Create Realtime Chat Connection

Create a short-lived realtime chat WebSocket connection token and return a ready-to-use wsUrl.

Use this endpoint when your backend should validate the license, avatar, domain/IP restrictions, and optional maximum call duration before opening the realtime WebSocket. The returned wsUrl points to /wss/v2/realtime-chat?token=... and can be used directly by the client.

Request rule: pass exactly one of avatarId or name. Do not pass both. Do not send model or voice in this token request; use the existing realtime session configuration flow after the WebSocket connects for session-level settings.

POST /api/open/v1/realtime-chat/connection

cURL

byAvatarId

curl --request POST \
  --url https://api.navtalk.ai/api/open/v1/realtime-chat/connection \
  --header 'Content-Type: application/json' \
  --header 'license: <api-key>' \
  --data '
{
  "avatarId": "8914367e-3892-4572-b345-e5023b0f03ec",
  "durationSeconds": 600
}
'

200

Example

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "wsUrl": "wss://transfer.navtalk.ai/wss/v2/realtime-chat?token=eyJhbGciOi...",
    "token": "eyJhbGciOi...",
    "expiresAt": 1781000000000,
    "expiresInSeconds": 300,
    "maxDurationSeconds": 600
  }
}

Use this endpoint to create a short-lived realtime chat WebSocket URL before starting a realtime digital human session.

The request must include exactly one avatar selector:

• avatarId: use a trained avatar ID for precise lookup
• name: use an avatar or system character name

durationSeconds is optional. When provided, it limits the maximum realtime call duration for the generated connection.

Do not send model or voice in this token request. Continue using the existing realtime session configuration flow after the WebSocket connects for session-level settings.

The response includes wsUrl, which can be passed directly to new WebSocket(wsUrl). The generated URL connects to /wss/v2/realtime-chat with a short-lived token.

The direct WebSocket flow is still supported. You can either call this REST endpoint first and connect with the returned wsUrl, or connect directly to /wss/v2/realtime-chat with license and either name or avatarId in the query string.

Use the returned wsUrl as-is. The service chooses the correct transfer host for the current environment and includes a short-lived token query parameter.

Authorizations

license · string · header · required

NavTalk API license key (e.g. sk_navtalk_...)

Body

application/json

Option 1

Option 2

Request body for creating a realtime chat WebSocket connection token. Pass exactly one of avatarId or name. Do not include model or voice in this token request.

avatarId · string · required

Avatar ID to connect to. Use this for precise avatar lookup.

Example:

"8914367e-3892-4572-b345-e5023b0f03ec"

name · string

Avatar or character name to connect to. If multiple avatars share this name, the service selects the first matching user avatar, then falls back to a system avatar.

Example:

"navtalk.Leo"

durationSeconds · integer<int64>

Optional maximum call duration in seconds. Must be greater than 0 when provided.

Required range: x >= 1

Example:

600

Response

200

application/json

Realtime chat connection created successfully

code · integer

Example:

200

message · string

Example:

"SUCCESS"

data · object

Show child attributes