/ 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 asapi_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.
Handshake
The first message must be ahandshake, within 5 seconds of connecting. Every setting is optional; the defaults suit a phone or web voice agent.
handshake_ack, with the session’s ID and every setting after defaults:
handshake_ack is ignored. Some settings can change during the session with config.update. See Settings.
Messages
Every message and field: Message reference.
Errors
Anerror message has a code and a message:
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
pingand wait forpong: it echoes yourts, or has the server time (Unix milliseconds) if you sent none. - Restarts. When a server restarts, you get
session.drainingwithreconnect_within_ms. Finish the current turn or speech, then open a new session. At the end of that time the socket closes with1012. - Busy. If the server is full, the connection request is answered with HTTP
503andRetry-After: 1. Try again after a second.
Latency tips
- Send
pcm16at 16 kHz in 20 to 40 ms frames, as the audio is captured. vad.min_silence_msis 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 newerinterimorpreflightarrives for the sameturn_id; thefinalthat follows has the same text. - Stream your LLM’s reply with
tts.appendinstead 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.