VoIP

VoIP is the simplest way to put your Omniagent on a phone number. Napster gives you a webhook URL — you register it with Twilio as the incoming-call webhook for a phone number. When someone calls, Twilio routes the call to Napster, and your agent answers.

No trunk credentials or SIP registration to manage — you bring your own Twilio account and phone number, and point it at Napster.

Twilio is currently the only supported VoIP provider. To use different telephony infrastructure, see the SIP channel.

How it works

Calls route from Twilio's webhook to your agent

Setting up VoIP

Enable the channel and register the voipEndpoint webhook

Channel overrides

VoIP-specific settings, tools, FAQs, and knowledge

Managing the VoIP channel

Get or remove the VoIP channel config

How it works

Caller → Your phone number (Twilio)
       → Incoming-call webhook → voipEndpoint (Napster)
       → Your Omniagent answers

You configure the VoIP channel once. Napster returns a voipEndpoint URL. You set that URL as the incoming-call webhook on your phone number in Twilio. Every call to that number is answered by your agent.

Setting up VoIP

Create an agent

If you don't already have one, create an agent. See Building Your Omniagent for the full walkthrough.

curl -X POST https://companion-api.napster.com/public/agents \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "name": "Phone Support Agent",
    "voiceId": "alloy",
    "providerSettings": {
      "temperature": 0.7,
      "turnDetection": {
        "threshold": 0.9,
        "silence_duration_ms": 800
      }
    }
  }'

For phone calls, a longer silence_duration_ms (e.g. 800ms) works better than the default 500ms. Phone audio quality is lower and callers tend to pause more.

Enable the VoIP channel

Call PUT /public/agents/{agentId}/channels/voip. The request body can be empty, or include per-channel overrides for provider settings, tools, knowledge, or FAQs.

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/voip \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "chanconfig_abc123",
  "channelType": "voip",
  "voipEndpoint": "https://companion-api.napster.com/voip/webhook/abc123",
  "created": 1710000001
}

The voipEndpoint is the URL you need for the next step.

Register the webhook with Twilio

Take the voipEndpoint from the response and set it as the incoming-call webhook for your phone number in the Twilio Console:

Go to Phone Numbers → Manage → Active Numbers and select your number.
Under Voice Configuration, set the voipEndpoint URL as the "A call comes in" webhook.
Save the configuration.

Once set, any call to that phone number is routed to your agent.

Test it

Call the phone number. Your agent should answer. If it doesn't, verify:

The voipEndpoint is correctly set as the webhook in Twilio
The agent has a valid companionId (and voiceId if not using a digital twin)
Your API key is active

Channel overrides

You can override the agent's default settings specifically for VoIP calls. Include any of these fields when enabling the channel:

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/voip \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerSettings": {
      "turnDetection": {
        "silence_duration_ms": 800
      }
    },
    "functions": ["fn_phone_only_tool"],
    "faqCollections": ["faq_phone_support"]
  }'

Field	Description
`providerSettings`	Override temperature, turn detection, noise reduction for phone calls
`functions`	Use different tools for phone vs web
`faqCollections`	Use different FAQs for phone vs web
`knowledgeBaseId`	Use a different knowledge base for phone
`useWebSearch`	Enable or disable web search for phone calls

If omitted, the agent's base configuration is used.

Managing the VoIP channel

# Get current VoIP config
curl https://companion-api.napster.com/public/agents/agent_abc123/channels/voip \
  -H "X-Api-Key: $NAPSTER_API_KEY"

# Remove VoIP channel
curl -X DELETE https://companion-api.napster.com/public/agents/agent_abc123/channels/voip \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Deleting the VoIP channel invalidates the voipEndpoint. Calls to the phone number will no longer be routed to your agent.

VoIP

How it works

Setting up VoIP

Channel overrides

Managing the VoIP channel

On this page