Skip to main content
The <anam-agent> element dispatches standard DOM Custom Events that cross the Shadow DOM boundary, so you can listen to them with addEventListener on the element itself or any ancestor. Event data is available on event.detail.

​
Listening to events

const widget = document.querySelector("anam-agent");

widget.addEventListener("anam-agent:session-started", (e) => {
  console.log("Session started:", e.detail.sessionId);
});

widget.addEventListener("anam-agent:message-received", (e) => {
  console.log(`${e.detail.role}: ${e.detail.content}`);
});

widget.addEventListener("anam-agent:error", (e) => {
  console.error(`Error [${e.detail.code}]: ${e.detail.message}`);
});

​
Events reference

Event NamePayloadDescription
anam-agent:session-started{ sessionId: string }A WebRTC session has been established.
anam-agent:session-ended{ sessionId: string, reason: string }The session has ended (user-initiated or server-side).
anam-agent:message-received{ role: "user" | "agent", content: string }A transcript message was received from either party.
anam-agent:message-sent{ content: string }The user sent a text message via the input field.
anam-agent:expanded{}The widget was expanded (floating layout only).
anam-agent:collapsed{}The widget was collapsed (floating layout only).
anam-agent:error{ code: string, message: string }An error occurred (auth failure, network issue, etc.).
anam-agent:mic-muted{}The user muted their microphone.
anam-agent:mic-unmuted{}The user unmuted their microphone.

​
Common patterns

Track session starts, message counts, and engagement duration:
const widget = document.querySelector("anam-agent");
let sessionStart;

widget.addEventListener("anam-agent:session-started", (e) => {
  sessionStart = Date.now();
  analytics.track("avatar_session_started", {
    sessionId: e.detail.sessionId,
  });
});

widget.addEventListener("anam-agent:session-ended", (e) => {
  const duration = Date.now() - sessionStart;
  analytics.track("avatar_session_ended", {
    sessionId: e.detail.sessionId,
    reason: e.detail.reason,
    durationMs: duration,
  });
});

widget.addEventListener("anam-agent:message-received", (e) => {
  if (e.detail.role === "agent") {
    analytics.track("avatar_message", {
      contentLength: e.detail.content.length,
    });
  }
});
React to widget expand/collapse to adjust your page layout:
const widget = document.querySelector("anam-agent");
const sidebar = document.getElementById("sidebar");

widget.addEventListener("anam-agent:expanded", () => {
  sidebar.style.marginRight = "420px";
});

widget.addEventListener("anam-agent:collapsed", () => {
  sidebar.style.marginRight = "0";
});
Display user-facing messages or trigger fallback behavior:
const widget = document.querySelector("anam-agent");

widget.addEventListener("anam-agent:error", (e) => {
  const { code, message } = e.detail;

  if (message.includes("Origin not allowed")) {
    showBanner("Widget configuration required. Contact your admin.");
  } else if (message.includes("Too many requests")) {
    showBanner("Please wait a moment before trying again.");
  } else {
    showBanner("Something went wrong. Please try again.");
  }
});