---
title: "Register a realtime agent call"
method: POST
path: "/conversation/register-call"
tags: ["Realtime Agent"]
---

# Register a realtime agent call

`POST /conversation/register-call`

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.

## Request body

- object
  - `agent_id` string, 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`.
  - `variables` object — 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.

## Response `201`

Access token created.

- object
  - `status` boolean
  - `data` object
    - `access_token` string — Short-lived, single-use token (prefixed `wct_`). Pass it as the `token` query param when opening the Agent WebSocket.
    - `expires_in` integer — Token lifetime in seconds.
    - `sample_rate` integer — Negotiated audio sample rate (Hz) for the session. Echoed back in the WebSocket `session.created` event.

## Other responses

- `400` — Validation failed (e.g. missing `agent_id`), or the organization has no remaining credits.
- `401` — Unauthorized access
- `404` — Resource not found. The referenced ID does not exist or does not belong to the caller's organization.
- `500` — Internal server error

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/c2d0eb64b01a/schema)