Events
The roleplay session lifecycle events and their payloads.
Subscribe with session.on(name, cb). It returns an unsubscribe function — call it (or
session.off) when your component unmounts to avoid leaks in single-page apps.
const off = session.on('personaSpeaking', ({ speaking }) => setAvatarTalking(speaking));
// later:
off();Event reference
| Event | Payload | Fires when |
|---|---|---|
connecting | — | connect() was called; the token is being redeemed and the call joined. |
ready | { persona: { name: string } } | The persona is connected and ready to speak. |
personaSpeaking | { speaking: boolean } | The AI persona started (true) or stopped (false) speaking. |
userSpeaking | { speaking: boolean } | The local rep started (true) or stopped (false) speaking. |
reconnecting | — | A transient network drop is being recovered automatically. |
reconnected | — | The connection recovered after a transient drop. |
ended | { callId: string; durationSec: number } | The call ended. callId is the public athos_call_… id. |
error | { code: string; message: string } | A domain error. Branch on code — see Error codes. |
There is no live transcript event. The transcript is delivered post-call via
GET /v1/calls/:id, not streamed during the call.
When ended fires
A call never ends by itself — the AI persona has no way to hang up. ended fires when you call
session.disconnect(), when the two-hour ceiling is reached, or when the network drops and
cannot recover (alongside a NETWORK_LOST error). Reaching the ceiling is not a failure: the
payload is the same as any other call's and the call is scored normally. See
How a call ends.
Using the callId
The ended event gives you the public callId. Scoring happens after the call ends, so the
score is not available immediately — wait for the call.scored webhook
(or poll GET /v1/calls) and look the call up by that same callId.