Skip to navigation
Runtime & dataMessaging API

Sessions and authentication

Before opening a WebSocket, you obtain an access token and create a session.

Obtain an access token

Exchange your connector token for a short-lived JWT access token.

POST /api/v1/access-token

Headers

HeaderRequiredDescription
X-TokenYesYour connector token (provided by PolyAI)
X-HostYesThe domain or app namespace you registered when generating the token (e.g. https://www.yourcompany.com or com.yourcompany.app). Must match exactly.
Content-TypeYesapplication/json

Request body

{}

Response — 200 OK

{
  "access_token": "eyJhbGc...",
  "expires_in": 86400,
  "token_type": "Bearer"
}
FieldTypeDescription
access_tokenstringJWT to use for all subsequent requests
expires_inintegerSeconds until the token expires
token_typestringAlways "Bearer"

Use this token in two places:

Treat the access token as sensitive. Do not log it, store it in localStorage, or expose it to third-party scripts. Always connect over wss:// (TLS).

Create session

A session represents one conversation. Create a session before opening a WebSocket.

POST /api/v1/sessions

Headers

HeaderRequiredDescription
AuthorizationYesBearer <access_token> from the previous step
Content-TypeYesapplication/json
User-AgentNoThe browser or device user agent

Request body (optional)

{
  "platform": "web",
  "streaming_enabled": true
}
FieldTypeDefaultDescription
streaming_enabledbooleanfalseWhen true, agent responses arrive as a series of incremental chunks. When false, each response arrives as a single complete message. See Streaming.
platformstringwebOne of web, ios, android, ios-web, android-web, or custom. Use ios / android from native SDKs that post to this endpoint directly. The webchat script reports web, ios-web, or android-web automatically based on its data-platform attribute — you don’t need to set this field when embedding the script.

The request body is optional — if omitted, streaming_enabled defaults to false.

Response — 200 OK

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Keep the session_id — you need it to open the WebSocket and to reconnect if the connection drops.

Sessions expire after roughly 10 minutes of inactivity. After expiry, create a new session — you cannot resume an expired session.