Events Guide

Voice Server  →  WebSocket  →  SDK Dispatcher  →  agent.on("event", handler)

agent.on("event.name", (event, call) => {
  // event — payload (varies per event)
  // call  — the Call object for this session
});

agent.on("call.started", (call) => {
  console.log(`📞 ${call.direction} call from ${call.from}`);
  call.setPromptVars({ customer_name: "John" });
});

agent.on("call.preparing", (call) => {
  call.setPromptVars({
    date_block: buildFreshDate(),
    format_rules: call.transport === "phone" ? VOICE_FORMAT : CHAT_FORMAT,
  });
});

agent.on("call.ended", (call, reason) => {
  console.log(`Call ended: ${reason}, lasted ${call.duration}s`);
  console.log(`Transcript:`, call.transcript);
});

agent.on("call.ringing", (ringingCall) => {
  if (isBlacklisted(ringingCall.from)) {
    ringingCall.reject();
  } else {
    ringingCall.accept();
  }
});

agent.on("call.forwarded", (event, call) => {
  console.log(`Call forwarded to ${event.to}`);
});

agent.on("call.recording", (event, call) => {
  // event.audio — base64 WAV data
  // event.duration_ms — recording duration
  // event.format — "wav"
  // event.sample_rate — typically 8000
  fs.writeFileSync(`recording-${call.id}.wav`, Buffer.from(event.audio, "base64"));
});

agent.on("chat.started", (call) => {
  // call.transport === "chat"
  call.setPromptVars({ format: "markdown" });
});

agent.on("whatsapp.started", (call, session) => {
  // call — universal Call object
  // session — WhatsAppSession with contactPhone, contactName
  call.setPromptVars({ customer_name: session.contactName });
});

agent.on("speech.started", (event, call) => {
  // event.turn_id, event.confidence
});

agent.on("speech.ended", (event, call) => {
  // event.turn_id, event.duration_ms
});

agent.on("user.speaking", (event, call) => {
  console.log(`Hearing: "${event.text}"`);
  // Updates rapidly: "hel" → "hello" → "hello how" → "hello how are you"
});

agent.on("user.message", (event, call) => {
  console.log(`User said: "${event.text}"`);
  // event.messageId — use for reply correlation
});

agent.on("eager.turn", (turn, call) => {
  // turn.text — accumulated transcript
  // turn.probability — confidence (0–1)
  // turn.messageId — for in_reply_to validation
});

agent.on("turn.end", (turn, call) => {
  call.reply(turn.text);
});

agent.on("turn.continued", (event, call) => {
  console.log("User continued — aborting previous response");
});

bot.speaking  →  bot.word × N  →  bot.finished      (completed normally)
                                   bot.interrupted    (user barged in)
                                   message.confirmed  (full text saved)

agent.on("bot.speaking", (event, call) => {
  // event.messageId — tracks this specific utterance
  // event.text — full text for non-streaming replies (empty for replyStream)
});

agent.on("bot.word", (event, call) => {
  // event.messageId — which message this word belongs to
  // event.word — the word just spoken
});

agent.on("bot.finished", (event, call) => {
  // event.messageId
  // event.durationMs — how long the bot spoke
  console.log(`Done (${event.durationMs}ms): "${call.currentBotText}"`);
});

agent.on("bot.interrupted", (event, call) => {
  // event.messageId
  // event.playedMs — how long the bot spoke before interruption
  // event.reason — "user_spoke" (after 2s) or "early" (before 2s)
  console.log(`Interrupted after ${event.playedMs}ms, said: "${call.currentBotText}"`);
});

// Live subtitles — grows word-by-word as the bot speaks
agent.on("bot.word", (event, call) => {
  updateSubtitle(call.currentBotText);
  // "¡Hola!"
  // "¡Hola! Estoy"
  // "¡Hola! Estoy bien,"
  // "¡Hola! Estoy bien, gracias."
});

// Capture full text when bot finishes
agent.on("bot.finished", (event, call) => {
  saveToTranscript("bot", call.currentBotText);
});

// Capture partial text when user interrupts
agent.on("bot.interrupted", (event, call) => {
  saveToTranscript("bot (interrupted)", call.currentBotText);
});

agent.on("message.confirmed", (event, call) => {
  // event.messageId
  // event.text — the confirmed message text
});

agent.on("message.aborted", (event, call) => {
  // event.messageId
  // event.reason
});

agent.on("reply.rejected", (event, call) => {
  // event.messageId — the rejected bot message
  // event.in_reply_to — what the reply referenced
  // event.expected_reply_to — what the server expected
  // event.reason — "message_obsolete" etc.
});

agent.on("llm.toolCall", (data, call) => {
  for (const tc of data.toolCalls) {
    console.log(`🔧 ${tc.name}(${tc.arguments})`);
  }
  // data.msgId — correlation ID
  // data.toolCalls — [{ id, name, arguments }]
});

agent.on("session.idleWarning", (event, call) => {
  // event.remainingSeconds — time left before timeout
  // event.idleTimeoutSeconds — total idle timeout configured
  call.say("Are you still there?");
});

agent.on("session.timeout", (event, call) => {
  // event.reason — "max_duration" | "idle_timeout"
  call.say("We've reached the time limit. Goodbye!");
});

agent.on("session.paused", (event) => {
  // event.sessionId — set for session-level pause
  // event.contact — set for contact-level pause
  // both undefined = global pause
});

agent.on("session.resumed", (event) => {
  // event.sessionId
  // event.contact
});

agent.on("call.held", (event, call) => {
  console.log("📞 Call on hold");
});

agent.on("call.unheld", (event, call) => {
  console.log("📞 Call resumed");
});

agent.on("call.muted", (event, call) => {
  console.log("🔇 Mic muted");
});

agent.on("call.unmuted", (event, call) => {
  if (event.muted_transcript) {
    console.log(`While muted, user said: "${event.muted_transcript}"`);
  }
});

agent.on("call.dtmf_sent", (event, call) => {
  // event.digits — the digits sent
});

agent.on("whatsapp.message", (event) => {
  // event.sessionId
  // event.from — contact phone number
  // event.name — contact name
  // event.type — "text" | "audio" | "image" | "video" | "document"
  // event.text — message text (for audio, this is the transcript)
  // event.messageId
  // event.paused — true when agent is paused (human-in-the-loop)
});

agent.on("whatsapp.response", (event) => {
  // event.sessionId
  // event.to — recipient phone
  // event.text — message text
  // event.source — "human" when sent by operator via agent.sendMessage()
});

agent.on("whatsapp.status", (event) => {
  // event.status — "sent" | "delivered" | "read"
  // event.recipient
  // event.messageId
});

agent.on("whatsapp.sessionEnded", (event) => {
  // event.session_id
  // event.contact_phone
  // event.duration
  // event.message_count
});

agent.on("credits.rejected", (event) => {
  console.log("⛔ No credits — call rejected");
});

agent.on("credits.exhausted", (event, call) => {
  call.say("We've run out of credits. The call will end shortly.");
});

agent.on("audio.metrics", (event, call) => {
  // event.source — "user" | "bot"
  // event.energyDb — -60 to 0
  // event.rms — 0–1
  // event.peak — 0–1
  // event.isSpeech — VAD detection
  // event.vadProb — 0–1
});

┌─── Connection ─────────────────────────────────────┐
│  call.started                                       │
│  call.preparing                                     │
│  bot.speaking  →  bot.word × N  →  bot.finished     │  ← greeting
└─────────────────────────────────────────────────────┘

┌─── User speaks ────────────────────────────────────┐
│  speech.started                                     │
│  user.speaking  (interim × N)                       │
│  speech.ended                                       │
│  user.message   (final text)                        │
│  eager.turn  →  turn.end                            │
└─────────────────────────────────────────────────────┘

┌─── Bot responds ───────────────────────────────────┐
│  call.preparing                                     │
│  bot.speaking                                       │
│  bot.word × N                                       │
│  bot.finished  |  bot.interrupted                   │
│  message.confirmed                                  │
└─────────────────────────────────────────────────────┘

┌─── Interruption (barge-in) ────────────────────────┐
│  speech.started                                     │
│  bot.interrupted                                    │
│  turn.continued  (if before 2s of bot audio)        │
│  user.message                                       │
│  turn.end                                           │
└─────────────────────────────────────────────────────┘

┌─── Disconnect ─────────────────────────────────────┐
│  call.ended                                         │
│  call.recording  (if enabled)                       │
└─────────────────────────────────────────────────────┘

event: user.message
data: {"callId":"CA123","text":"Hello","messageId":"msg_abc","agent":"mara"}

event: bot.word
data: {"callId":"CA123","word":"Hi","messageId":"msg_def","agent":"mara"}