Skip to main content
One WebSocket session does streaming speech to text (STT) and streaming text to speech (TTS) at the same time. Send the caller’s audio as it is captured and get transcripts as they speak; send text, even word by word from an LLM, and get speech back right away. It is built for voice agents: it tells you when the caller starts and stops talking, when their turn is over, and lets you cut your agent off when they interrupt.
Connect to exactly this address (a trailing / is fine); any other path is answered with HTTP 404.

Playground

Talk to it from your browser: microphone, transcripts, voices and live timings.

Speech to text

Audio formats, speech detection, turns, transcripts.

Text to speech

Whole and streamed text, interruptions, audio formats.

Settings

Every setting, its range and default.

How a session works

  • Text frames are JSON messages with a type.
  • Binary frames are audio: from you, the caller’s audio; from Hamsa, speech.
  • Speech to text and text to speech run at the same time on the session, so you hear the caller while your agent speaks.

Quick start

Authentication

Send your key as api_key in the handshake message. If your client can’t, send it in the x-api-key header of the connection request, or in the URL as ?api_key= (URLs can end up in logs, so avoid it).
  • Secret keys (sk_) work. During a rotation, the old value keeps working until its overlap ends.
  • Older (legacy) keys work.
  • Public keys (pk_) are refused: they only create call tokens for agents.
  • A limited key needs the Create scope on Realtime (realtime:create).
  • A key with allowed origins only works from a browser page on one of those websites. A server sends no origin, so it is refused.
  • The key’s owner must still be a member of the project, and your account balance must be positive when the session starts.
Keep secret keys on your server. For a browser or mobile app, open the session from your server, or use a key limited to Realtime with allowed origins. See API keys.

Handshake

The first message must be a handshake, within 5 seconds of connecting. Every setting is optional; the defaults suit a phone or web voice agent.
The reply is handshake_ack, with the session’s ID and every setting after defaults:
Send audio and requests only after it: anything sent before handshake_ack is ignored. Some settings can change during the session with config.update. See Settings.

Messages

Every message and field: Message reference.

Errors

An error message has a code and a message:
Before the session opens, the socket closes right after the error: Some key refusals also have a reason: PublicKeyMintOnly, KeyRotated, ApiKeyRevoked, ApiKeyDisabled or ApiKeyExpired. During the session, an error doesn’t close it: A failed speech request gets a tts.error instead. See Text to speech.

Close codes

Limits

Staying connected

  • Pings. Hamsa pings the socket every 20 seconds. Browsers and WebSocket libraries answer on their own; a socket that doesn’t answer is closed. To check the connection yourself, send ping and wait for pong: it echoes your ts, or has the server time (Unix milliseconds) if you sent none.
  • Restarts. When a server restarts, you get session.draining with reconnect_within_ms. Finish the current turn or speech, then open a new session. At the end of that time the socket closes with 1012.
  • Busy. If the server is full, the connection request is answered with HTTP 503 and Retry-After: 1. Try again after a second.

Latency tips

  • Send pcm16 at 16 kHz in 20 to 40 ms frames, as the audio is captured.
  • vad.min_silence_ms is the floor for transcript latency: 300 to 400 ms suits quick agents, 550 ms or more suits callers who pause to think.
  • Start your LLM on preflight. Drop its answer only if a newer interim or preflight arrives for the same turn_id; the final that follows has the same text.
  • Stream your LLM’s reply with tts.append instead of waiting for all of it.
  • Measured on one production session with the defaults: about 700 ms from the caller stopping to the first transcript (550 ms of it is min_silence_ms), and about 190 ms to the first speech audio, whatever the text length.