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.

Green screen video

For WebRTC sessions, you can enable a green-screen background on the companion's video stream by setting useGreenVideo to true on the channel config. This lets you composite the video in your application.

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 '{
    "useGreenVideo": true
  }'