Events

Subscribe with on(event, callback) and unsubscribe with off(event, callback). The SDK forwards events from two sources:

Avatar / engine events sent by the Avaturn backend over the underlying transport (avatar speech, transcripts, errors).
Client lifecycle events emitted locally by the SDK (init, idle, microphone state).

Avatar speech

`avatar_started_speaking`

Fired when the avatar starts speaking.

{ type: "avatar_started_speaking", phrase_id: string }

`avatar_ended_speaking`

Fired when the avatar finishes the current utterance.

{ type: "avatar_ended_speaking" }

`avatar_started_speaking_phrase`

Fired when the avatar starts a specific queued phrase. Use this when you need to track individual phrases (e.g. for captioning).

{ type: "avatar_started_speaking_phrase", phrase_id: string }

`avatar_ended_speaking_phrase`

Fired when the avatar finishes a phrase.

{ type: "avatar_ended_speaking_phrase", phrase_id: string }

Transcripts

Emitted by the OpenAI Realtime engine. Not emitted by the Cartesia engine.

User-input transcripts require configuration. Set audio.input.transcription.model in the OpenAI session config (e.g. "whisper-1"); without it the input transcript event never fires. Assistant transcripts flow by default.

`ce_events.realtime.input_transcript`

User speech transcription.

{
  type: "ce_events.realtime.input_transcript",
  transcript: string,
  timestamp: number // unix seconds
}

`ce_events.realtime.response_transcript`

Avatar (assistant) speech transcription.

{
  type: "ce_events.realtime.response_transcript",
  transcript: string,
  timestamp: number // unix seconds
}

Client lifecycle

Emitted by the SDK locally.

`init`

Fired when the avatar video track is ready. The promise returned by init() resolves on this event.

`idle`

Fired after 5 minutes without a backend message or task() call. If keepAlive is false, the SDK also tears down its local state right after the event fires.

The idle event bypasses the event catch-all. Subscribe to idle directly if you need to react to it.

Errors

`error`

Fired when the backend reports a lifecycle failure. Payload structure:

{
  type: "error",
  error: {
    type: "session_lifecycle_error",
    code: "internal_error" | "limits_exceeded" | "openai-realtime-version-mismatch",
    message: string,
    session_id: string
  }
}

openai-realtime-version-mismatch — your OpenAI session config mixes beta and GA-only features. Use GA-only (beta-to-GA migration).
limits_exceeded — workspace quota reached.
internal_error — generic server-side failure; check message for details.

Microphone

`local_audio_change`

Fired when the user’s microphone mute state changes. Callback receives a boolean directly (true = unmuted, false = muted).

avatar.on("local_audio_change", (active: boolean) => {
  // ...
});

`local_mic_state_change`

Fired when the microphone permission or device state changes. Callback receives a state string from Daily’s DailyTrackState['state'] union (e.g. "blocked", "off", "sendable", "loading", "interrupted", "playable", "receivable").

avatar.on("local_mic_state_change", (state) => {
  // ...
});

Catch-all

`event`

Fires alongside every other event except idle. Useful for logging or debugging.

avatar.on("event", ({ event, value }) => {
  console.log(event, value);
});

Example

function onPhraseEnd({ phrase_id }: { phrase_id: string }) {
  console.log("phrase done:", phrase_id);
}

avatar.on("avatar_ended_speaking_phrase", onPhraseEnd);
// later
avatar.off("avatar_ended_speaking_phrase", onPhraseEnd);

Get Started

Conversation Engines

Web SDK

REST API

Legacy

Avatar speech

`avatar_started_speaking`

`avatar_ended_speaking`

`avatar_started_speaking_phrase`

`avatar_ended_speaking_phrase`

Transcripts

`ce_events.realtime.input_transcript`

`ce_events.realtime.response_transcript`

Client lifecycle

`init`

`idle`

Errors

`error`

Microphone

`local_audio_change`

`local_mic_state_change`

Catch-all

`event`

Example

​Avatar speech

​avatar_started_speaking

​avatar_ended_speaking

​avatar_started_speaking_phrase

​avatar_ended_speaking_phrase

​Transcripts

​ce_events.realtime.input_transcript

​ce_events.realtime.response_transcript

​Client lifecycle

​init

​idle

​Errors

​error

​Microphone

​local_audio_change

​local_mic_state_change

​Catch-all

​event

​Example

Avatar speech

`avatar_started_speaking`

`avatar_ended_speaking`

`avatar_started_speaking_phrase`

`avatar_ended_speaking_phrase`

Transcripts

`ce_events.realtime.input_transcript`

`ce_events.realtime.response_transcript`

Client lifecycle

`init`

`idle`

Errors

`error`

Microphone

`local_audio_change`

`local_mic_state_change`

Catch-all

`event`

Example