SIP

SIP connections are currently in private preview and available only by request. Contact us to enable SIP for your account.

SIP integration lets your Omniagent answer incoming phone calls. You register a SIP extension with the Omniagent API, and every call to that extension is picked up by your agent — the same agent you can deploy to WebRTC and WebSockets.

Unlike WebRTC and WebSocket connections — which are created per session — SIP is a persistent setup. You configure it once, and the agent answers calls continuously until you remove the configuration.

How it works

SIP uses three resources that you manage separately:

Resource	What it defines
Agent	Who answers the call — the companion, voice, language, tools, FAQs, knowledge, and provider settings. Agents are channel-agnostic and can be used across SIP, WebRTC, and WebSocket.
SIP Channel Config	SIP-specific overrides — configures human handoff. Can optionally override the agent's default resources and provider settings for SIP calls.
SIP Connection	Where to listen for calls — the SIP credentials (server, port, domain, username, password, transport) that connect to your telephony provider.

A SIP Connection links to an Agent. One agent can serve multiple connections — for example, the same agent answering on different phone numbers or extensions.

Agent (companion + voice + config)
  └── SIP Channel Config (human handoff)
        ├── SIP Connection A (extension 101)
        ├── SIP Connection B (extension 102)
        └── SIP Connection C (extension 103)

Setting up SIP

Create an Agent

Define which companion answers and how it behaves. The agent holds the base configuration that applies across all channels.

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": "Support Agent",
    "voiceId": "alloy",
    "language": "English",
    "functions": ["fn_order_status", "fn_returns"],
    "faqCollections": ["faq_support"],
    "knowledgeBaseId": "kb_product_docs",
    "providerSettings": {
      "temperature": 0.7,
      "turnDetection": {
        "threshold": 0.9,
        "silence_duration_ms": 500
      }
    }
  }'

Response:

{
  "id": "agent_abc123",
  "companionId": "comp_abc123",
  "name": "Support Agent",
  "voiceId": "alloy",
  "language": "English",
  "functions": ["fn_order_status", "fn_returns"],
  "faqCollections": ["faq_support"],
  "knowledgeBaseId": "kb_product_docs",
  "providerSettings": {
    "temperature": 0.7,
    "turnDetection": {
      "threshold": 0.9,
      "silence_duration_ms": 500
    }
  },
  "created": 1710000000
}

Parameter	Type	Required	Description
`companionId`	string	Yes	The companion that answers calls.
`name`	string	No	A label for this agent.
`voiceId`	string	Yes	The voice to use for the agent's speech output (e.g. `alloy`, `echo`, `shimmer`).
`language`	string	No	Lock the agent to a specific language (e.g. `English`, `Spanish`). If omitted, defaults to English but can switch when asked.
`functions`	string[]	No	Tool IDs to attach.
`faqCollections`	string[]	No	FAQ collection IDs.
`knowledgeBaseId`	string	No	Knowledge collection ID.
`providerSettings`	object	Yes	Model and audio settings — `temperature`, `turnDetection`, `noiseReduction`. See Configuration for details.

Set up the SIP channel

This step is required even if you don't need human handoff — it registers the SIP channel for the agent under your API key. Without it, SIP connections cannot route calls to the agent.

This uses PUT — it creates the channel config if it doesn't exist, or updates it if it does.

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/sip \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "humanHandoff": {
      "enabled": true,
      "transferExtension": "200",
      "transferDescription": "Transfer when the caller asks for a human or the issue cannot be resolved"
    }
  }'

Response:

{
  "id": "chanconfig_abc123",
  "apiKeyId": "key_abc123",
  "channelType": "sip",
  "humanHandoff": {
    "enabled": true,
    "transferExtension": "200",
    "transferDescription": "Transfer when the caller asks for a human or the issue cannot be resolved"
  },
  "created": 1710000001
}

Parameter	Type	Required	Description
`humanHandoff`	object	No	Configure live agent transfer. See Human handoff below.
`functions`	string[]	No	Override the agent's default tool IDs for SIP calls.
`faqCollections`	string[]	No	Override the agent's default FAQ collection IDs for SIP calls.
`knowledgeBaseId`	string	No	Override the agent's default knowledge collection for SIP calls.
`providerSettings`	object	No	Override the agent's default provider settings for SIP calls.

The channel config fields for functions, faqCollections, knowledgeBaseId, and providerSettings are optional overrides. If omitted, the agent's base configuration is used.

Create a SIP Connection

Provide the SIP credentials from your telephony provider and link them to the agent. This deploys a listener that registers with your SIP server and starts accepting calls.

curl -X POST https://companion-api.napster.com/public/sip-connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "name": "Main Support Line",
    "settings": {
      "server": "sip.your-provider.com",
      "port": 5060,
      "domain": "your-provider.com",
      "username": "your-sip-username",
      "password": "your-sip-password",
      "transport": "TCP",
      "callerId": "support-line-01"
    }
  }'

Response:

{
  "id": "sipconn_abc123",
  "agentId": "agent_abc123",
  "name": "Main Support Line",
  "settings": {
    "server": "sip.your-provider.com",
    "port": 5060,
    "domain": "your-provider.com",
    "username": "your-sip-username",
    "transport": "TCP",
    "callerId": "support-line-01"
  },
  "status": {
    "lifecycleStatus": "Pending",
    "sipStatus": null,
    "message": null,
    "lastRefreshed": 1710000005
  },
  "created": 1710000005
}

Parameter	Type	Required	Description
`agentId`	string	Yes	The agent to use for incoming calls on this connection.
`name`	string	No	A label for this connection.
`settings.server`	string	Yes	Your SIP provider's server address.
`settings.port`	integer	Yes	The SIP server port (typically `5060`).
`settings.domain`	string	Yes	The SIP domain.
`settings.username`	string	Yes	Your SIP account username.
`settings.password`	string	Yes	Your SIP account password. Only sent on creation — not returned in responses.
`settings.transport`	string	Yes	The transport protocol (e.g. `TCP`).
`settings.callerId`	string	No	A unique identifier for this connection on your SIP server. Not a phone number shown to callers.

Check connection status

After creating a connection, the Omniagent API deploys a listener and registers it with your SIP server. The status object tracks two independent states:

lifecycleStatus — whether the listener itself is deployed and running.
sipStatus — whether the listener has successfully registered with your SIP provider.

Both must be healthy for the agent to receive calls.

curl -X POST https://companion-api.napster.com/public/sip-connections/sipconn_abc123/status \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Response:

{
  "status": {
    "lifecycleStatus": "Running",
    "sipStatus": "online",
    "message": null,
    "lastRefreshed": 1710000010
  },
  "created": 1710000005
}

Lifecycle status

Tracks whether the listener is deployed and running.

Value	Description
`Pending`	The listener is being provisioned.
`Running`	The listener is up and operational.
`Failed`	The listener failed to start. Check `status.message` for details.
`Error`	The listener encountered a runtime error. Check `status.message` for details.
`Unknown`	The state could not be determined.

SIP status

Tracks the SIP registration state. This is only relevant once lifecycleStatus is Running.

Value	Description
`registering`	The listener is running but has not yet registered with your SIP provider.
`online`	Registered and ready to receive calls.
`calling`	Registered and an active call is in progress.

Once lifecycleStatus is Running and sipStatus is online, your agent is live — incoming calls to your SIP extension are answered by the companion.

Troubleshoot registration errors

If lifecycleStatus is Running but sipStatus stays on registering and never transitions to online, the listener is up but failing to register with your SIP provider. Use the errors endpoint to retrieve recent error logs for the connection.

curl https://companion-api.napster.com/public/sip-connections/sipconn_abc123/errors \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Response:

[
  {
    "timestamp": "2025-03-10T12:00:05Z",
    "message": "SIP registration failed: 401 Unauthorized",
    "code": 401
  }
]

Field	Type	Description
`timestamp`	string	When the error occurred.
`message`	string	A human-readable description of the error.
`code`	integer	The error or SIP response code.

Common issues include incorrect credentials (401), unreachable server, or wrong transport protocol. Double-check the settings on your SIP Connection if registration fails.

Human handoff

The humanHandoff setting lets the agent transfer a call to a live person over SIP. When enabled, the agent can initiate a SIP transfer to the extension you specify.

Human handoff is configured on the SIP channel config (the same PUT call used during channel setup). You can include it when you first create the channel config, or add it later by updating the same endpoint:

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/sip \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "humanHandoff": {
      "enabled": true,
      "transferExtension": "200",
      "transferDescription": "Transfer when the caller asks for a human or the issue cannot be resolved"
    }
  }'

Parameter	Type	Required	Description
`humanHandoff.enabled`	boolean	No	Set to `true` to allow the agent to transfer calls.
`humanHandoff.transferExtension`	string	No	The SIP extension to transfer the call to.
`humanHandoff.transferDescription`	string	No	A description of when or why to transfer — the agent uses this to decide when a handoff is appropriate.

When enabled is true and a transferExtension is set, the agent can transfer the caller during the conversation. The transferDescription field is critical — it directly controls when and how the agent initiates the transfer. Write it as a clear instruction to the agent, for example: "Transfer the caller to a human operator when they explicitly ask to speak with a real person. Before calling this function, tell the caller you are transferring them and ask them to wait."

The transferDescription is not just a label — the agent uses it to decide when a handoff is appropriate and what to say to the caller before transferring. Be specific about the conditions and the behavior you expect.

Managing your agent

For listing, updating, and deleting agents and channel configs, see Managing Your Agent.

Managing SIP Connections

You can list, update, and delete your SIP connections:

# List all SIP connections
curl https://companion-api.napster.com/public/sip-connections \
  -H "X-Api-Key: $NAPSTER_API_KEY"

# Update a SIP connection
curl -X PATCH https://companion-api.napster.com/public/sip-connections/sipconn_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Support Line"
  }'

# Delete a SIP connection
curl -X DELETE https://companion-api.napster.com/public/sip-connections/sipconn_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Deleting a connection stops the listener and unregisters from your SIP server.

SIP

On this page