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

When a connection request contains invalid settings — an unsupported voiceId, malformed provider credentials, or a companion that isn't ready — the API returns a 400 response with a descriptive error explaining what to fix. The session is aborted immediately rather than connecting and then failing silently, so you get the reason back on the request instead of watching a session hang.

Handle the 400 on your backend before handing a token to the client: surface the message to your logs, correct the configuration, and retry.

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.