Realtime Agent

Register a realtime agent call

Changed on

Mint a short-lived, single-use access token for opening a realtime Agent WebSocket connection. This is the recommended way to start a session from a browser or other client-side app: your API key stays server-side, and the browser only ever sees the short-lived token. (Server-side or trusted clients may instead connect to the WebSocket with a raw API key directly.)

Flow:

  1. Call this endpoint with your API key and the agent_id (plus optional mode and per-call variables). All session configuration is fixed here — it is baked into the returned token.
  2. Open a WebSocket to wss://api.smallest.ai/atoms/v1/agent/connect?token=<access_token>. No agent_id, mode, or variables query params are needed on the WebSocket — they come from the token.

The token is valid for expires_in seconds (30) and can be used for a single connection. Request a fresh token for each connection.

post/conversation/register-call

Request

  • Base URL
    https://api.smallest.ai/atoms/v1
  • URL
    https://api.smallest.ai/atoms/v1/conversation/register-call
  • Auth
    HTTP bearer

Request body

agent_idstring required

The Atoms agent to connect to.

mode'webcall' | 'chat'

Session mode. webcall = full voice pipeline (audio in + audio out). chat = text-only pipeline. Defaults to webcall.

sample_rate8000 | 16000 | 24000 | 44100

Deprecated. Use output_audio_format instead. Still accepted, and will keep being accepted - existing integrations do not need to change.

A bare rate meaning PCM at that rate, so sample_rate: 24000 and output_audio_format: "pcm_24000" are the same request. It predates the one-token-per-direction contract and is the reason two fields exist for one thing. 44100 is only rendered by the lightning-v3.1 and lightning-v3.1-pro voices; asking for a rate the agent's voice cannot render is refused here rather than failing mid-call. This does not set the rate of the audio you send - use input_audio_format.

input_audio_format'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'pcm_48000' | 'mulaw_8000' | 'alaw_8000' | 'opus_8000' | 'opus_16000' | 'opus_24000' | 'opus_48000'

The format you will send, as one <encoding>_<rate> token naming both the encoding and the rate. Defaults to PCM at the output rate, so a client sending only sample_rate needs nothing else.

The recogniser is configured at this rate and your audio is not resampled, so the token must match the bytes you send: a mismatch produces wrong transcripts and no error. G.711 exists only at 8000. Opus is raw packets, one per WebSocket message; Ogg-framed Opus is a different format and is refused.

A browser client can also declare this later, on the connect URL, once its AudioContext reports the rate it actually got.

output_audio_format'pcm_8000' | 'pcm_16000' | 'pcm_24000' | 'pcm_44100'

The format the agent sends back. Same token shape as input_audio_format. Sending this together with sample_rate is allowed only if they agree; disagreeing values are refused rather than resolved by a precedence rule.

variablesobject

Per-call prompt variables that override the agent's defaultVariables for this session only. Values must be string, number, or boolean. Reserved system-variable keys (call_id, conversation_type, agent_number, user_number, current_date, current_time, current_day, agent_gender, default_language, supported_languages, timezone) are populated by the server and stripped if supplied.

Example request

{
  "agent_id": "69da0b4c20c0e03cfa4ee258",
  "sample_rate": 24000,
  "input_audio_format": "pcm_24000",
  "output_audio_format": "pcm_24000",
  "variables": {
    "customer_name": "Tanay",
    "account_tier": "gold"
  }
}

Response

Access token created.

statusboolean

Example response

{
  "status": true,
  "data": {
    "access_token": "wct_9f8c2b1e-4d5a-4e6f-a7b8-c9d0e1f2a3b4",
    "expires_in": 30,
    "sample_rate": 24000,
    "input_audio_format": "pcm_24000",
    "output_audio_format": "pcm_24000"
  }
}

Changes

  • 0376bd120f3bRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • ce6edcbc6fc8Revision changes
    • info

      endpoint added