From Per-Session Connections to Omniagent

If you're currently using POST /public/connections (WebRTC) or POST /public/ws-connections (WebSocket) to create sessions, this guide walks you through migrating to the Omniagent model.

Why migrate

With per-session connections, you pass the full configuration — companion, voice, tools, knowledge, provider settings — on every request. With an Omniagent, you define that configuration once and create sessions with a minimal call. Benefits:

Less code per session — one field (channelType) instead of repeating the full config
Consistency — same agent across WebRTC, WebSocket, and SIP
Update once — change the voice or swap a tool, every channel picks it up
Memory across channels — the same user can talk to the same agent on web and phone

The per-session endpoints (POST /public/connections and POST /public/ws-connections) are not deprecated. They still work and are available for prototyping or one-off sessions.

Migration steps

Create an Omniagent

Take the fields from your existing connection request and use them to create an agent:

Before — passed on every session:

curl -X POST https://companion-api.napster.com/public/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "language": "English",
    "functions": ["fn_order_status", "fn_returns"],
    "faqCollections": ["faq_support"],
    "knowledgeBaseId": "kb_product_docs",
    "providerConfig": {
      "voiceId": "alloy",
      "settings": {
        "temperature": 0.7
      }
    }
  }'

After — created once:

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

Key differences:

voiceId moves from providerConfig.voiceId to a top-level field
providerConfig.settings becomes providerSettings (top-level, flattened)
name is new — an optional label for the agent

Replace session creation calls

Replace your POST /public/connections or POST /public/ws-connections calls with POST /public/agents/{agentId}/connections.

WebRTC — before:

curl -X POST https://companion-api.napster.com/public/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "functions": ["fn_order_status"],
    "providerConfig": {
      "voiceId": "alloy",
      "settings": { "temperature": 0.7 }
    },
    "externalClientId": "user_12345"
  }'

WebRTC — after:

curl -X POST https://companion-api.napster.com/public/agents/agent_abc123/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "webrtc",
    "externalClientId": "user_12345"
  }'

WebSocket — before:

curl -X POST https://companion-api.napster.com/public/ws-connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "functions": ["fn_order_status"],
    "providerConfig": {
      "voiceId": "alloy",
      "settings": { "temperature": 0.7 }
    },
    "externalClientId": "user_12345"
  }'

WebSocket — after:

curl -X POST https://companion-api.napster.com/public/agents/agent_abc123/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "websocket",
    "externalClientId": "user_12345"
  }'

Both channels use the same endpoint — only channelType differs. The response returns the same token and connection object. Your SDK integration and WebSocket connection code stays the same.

Handle session-specific fields

Some fields from the old connection request are passed per session, not on the agent:

Field	Where it goes
`externalClientId`	Pass on `POST /public/agents/{agentId}/connections`
`externalClientProfile`	Pass on `POST /public/agents/{agentId}/connections`
`tags`	Set on the agent (`POST/PATCH /public/agents/{agentId}`) or per-session (`POST /public/agents/{agentId}/connections`)
`disableIdleTimeout`	Set on the agent (`POST/PATCH /public/agents/{agentId}`)
`providerConfig.useGreenVideo`	Set on the channel config (`PUT /public/agents/{agentId}/channels/{channelType}`) as `useGreenVideo`

Field mapping

Per-session connection field	Agent field
`companionId`	`companionId`
`providerConfig.voiceId`	`voiceId` (top-level)
`providerConfig.settings.*`	`providerSettings.*` (top-level)
`language`	`language`
`functions`	`functions`
`faqCollections`	`faqCollections`
`knowledgeBaseId`	`knowledgeBaseId`