Register Call | Smallest AI Docs

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:

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.
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.

Mint a **short-lived, single-use access token** for opening a realtime [Agent WebSocket](/atoms/api-reference/realtime-agent/realtime-agent) 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.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Request

This endpoint expects an object.

agent_idstringRequired

The Atoms agent to connect to.

modeenumOptionalDefaults to webcall

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

Allowed values:

input_audio_formatenumOptional

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.

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_formatenumOptionalDefaults to pcm_24000

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.

Allowed values:

variablesmap from strings to strings or doubles or booleansOptional

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.

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.

sample_rateenumOptionalDefaults to 24000Deprecated

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.

**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`.

Allowed values:

Response

Access token created.

statusbooleanOptional

dataobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

500

Internal Server Error

1	import requests
2
3	url = "https://api.smallest.ai/atoms/v1/conversation/register-call"
4
5	payload = { "agent_id": "69da0b4c20c0e03cfa4ee258" }
6	headers = {
7	"Authorization": "Bearer <token>",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.post(url, json=payload, headers=headers)
12
13	print(response.json())

1	{
2	"status": true,
3	"data": {
4	"access_token": "wct_9f8c2b1e-4d5a-4e6f-a7b8-c9d0e1f2a3b4",
5	"expires_in": 30,
6	"sample_rate": 24000,
7	"input_audio_format": "pcm_24000",
8	"output_audio_format": "pcm_24000"
9	}
10	}