VoIP

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

No trunk credentials, no SIP registration, no infrastructure to manage.

How it works

Caller → Your phone number (Twilio/Telnyx/Vonage)
       → 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 at your VoIP provider. 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 your VoIP provider

Take the voipEndpoint from the response and set it as the incoming-call webhook for your phone number at your VoIP provider. The exact location varies by provider:

Provider	Where to set it
Twilio	Phone Numbers → Manage → Active Numbers → select number → Voice Configuration → set the `voipEndpoint` as the "A call comes in" webhook
Telnyx	Voice → Call Control Applications → create or edit an application → set the `voipEndpoint` as the webhook URL → then assign your phone number to the application under Numbers → My Numbers
Vonage	Applications → create or select an application → enable Voice → set the `voipEndpoint` as the Answer URL → then link your phone number to the application under Numbers → Your Numbers

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

Twilio lets you set the webhook directly on a phone number. Telnyx and Vonage both use an intermediary resource (application/connection) where you configure the webhook, then associate phone numbers with it.

Test it

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

The voipEndpoint is correctly set as the webhook at your provider
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

On this page