> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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.
## OpenAPI
````yaml POST /api/open/v1/realtime-chat/connection
openapi: 3.1.0
info:
title: NavTalk API
description: NavTalk API for AI avatar management, file uploads, and video generation
version: 1.0.0
servers:
- url: https://api.navtalk.ai
description: NavTalk Production Environment Server
- url: https://qaapi.navtalk.ai
description: NavTalk QA Environment Server
- url: https://devapi.navtalk.ai
description: NavTalk Development Environment Server
security:
- navtalkLicenseAuth: []
paths:
/api/open/v1/realtime-chat/connection:
post:
tags:
- Realtime Chat
summary: Create Realtime Chat Connection
description: >-
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.
operationId: createRealtimeChatConnection
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RealtimeConnectionRequest'
examples:
byAvatarId:
summary: Connect by avatar ID
value:
avatarId: 8914367e-3892-4572-b345-e5023b0f03ec
durationSeconds: 600
byName:
summary: Connect by avatar name
value:
name: navtalk.Leo
durationSeconds: 600
responses:
'200':
description: Realtime chat connection created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RealtimeConnectionResponse'
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
'400':
description: >-
License validation, avatar validation, domain restriction, or
parameter validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/NavtalkErrorResponse'
examples:
missingBody:
summary: Missing request body
value:
code: 400
message: Request body is required
missingOrDuplicateAvatarSelector:
summary: Missing or duplicate avatar selector
value:
code: 400
message: Exactly one of avatarId or name parameter is required
invalidDuration:
summary: Invalid duration
value:
code: 400
message: durationSeconds must be greater than 0
avatarNotFound:
summary: Avatar not found
value:
code: 400
message: >-
The requested character could not be found. The avatar
must be trained before use.
domainRestricted:
summary: Domain or IP not allowed
value:
code: 400
message: >-
Access from your domain or IP address is not allowed for
this license.
realtimeCallDisabled:
summary: Realtime calls disabled
value:
code: 400
message: >-
Your account is prohibited from making calls. Please
contact the administrator.
security:
- navtalkLicenseAuth: []
components:
schemas:
RealtimeConnectionRequest:
type: object
description: >-
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.
additionalProperties: false
properties:
avatarId:
type: string
description: Avatar ID to connect to. Use this for precise avatar lookup.
example: 8914367e-3892-4572-b345-e5023b0f03ec
name:
type: string
description: >-
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:
type: integer
format: int64
minimum: 1
description: >-
Optional maximum call duration in seconds. Must be greater than 0
when provided.
example: 600
oneOf:
- required:
- avatarId
not:
required:
- name
- required:
- name
not:
required:
- avatarId
RealtimeConnectionResponse:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: SUCCESS
data:
$ref: '#/components/schemas/RealtimeConnectionData'
NavtalkErrorResponse:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: Invalid license key
RealtimeConnectionData:
type: object
properties:
wsUrl:
type: string
description: Ready-to-use WebSocket URL. Connect to this URL directly.
example: wss://transfer.navtalk.ai/wss/v2/realtime-chat?token=eyJhbGciOi...
token:
type: string
description: Short-lived realtime connection token included in `wsUrl`.
example: eyJhbGciOi...
expiresAt:
type: integer
format: int64
description: Token expiration timestamp in milliseconds since Unix epoch.
example: 1781000000000
expiresInSeconds:
type: integer
format: int64
description: >-
Realtime connection token TTL in seconds. Default is 300 seconds
unless configured differently by the server.
example: 300
maxDurationSeconds:
type: integer
format: int64
nullable: true
description: >-
Optional maximum call duration embedded in the connection token.
Null when no duration limit was requested.
example: 600
securitySchemes:
navtalkLicenseAuth:
type: apiKey
in: header
name: license
description: NavTalk API license key (e.g. sk_navtalk_...)
````