Made in 10Docs
GuidesAPI
Real time

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:

events_url
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 codeWhy
4401The token is wrong, has expired, or is another call's
4404No such call
4410The call ended more than 5 minutes ago
44295 listeners are already connected to this call
4408Closed later: the listener fell behind 3 times in a minute, or answered nothing (not even a pong) for 45 seconds
1000Closed 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.

MessageWhen
{"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.

reasonmessage
time_limitThe call reached its time limit.
person_leftThe person left the call.
endedThe call was ended (through the API or an end message).
never_connectedNobody joined the call in time.
unavailableThe character couldn't join right now; try again in a few minutes.
errorThe call stopped because of a problem on our side.

From your server

MessageWhat 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. Its ack or error carries 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

codeWhy
bad_messageNot a JSON object, no type, no text or an empty one, or a binary frame
unknown_typeNot end, say or context
too_longOver the limits above
queue_full5 say lines are already waiting (or too many notes at once)
context_fullThe call's 20,000 characters of context are used
not_supportedThis call takes its turns itself
endedThe call is over

The call never waits on you

A slow or broken listener never slows the call down:

WhatWhat happens
You connect lateA snapshot with every transcript line so far, then the live frames. Nothing is missed or repeated
You fall behindPast 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 dropThe call goes on. Reconnect with the same token for a fresh snapshot
Your connection goes silentClosed after 45 seconds without a word (not even a pong), so your seat is free for your reconnection
A sixth listener connectsClosed with 4429
You say while the AI speaksQueued: spoken after the current reply. The person talking over a say interrupts it like any reply
You say while the person speaksIt waits until their turn ends and the AI has answered (at most 15 seconds)
The call endsA line cut off by the end goes out first, marked interrupted; then ended, then the close
You send something malformed or unknownAn error frame; never a closed call or socket

On this page