Agent WebSocket

A bidirectional session with an Atoms agent. Mint an access token, open the connection with it, and the server creates a session, bridges audio and transcripts to the STT/LLM/TTS pipeline, and streams events back until the client closes or the server ends the session.

Post-call, the full conversation (transcript + recording) is available at GET /atoms/v1/conversation/{callId} using the call_id from session.created.

Connection

Recommended: short-lived token flow

1. Register the call. Call POST /conversation/register-call (see the Register Call reference in this section) with your API key in the Authorization: Bearer <key> header and the agent_id (plus optional mode and variables) in the body. It returns a short-lived, single-use access_token (prefixed wct_, valid for expires_in seconds).

2. Open the WebSocket with only the token:

   wss://api.smallest.ai/atoms/v1/agent/connect?token=<access_token>

   agent_id, mode, and variables are already baked into the token — don’t pass them on the URL.

This keeps your API key server-side; the browser only ever holds the short-lived token.

Alternative: connect with your API key directly

You can also connect with a raw API key — ?token=<sk_key> or Authorization: Bearer <sk_key> — plus the query params below. This is convenient for server-side or trusted clients. For browser / client-side apps, prefer the token flow above so your API key is never exposed.

* token or Authorization: Bearer <key> — not both.

Connection errors

• 401 Unauthorized — invalid or missing token/API key, expired or already-used wct_ token, or agent_id not found.
• 503 Service Unavailable — server is gracefully draining. The HTTP upgrade is rejected before the WebSocket handshake completes. Clients should retry with exponential backoff.

Example: register a call, then connect (recommended)

// 1. Mint a short-lived token (server-side — keeps your API key private)
const res = await fetch(
  "https://api.smallest.ai/atoms/v1/conversation/register-call",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agentId,
      mode: "webcall",
      // One token per direction. `input_audio_format` is what you send,
      // `output_audio_format` is what the agent sends back. The older
      // `sample_rate` field still works but sets the output only.
      input_audio_format: "pcm_24000",
      output_audio_format: "pcm_24000",
      variables: { customer_name: "Tanay", account_tier: "gold" },
    }),
  }
);
// { access_token, expires_in, sample_rate, input_audio_format, output_audio_format }
const { data } = await res.json();
// 2. Open the WebSocket with the token (e.g. in the browser)
const ws = new WebSocket(
  `wss://api.smallest.ai/atoms/v1/agent/connect?token=${data.access_token}`
);

Example: connect with your API key directly

const variables = { customer_name: "Tanay", account_tier: "gold" };
const ws = new WebSocket(
  "wss://api.smallest.ai/atoms/v1/agent/connect" +
  `?token=${apiKey}` +
  `&agent_id=${agentId}` +
  `&mode=webcall` +
  `&variables=${encodeURIComponent(JSON.stringify(variables))}`
);