Session Configuration

When you create a session — whether from an Omniagent or a per-session connection — you can pass additional settings that apply only to that session.

Memory and user identity

Pass an externalClientId to enable memory for the session. The agent remembers what was said and can pick up the conversation in future sessions with the same user.

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

Memory is scoped to a companion + external client ID pair:

• Same user + different companion = fresh memory
• Different externalClientId + same companion = treated as a new person
• Same externalClientId + same companion = recalls previous conversations

Use a stable, unique identifier from your system — such as a user ID or account ID.

The value must match ^[A-Za-z0-9_-]{1,32}$: English letters, digits, underscores, and hyphens only, up to 32 characters. If your internal identifiers don't fit (for example, UUIDs or email addresses), hash or map them to a compact ID before passing them to the API.

User context

The externalClientProfile field lets you pass structured information about the end user into the session. The agent can reference this data during the conversation to personalize its responses.

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",
    "externalClientProfile": {
      "name": "Jane",
      "plan": "premium",
      "company": "Acme Corp"
    }
  }'

The object is unstructured — include any fields that would help the agent tailor its behavior. For example, passing the user's name lets the agent greet them personally, and passing their subscription tier lets it adjust recommendations accordingly.

Opening instructions

The initialSpeech field gives the agent instructions on how to open the session — how it should start this conversation, before the user speaks. It's guidance, not a verbatim line: the agent follows the instruction in its own voice when the connection is established.

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",
    "initialSpeech": "Greet the customer warmly, introduce yourself as Acme Support, and ask what they need help with."
  }'

Because it's passed per connection, you can tailor the opening to the context of each session — for example, referencing what the user was doing when they started the conversation.

initialSpeech is available on every connection endpoint: POST /public/agents/{agentId}/connections, POST /public/connections, and POST /public/ws-connections.

Setting a default per channel

To open every session on a channel the same way, set initialSpeech on the channel config instead of on each connection. The value applies to all sessions created on that channel unless a connection request overrides it.

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/webrtc \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initialSpeech": "Greet the customer warmly, introduce yourself as Acme Support, and ask what they need help with."
  }'

Handling invalid configuration

Configuration problems surface at one of two points, depending on what's wrong. This applies to every connection endpoint: POST /public/agents/{agentId}/connections, POST /public/connections, and POST /public/ws-connections.

When you create the connection. The API returns a 400 for problems it can check itself — for example, a missing voiceId, a digital twin whose cloned voice isn't ready, or a tool, FAQ collection, or MCP server that doesn't exist. Handle the 400 on your backend: log the message, fix the configuration, and retry.

When the session starts. The AI provider checks the rest after your client connects — whether it recognizes the voice, accepts your credentials, and can handle the instructions' length. The connection request succeeds, and if the provider rejects the configuration, your client receives a provider_connection_aborted event and the session closes. Listen for it so you can report the failure instead of showing a dropped connection.

Green screen video

For WebRTC sessions, you can enable a green-screen background on the companion's video stream so you can composite the avatar over your own UI. This requires matching useGreenVideo on the channel config with an SDK init flag — see Green screen background on the WebRTC guide for the full setup.

Ending a session

To close a live session from your backend — for example, when a user's plan runs out mid-conversation or a kiosk needs to be freed — call DELETE /public/connections/{connectionId} with the connection.id you received when you opened the session:

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

The API returns 200 and the session ends right away. It then appears in sessions as closed with closeReason: "connection_aborted".

This works for webrtc, websocket, and kiosk sessions.