Request a session token

Snapshot: 0.9.17-patch1 · selected operations. This is a stored schema reference, not a fresh export or confirmation of behavior in another release. Scope and availability.

Availability and authentication

API access must be enabled for your deployment. Ask the platform administrator to confirm availability and the required API-key scope documented in the operation description below. Send the team API key in the X-API-Key header. Enabled interaction modes depend on endpoint runtime capabilities; the export profile does not enable them in your deployment.

POST /api/v1/sessions/token

Issues a runtime session id and a short-lived WebSocket token for the requested SDK mode.

After this call, connect the browser SDK to: /ws/session?sessionId={sessionId}&token={wsToken}

WebSocket wire format:

Messages use the ChannelMessage envelope (see components.schemas.ChannelMessage).
The server sends an initial status message with state=connected.

WebSocket close codes:

4001 — missing sessionId or token
4003 — invalid token or expired session
4000 — superseded by a newer connection
4500 — internal server error

Authentication: requires a team API key with CREATE_CALL_TOKEN scope.

voice_conversation responses also include WebRTC gateway metadata (telproDomain, webrtcGatewayUrl).

For the message envelope named above, see ChannelMessage.

Request body

Required: yes.

application/json

Required means required within its containing object. Exact schema below retains all constraints and alternatives.

Field	Type	Required	Description	Constraints
`endpointId`	string	Yes	Endpoint to open a session against. It must belong to the API key team.	format: "uuid"
`mode`	string	Yes	Session mode to provision: text chat, browser TTS playback, WebRTC voice, browser action dispatch, or interpretation listening.	enum: ["text","audio_playback","voice_conversation","browser_actions","listen"]

Exact request schema and examples

{
  "schema": {
    "type": "object",
    "required": [
      "endpointId",
      "mode"
    ],
    "properties": {
      "endpointId": {
        "type": "string",
        "format": "uuid",
        "description": "Endpoint to open a session against. It must belong to the API key team.",
        "example": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f"
      },
      "mode": {
        "type": "string",
        "enum": [
          "text",
          "audio_playback",
          "voice_conversation",
          "browser_actions",
          "listen"
        ],
        "description": "Session mode to provision: text chat, browser TTS playback, WebRTC voice, browser action dispatch, or interpretation listening."
      }
    }
  },
  "examples": {
    "request_text_capability": {
      "summary": "Request a text session",
      "value": {
        "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
        "mode": "text"
      }
    },
    "request_audio_playback_capability": {
      "summary": "Request an audio playback session",
      "value": {
        "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
        "mode": "audio_playback"
      }
    },
    "request_voice_capability": {
      "summary": "Request a voice conversation session",
      "value": {
        "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
        "mode": "voice_conversation"
      }
    },
    "request_browser_actions_capability": {
      "summary": "Request a browser actions session",
      "value": {
        "endpointId": "0f6c3d4e-8b8f-4c59-9d0e-7e5e3b1f7f0f",
        "mode": "browser_actions"
      }
    }
  }
}

Responses

These are declared schema responses, not results of live requests. An example is illustrative, not a complete catalogue of possible errors.

Status	Description
200	Default Response
400	Request validation failed
401	API key is missing or invalid
403	Forbidden: wrong team, origin/IP rejected, missing scope, or subscription limit reached
404	Endpoint not found
409	Endpoint flow is not configured or not synced for the requested mode
429	Too many requests
500	Unexpected server error
503	voice_conversation requested but TelPro is not configured

200

Default Response

Content type: application/json.

Required means required within its containing object. Exact schema below retains all constraints and alternatives.

Field	Type	Required	Description	Constraints
`sessionId`	string	Yes	The runtime session id (also the X-Call-ID for voice)	—
`wsToken`	string	Yes	WebSocket token for /ws/session authentication	—
`wsTokenExpiresIn`	number	Yes	WS token validity in seconds (5 min)	—
`expiresIn`	number	Yes	Session token validity in seconds	—
`telproDomain`	string	No	WebRTC gateway / TURN / STUN host (voice_conversation only)	—
`webrtcGatewayUrl`	string	No	WebSocket URL of the WebRTC gateway (voice_conversation only)	—
`traceId`	string	No	OpenTelemetry trace id returned for voice_conversation sessions.	—
`spanId`	string	No	OpenTelemetry root span id returned for voice_conversation sessions.	—