Skip to main content
Anam personas communicate through an event system that lets you respond to connection changes, conversation updates, and user interactions. Understanding these events helps you build responsive, interactive applications.

​
How Events Work

The Anam SDK uses an event-driven architecture where your application listens for specific events and reacts accordingly. This allows you to:
  • Update your UI based on connection status
  • Track conversation history in real-time
  • Handle user interruptions
  • Monitor stream quality and performance

​
Available Events

​
Connection Events

These events track the connection lifecycle between your client and Anam’s streaming infrastructure:

​
CONNECTION_ESTABLISHED

Fired when the WebRTC connection is successfully established. 
import { AnamEvent } from "@anam-ai/js-sdk";

anamClient.addListener(AnamEvent.CONNECTION_ESTABLISHED, () => {
  console.log("Connected to Anam streaming service");
  updateConnectionStatus("connected");
  hideLoadingSpinner();
});

​
SESSION_READY

Fired after the session initializes and all backend components are ready. Use this to remove loading indicators. 
anamClient.addListener(AnamEvent.SESSION_READY, (sessionId) => {
  console.log("Session ready:", sessionId);
  setIsLoading(false);
});

​
CONNECTION_CLOSED

Fired when the connection is terminated. Receives a reason code and optional details. 
anamClient.addListener(AnamEvent.CONNECTION_CLOSED, (reason, details) => {
  console.log("Connection closed:", reason, details);
  updateConnectionStatus("disconnected");
  showReconnectButton();
});

​
Video Events

​
VIDEO_STREAM_STARTED

Fired when the video MediaStream becomes available. 
anamClient.addListener(AnamEvent.VIDEO_STREAM_STARTED, (videoStream) => {
  console.log("Video stream available");
  // You can attach this to a video element if using manual stream handling
});

​
VIDEO_PLAY_STARTED

Fired when the first video frames begin playing. Ideal for removing loading indicators. 
anamClient.addListener(AnamEvent.VIDEO_PLAY_STARTED, () => {
  console.log("Video stream started");
  hideVideoLoadingState();
  showPersonaInterface();
});

​
Audio Events

​
AUDIO_STREAM_STARTED

Fired when the audio MediaStream from the persona becomes available. 
anamClient.addListener(AnamEvent.AUDIO_STREAM_STARTED, (audioStream) => {
  console.log("Audio stream available");
});

​
INPUT_AUDIO_STREAM_STARTED

Fired when microphone input is successfully initialized. 
anamClient.addListener(AnamEvent.INPUT_AUDIO_STREAM_STARTED, (stream) => {
  console.log("Microphone access granted");
  showMicrophoneIndicator();
  updateAudioInputStatus("active");
});

​
INPUT_AUDIO_DEVICE_CHANGED

Fired when the input audio device changes. 
anamClient.addListener(AnamEvent.INPUT_AUDIO_DEVICE_CHANGED, (deviceId) => {
  console.log("Audio input device changed to:", deviceId);
});

​
Microphone Permission Events

These events track the state of microphone permission requests:

​
MIC_PERMISSION_PENDING

Fired when the browser is requesting microphone permission from the user. 
anamClient.addListener(AnamEvent.MIC_PERMISSION_PENDING, () => {
  showMicPermissionPrompt();
});

​
MIC_PERMISSION_GRANTED

Fired when the user grants microphone permission. 
anamClient.addListener(AnamEvent.MIC_PERMISSION_GRANTED, () => {
  hideMicPermissionPrompt();
});

​
MIC_PERMISSION_DENIED

Fired when the user denies microphone permission. 
anamClient.addListener(AnamEvent.MIC_PERMISSION_DENIED, (error) => {
  console.error("Microphone permission denied:", error);
  showMicPermissionError();
});

​
Conversation Events

These events help you track and respond to conversation flow:

​
MESSAGE_HISTORY_UPDATED

Provides the complete conversation history each time a participant finishes speaking. 
anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, (messages) => {
  console.log("Conversation updated:", messages);
  updateChatHistory(messages);

  // Example message structure:
  // [
  //   { role: "user", content: "Hello" },
  //   { role: "assistant", content: "Hi there! How can I help?" }
  // ]
});

​
MESSAGE_STREAM_EVENT_RECEIVED

Provides real-time transcription updates as speech occurs. 
anamClient.addListener(AnamEvent.MESSAGE_STREAM_EVENT_RECEIVED, (event) => {
  if (event.role === "persona") {
    // Persona is speaking - show real-time transcription
    updatePersonaTranscript(event.content);
  } else if (event.role === "user") {
    // User finished speaking - complete transcription
    updateUserTranscript(event.content);
  }
});

​
Reasoning Events

These events provide insight into the persona’s reasoning process (when using models that support it):

​
REASONING_HISTORY_UPDATED

Provides the complete reasoning history. 
anamClient.addListener(AnamEvent.REASONING_HISTORY_UPDATED, (thoughts) => {
  console.log("Reasoning updated:", thoughts);
});

​
REASONING_STREAM_EVENT_RECEIVED

Provides real-time reasoning updates as the persona thinks. 
anamClient.addListener(AnamEvent.REASONING_STREAM_EVENT_RECEIVED, (event) => {
  updateReasoningDisplay(event);
});

​
Talk Stream Events

​
TALK_STREAM_INTERRUPTED

Fired when a user interrupts a TalkMessageStream by speaking. Receives the correlation ID directly. 
anamClient.addListener(AnamEvent.TALK_STREAM_INTERRUPTED, (correlationId) => {
  console.log("Talk stream interrupted:", correlationId);
  handleStreamInterruption(correlationId);
  stopCurrentGeneration();
});

​
Server Events

​
SERVER_WARNING

Fired when the server sends a warning message. 
anamClient.addListener(AnamEvent.SERVER_WARNING, (message) => {
  console.warn("Server warning:", message);
});

​
Tool Call Events

All tool calls emit lifecycle events — started, completed, and failed — that you can use to trigger client-side actions or for monitoring. For client tools, use registerToolCallHandler to define per-tool handlers, this will automatically emit completed or failed events when the handler completes. Register handlers for specific tools by name. For client tools, the return value from onStart is sent back to the LLM as the tool result: 
// Register a handler — returns a cancel function
const cancelNavHandler = anamClient.registerToolCallHandler("navigate_to_page", {
  onStart: async (payload) => {
    const { page, section } = payload.arguments;
    window.location.href = `/${page}`;
    return `Navigated to ${page}`;
  },
  onComplete: async (payload) => {
    console.log(`Completed in ${payload.executionTime}ms`);
  },
  onFail: async (payload) => {
    console.error(`Failed: ${payload.errorMessage}`);
  },
});

// Clean up when done
cancelNavHandler();

​
TOOL_CALL_STARTED

Fired when any tool call begins. Receives a ToolCallStartedPayload with the tool name, type, and arguments. 
anamClient.addListener(AnamEvent.TOOL_CALL_STARTED, (event) => {
  const { toolName, arguments: args } = event;
  console.log(`Tool started: ${toolName}`, args);
});

​
TOOL_CALL_COMPLETED

Fired when a tool call completes successfully. Includes the result and execution time. 
anamClient.addListener(AnamEvent.TOOL_CALL_COMPLETED, (event) => {
  const { toolName, result, executionTime } = event;
  console.log(`Tool ${toolName} completed in ${executionTime}ms:`, result);
});

​
TOOL_CALL_FAILED

Fired when a tool call fails. Includes the error message and execution time. 
anamClient.addListener(AnamEvent.TOOL_CALL_FAILED, (event) => {
  const { toolName, errorMessage, executionTime } = event;
  console.error(`Tool ${toolName} failed after ${executionTime}ms: ${errorMessage}`);
});

​
CLIENT_TOOL_EVENT_RECEIVED (Deprecated)

A legacy event for client tools. Replaced by TOOL_CALL_STARTED and registerToolCallHandler as of SDK v4.9.0. 
// Deprecated — use registerToolCallHandler instead
anamClient.addListener(AnamEvent.CLIENT_TOOL_EVENT_RECEIVED, (event) => {
  const { eventName, eventData } = event;

  switch (eventName) {
    case "navigate_to_page":
      window.location.href = `/${eventData.page}`;
      break;
    case "open_modal":
      openModal(eventData.modalType, eventData.data);
      break;
  }
});
Client tools enable voice-driven or chat-driven UI control. For a complete guide on creating and configuring client tools, see the Client Tools Guide.

​
Removing Event Listeners

Remove listeners when components unmount or sessions end to prevent memory leaks: 
const handleMessage = (messages) => {
  updateChatHistory(messages);
};

// Add listener
anamClient.addListener(AnamEvent.MESSAGE_HISTORY_UPDATED, handleMessage);

// Remove listener when done
anamClient.removeListener(AnamEvent.MESSAGE_HISTORY_UPDATED, handleMessage);

​
Learn More

Events API Reference

Complete event reference with callback signatures

Client Tools Guide

Guide for creating and handling client tools