Live events and control
A WebSocket for your server: a call's transcript and status as they happen, and say, context and end to steer it.
Every call has a second WebSocket, for your own server. The call's events go out the moment they happen: the transcript line by line, its status, when the AI speaks, the tools it uses. And your server can steer the call: make the character say a line, give it a note to read, or end it.
Webhooks stay for what must arrive even when nothing is connected; this socket is for while the call runs.
Connecting
The address is the events_url that starting a call answered:
wss://api.daxov.com/live-events/<session>?token=ev.…Your server only
Whoever holds events_url can read the conversation, make the character say anything, and end the call. Never send it to a browser.
The token is the login:
- It names one call. A sound socket token never works here, nor this one there.
- It can be used again, by several listeners at once: up to 5 per call. A listener that drops reconnects with the same token.
- It lasts as long as the call can: the wait for the browser, the call's
max_seconds, then 5 more minutes. It never runs out during a call. - After the call ends it still connects for 5 minutes (you get the snapshot,
ended, and the close); later, it is refused with 4410.
A refused connection is accepted and then closed at once with a code:
| Close code | Why |
|---|---|
| 4401 | The token is wrong, has expired, or is another call's |
| 4404 | No such call |
| 4410 | The call ended more than 5 minutes ago |
| 4429 | 5 listeners are already connected to this call |
| 4408 | Closed later: the listener fell behind 3 times in a minute, or answered nothing (not even a pong) for 45 seconds |
| 1000 | Closed after ended |
// Node 22+ has WebSocket built in.
const ws = new WebSocket(start.events_url);
ws.onmessage = ({ data }) => {
const msg = JSON.parse(data);
if (msg.type === "snapshot") console.log("lines so far", msg.lines, "controls", msg.controls);
if (msg.type === "transcript") console.log(msg.who, msg.text);
if (msg.type === "ended") console.log("ended:", msg.reason);
};
// Later: the character says this next, word for word.
ws.send(JSON.stringify({ type: "say", text: "Your order has shipped.", id: "a1" }));Our server SDK has a ready-made listener, ControlSocket, that reconnects and gives each transcript line once: see the client SDK.
From us
JSON text frames. Times are milliseconds on the call's own clock, counted from when we started the call; the snapshot's connected_ms is when the person's side connected.
| Message | When |
|---|---|
{"type":"snapshot","call":"a1b2c3d4","status":"running","connected_ms":2100,"speaking":false,"lines":[…],"controls":["end","say","context"]} | First, on every connection: the call as it stands. lines has every transcript line so far, so a late listener has the whole conversation. controls says what this call takes |
{"type":"status","status":"running"} | The status changed: starting, waiting (for the person's side to connect), running, ended, failed |
{"type":"transcript","turn":3,"who":"person","text":"What does it cost?","ended_ms":41250} | The person's turn is final; ended_ms is when they stopped speaking |
{"type":"transcript","turn":3,"who":"ai","text":"It's ten dollars a month.","interrupted":false,"started_ms":42100,"ended_ms":44900,"delay_ms":850} | The AI's reply is over: played to the end, or interrupted (by the person, or by the end of the call). delay_ms is from the person stopping to the AI being heard. A line from a say has "say": true |
{"type":"speaking","speaking":true,"turn":3} | The person starts hearing the AI (with a face, when the face speaks); false when it stops |
{"type":"tool","name":"order_status","ok":true,"ms":420,"turn":3} | The character used one of its tools; ok is false when it failed, timed out or wasn't run |
{"type":"ack","for":"say","id":"a1"} | A message of yours was taken |
{"type":"error","code":"queue_full","message":"…","for":"say","id":"a1"} | A message of yours was refused (codes below). The call and the socket go on |
{"type":"lagged","missed":12} | You fell behind and missed 12 frames; a fresh snapshot follows at once |
{"type":"ended","status":"ended","reason":"time_limit","message":"The call reached its time limit."} | The call is over; then we close with 1000 |
Each line goes out once, when it is final. The AI's line comes when its reply is over, not word by word; speaking says when it starts. With some characters the AI's words come a moment after its voice; its line then goes out as soon as they do. Words added after a line went out are only in the call's transcript (GET /v1/calls/{call_id}).
We send a ping every 15 seconds. Ignore message types you don't know: more may come.
Why a call ended
ended never carries the words of the systems behind the call.
reason | message |
|---|---|
time_limit | The call reached its time limit. |
person_left | The person left the call. |
ended | The call was ended (through the API or an end message). |
never_connected | Nobody joined the call in time. |
unavailable | The character couldn't join right now; try again in a few minutes. |
error | The call stopped because of a problem on our side. |
From your server
| Message | What happens |
|---|---|
{"type":"end"} | The call ends, as with POST /v1/calls/{call_id}/end; ended follows |
{"type":"say","text":"Your order has shipped."} | The character speaks this line next, word for word. If the AI is speaking or writing a reply, after that reply; if the person is speaking, after they finish and the AI has answered them. The character is told in its next turn that it said it (or how much was heard, if the person interrupted) |
{"type":"context","text":"The caller is a premium customer."} | A note the character reads at the head of its next turn, and keeps from then on. Never in the transcript |
- Any message may carry an
"id", a string or a number. Itsackorerrorcarries it back. say: at most 1,000 characters (about a minute of speech). Line breaks and control characters become spaces. At most 5 lines waiting at once. Audio tags such as[laughs]work where the character's voice takes them.context: at most 4,000 characters a note and 20,000 a call in all, since every note stays in what the character reads on every later turn. Line breaks are kept.- Sent before the person's side connects, both wait: the notes go into the greeting, and the lines are spoken after it.
Which calls take say and context
say and context work when the character's turns run through our own pipeline: hearing, then the mind, then the voice. Some characters' tiers run on a speech-to-speech model, or on a partner that runs the whole call; those take their turns themselves. They answer say and context with the error not_supported, and their snapshot's controls is ["end"]. Read controls rather than guessing.
transcript and speaking come from our pipeline and from speech-to-speech calls. A call run entirely by a partner sends status and ended only.
Error codes
code | Why |
|---|---|
bad_message | Not a JSON object, no type, no text or an empty one, or a binary frame |
unknown_type | Not end, say or context |
too_long | Over the limits above |
queue_full | 5 say lines are already waiting (or too many notes at once) |
context_full | The call's 20,000 characters of context are used |
not_supported | This call takes its turns itself |
ended | The call is over |
The call never waits on you
A slow or broken listener never slows the call down:
| What | What happens |
|---|---|
| You connect late | A snapshot with every transcript line so far, then the live frames. Nothing is missed or repeated |
| You fall behind | Past 256 frames behind you get lagged with how many you missed, then a fresh snapshot, so no transcript line is lost. The third time in a minute you are closed with 4408. A frame your connection hasn't taken in 10 seconds closes it too |
| You drop | The call goes on. Reconnect with the same token for a fresh snapshot |
| Your connection goes silent | Closed after 45 seconds without a word (not even a pong), so your seat is free for your reconnection |
| A sixth listener connects | Closed with 4429 |
You say while the AI speaks | Queued: spoken after the current reply. The person talking over a say interrupts it like any reply |
You say while the person speaks | It waits until their turn ends and the AI has answered (at most 15 seconds) |
| The call ends | A line cut off by the end goes out first, marked interrupted; then ended, then the close |
| You send something malformed or unknown | An error frame; never a closed call or socket |