From SIP Agents to Omniagent

The SIP-specific agent model has been replaced by a channel-agnostic architecture. If you have an existing SIP integration using /public/sip-agents, this guide walks you through every change you need to make.

What changed

The old SIP Agent resource bundled everything into a single object — companion config, voice, human handoff, and SIP-specific settings. The new model splits this into two resources:

Before (SIP Agent model)	After (Agent model)
SIP Agent (`/public/sip-agents`)	Agent (`/public/agents`) — companion, voice, language, tools, FAQs, knowledge, and provider settings. Works across SIP, WebRTC, and WebSocket.
(part of SIP Agent)	SIP Channel Config (`/public/agents/{agentId}/channels/sip`) — SIP-specific overrides: human handoff and optional resource overrides.
SIP Connection (`/public/sip-connections`)	SIP Connection (`/public/sip-connections`) — unchanged, but now references `agentId` instead of `sipAgentConfigurationId`.

Before:                              After:

SIP Agent                            Agent (channel-agnostic)
  ├── SIP Connection A                 └── SIP Channel Config
  ├── SIP Connection B                       ├── SIP Connection A
  └── SIP Connection C                       ├── SIP Connection B
                                             └── SIP Connection C

Endpoint mapping

Each old SIP Agent operation now maps to the Agent endpoint, the SIP Channel Config endpoint, or both.

Old endpoint	New endpoint(s)
`POST /public/sip-agents`	`POST /public/agents` then `PUT /public/agents/{agentId}/channels/sip` — create the agent first, then set up the SIP channel config.
`GET /public/sip-agents`	`GET /public/agents` — returns all agents. Use `GET /public/agents/{agentId}/channels/sip` to fetch SIP-specific overrides for a given agent.
`PATCH /public/sip-agents/{id}`	`PATCH /public/agents/{agentId}` for agent-level fields. `PUT /public/agents/{agentId}/channels/sip` for SIP-only fields (`humanHandoff`, channel overrides).
`DELETE /public/sip-agents/{id}`	`DELETE /public/agents/{agentId}` removes the agent for all channels. `DELETE /public/agents/{agentId}/channels/sip` keeps the agent, only removes SIP overrides.

Migration steps

Create an Agent from your SIP Agent config

Take the fields from your existing POST /public/sip-agents call and restructure them for POST /public/agents.

Before:

curl -X POST https://companion-api.napster.com/public/sip-agents \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "name": "Support Agent",
    "language": "English",
    "functions": ["fn_order_status", "fn_returns"],
    "providerSettings": {
      "voiceId": "alloy",
      "temperature": 0.7
    },
    "humanHandoff": {
      "enabled": true,
      "transferExtension": "200",
      "transferDescription": "Transfer when the caller asks for a human"
    }
  }'

After:

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"],
    "providerSettings": {
      "temperature": 0.7
    }
  }'

Three things changed:

Endpoint: /public/sip-agents → /public/agents
voiceId: Moved from inside providerSettings to a top-level field
humanHandoff: Removed from the agent — you configure this in the next step

Set up the SIP channel config

The SIP channel config is required for SIP to work, even if you don't use human handoff. It registers the SIP channel for the agent under your API key. If you previously had humanHandoff on your SIP Agent, move it here.

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"
    }
  }'

If you don't need human handoff, send an empty body:

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 '{}'

The humanHandoff object itself is unchanged — same fields, same behavior. It just lives in a different place.

You can also use this channel config to override agent-level functions, faqCollections, knowledgeBaseId, and providerSettings specifically for SIP calls. If omitted, the agent's base config is used.

Update SIP Connection references

Your SIP connection payloads need one field renamed.

Before: "sipAgentConfigurationId": "sipagent_abc123"

After: "agentId": "agent_abc123"

Everything else about SIP connections (settings, status, errors) stays the same.

Update management calls

Agent-level fields (voiceId, language, functions, providerSettings, etc.) go to the Agent endpoint. SIP-specific fields (humanHandoff, channel overrides) go to the SIP Channel Config endpoint.

When updating an agent, remember that voiceId is now a top-level field: