ANanam
Sessions

create session token

Changed on

Create a new session token used to initialise Anam client side SDKs

post/v1/auth/session-token

Request

  • Base URL
    https://api.anam.ai
  • URL
    https://api.anam.ai/v1/auth/session-token
  • Auth
    HTTP bearer

Request body

clientLabelstring

The client label for the session

maxSessionsinteger

The most sessions the token can start. Omit it for no limit (the default). Each call to POST /v1/engine/session with the token counts, including one that fails, so set maxSessions: 1 only when your client starts the session once and gets a new token to retry. The Anam JS SDK retries a failed start up to 3 times by default: send maxSessions: 3, or set the SDK's retry.maxAttempts to 1. Reconnects and ICE restarts within a session don't count. Once the limit is reached, session start returns 401. If the API key has its own limit, the lower of the two applies.

expiresInSecondsinteger

How long the token can start sessions, in seconds, from 120 (2 minutes) to 3600 (1 hour). Omit it for one hour. The token is checked only when a session starts: once it expires, POST /v1/engine/session returns 401, but a session it already started keeps running until it ends. Start the session within this time, including any retries your client makes.

Example request

{
  "maxSessions": 1,
  "expiresInSeconds": 300,
  "personaConfig": {
    "name": "Cara",
    "avatarId": "071b0286-4cce-4808-bee2-e642f1062de3",
    "avatarModel": "cara-4",
    "voiceId": "de23e340-1416-4dd8-977d-065a7ca11697",
    "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
    "systemPrompt": "You are a helpful assistant",
    "maxSessionLengthSeconds": 600,
    "initialMessage": "Hi there! I'm excited to chat with you today.",
    "voiceDetectionOptions": {
      "endOfSpeechSensitivity": 0.5,
      "silenceBeforeSkipTurnSeconds": 5,
      "silenceBeforeSessionEndSeconds": 60,
      "silenceBeforeAutoEndTurnSeconds": 5,
      "speechEnhancementLevel": 0.8,
      "sttProvider": "anam"
    },
    "voiceGenerationOptions": {
      "stability": 0.5,
      "speed": 1,
      "pronunciationDictionaryId": "4f600129-13cf-4bfa-909a-2f4c31467f43"
    },
    "directorNotes": {
      "presetStyle": "warm",
      "customStylePrompt": "Warm smile, composed, slightly amused, looking directly at camera",
      "expressivity": 0.5,
      "customIdlingStylePrompt": "Listen attentively, nod slowly, soft relaxed gaze"
    },
    "tools": [
      {
        "type": "client",
        "name": "open_calendar",
        "description": "Open the calendar UI in the client app.",
        "parameters": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "description": "Date to jump to, in YYYY-MM-DD format."
            }
          }
        }
      },
      {
        "type": "server",
        "subtype": "knowledge",
        "name": "search_docs",
        "description": "Search the knowledge base for relevant documents.",
        "config": {
          "documentFolderIds": [
            "67d27a9f-0ce1-4432-848b-8ab2b97f024b"
          ]
        }
      }
    ]
  },
  "sessionOptions": {
    "sessionReplay": {
      "enableSessionReplay": true
    },
    "dataRetention": {
      "transcripts": true
    },
    "videoQuality": "high",
    "showAIAvatarDisclosure": true,
    "videoWidth": 1152,
    "videoHeight": 768,
    "egress": {
      "mode": "daily",
      "daily": {
        "roomUrl": "https://your-domain.daily.co/avatar-room"
      }
    }
  }
}

Response

Successfully started session

sessionTokenstring

Signed JWT the client passes to the Anam SDK to open a WebRTC connection.

Changes