Host Communication

Overview

Both <tavus-widget> and <tavus-embed> support two-way communication with the host page:

Element → page: the element dispatches CustomEvents (with bubbles: true and composed: true) for conversation lifecycle, tool calls, and protocol messages.
Page → element: the element exposes methods for starting, creating, ending, and messaging the conversation (startConversation(), endConversation(), …).

CDN consumers use plain DOM APIs - no extra bundle needed. npm consumers can use the typed TavusIntegration helper exported from @tavus/widget and @tavus/embed.

Events

Listen on the element itself, or on document (events bubble out of the shadow DOM):

const el = document.querySelector("tavus-embed");

el.addEventListener("tavus:conversation-started", (e) => {
  console.log("started", e.detail.conversationId);
});

el.addEventListener("tavus:tool-call", (e) => {
  console.log("tool call", e.detail.name, e.detail.arguments);
});

Event	`detail`	Fires when
`tavus:ready`	`{ deploymentId }`	The configuration has loaded and the element’s methods are installed. Fires once.
`tavus:conversation-created`	`{ conversationId }`	`createConversation()` created a room nobody has joined yet.
`tavus:conversation-started`	`{ conversationId }`	The visitor joins and the conversation connects.
`tavus:conversation-ended`	`{ conversationId }`	The conversation ends.
`tavus:state-change`	`{ state }`	The conversation state changes. `state` is one of `idle`, `initializing`, `connecting`, `connected`, `disconnecting`, `ended`, `error`.
`tavus:mode-change`	`{ mode }`	The screen the element shows changes. `mode` is one of `idle` (preview), `haircheck`, `call`, `ended` (after-call screen), `unavailable`. With `expand-options`, the overlay is open while the mode is `haircheck` or `call`.
`tavus:error`	`{ code, message }`	The conversation hits an error. A start the server refuses (daily limit, busy) emits this and then `tavus:mode-change` with `unavailable`; treat the mode change as the signal.
`tavus:tool-call`	`{ name, arguments, tool_call_id?, seq?, turn_idx? }`	The PAL’s LLM invokes a tool. `arguments` is a JSON string. Reply with `conversation.tool_result` and the same `tool_call_id` when one is present.
`tavus:protocol-message`	varies	Firehose: fires for every observable protocol event (utterances, perception, speaking state, …). Switch on `detail.event_type`.

tavus:protocol-message carries the raw Interaction Events protocol - detail.event_type values such as conversation.utterance, conversation.tool_call, conversation.started_speaking, and conversation.stopped_speaking match the schemas documented there. For speaking state, check detail.properties.role ("user", "pal", or legacy "replica"). See Started/Stopped Speaking Event.

Reading a transcript

Utterances arrive on tavus:protocol-message with detail.event_type === "conversation.utterance". detail.properties.role is "user" for the visitor or "replica" for the PAL, and detail.properties.speech is the text. Two kinds of utterance share that event type: a complete utterance, which carries no final field, and streaming partials of the same sentence, which carry a boolean final field (false while the sentence grows) and may carry is_interrupted. Keep only the ones without a final field, or a transcript shows every partial as its own line.

integration.on("tavus:protocol-message", (e) => {
  const { event_type, properties } = e.detail;
  if (event_type !== "conversation.utterance") return;
  if (typeof properties.final === "boolean") return; // streaming partial
  addLine(properties.role === "user" ? "You" : "Agent", properties.speech);
});

Magic Canvas card taps are not emitted as tavus:* host events. Only an API-created conversation with a callback_url receives them as canvas.interaction events. Hosted embed and widget conversations do not have a callback_url. See Canvas interactions.

Imperative API

The element installs its methods once its configuration has loaded, so wait for tavus:ready before calling them:

const el = document.querySelector("tavus-embed");

el.addEventListener("tavus:ready", () => {
  el.startConversation(); // as if the visitor pressed Start
});

// Later, once the conversation is live:
el.sendMessage("Hello!"); // sent as conversation.respond
el.endConversation();

Method	Description
`startConversation(options?)`	Starts the conversation the same way the start button does.
`createConversation()`	Creates the conversation ahead of the join, so the PAL is ready when the visitor starts. The next `startConversation()` joins it. Resolves with `{ conversationId }`; rejects when the room could not be created. Every call creates a real conversation, joined or not, and an unjoined one is ended by `endConversation()`, by a second create, or when the page is left. If a start arrives while the create is still in flight, the start joins that attempt and no `tavus:conversation-created` fires.
`endConversation()`	Ends the conversation, or cancels a pending start.
`sendMessage(interaction)`	Sends a typed protocol interaction. A plain string is sent as `conversation.respond`. See Interactions.
`updateConfig(patch)`	Deep-merges an `override-config` patch onto the configuration in effect.
`destroy()`	Ends any live conversation and removes the element.
`open()` / `close()`	`<tavus-widget>` only: expands or collapses the popup. `close()` is the popup’s own close path: it ends a conversation in progress and cancels a pending start before it collapses.

Host-provided devices

When your page renders its own device preview, skip the built-in haircheck and pass the selected devices into the call:

el.startConversation({
  haircheck: "provided",
  devices: {
    microphone: { deviceId: selectedMicrophoneId, enabled: true },
    camera: { track: previewVideoTrack, enabled: cameraEnabled },
  },
});

element.tavus

element.tavus.sendChat(text) sends a chat message into the conversation as the visitor, and element.tavus.sendMessage(interaction) sends a typed protocol interaction.

Interactions

sendMessage accepts the same interaction shapes as the Interactions Protocol:

`event_type`	`properties`	Effect
`conversation.echo`	`{ text }`	The PAL speaks the text verbatim. See Echo.
`conversation.respond`	`{ text }`	The text is sent to the LLM, which responds. See Respond.
`conversation.interrupt`	-	Interrupts the PAL mid-speech. See Interrupt.
`conversation.append_llm_context`	`{ context }`	Appends to the conversation’s LLM context. See Append Context.
`conversation.overwrite_llm_context`	`{ context }`	Replaces the conversation’s LLM context. See Overwrite Context.

TavusIntegration helper (npm)

npm consumers get a typed wrapper around the element from the same package as the registration side effect:

import "@tavus/embed";
import { TavusIntegration, type TavusInteraction } from "@tavus/embed";

// Pass the tag name to target: "tavus-embed" (default) or "tavus-widget".
const integration = new TavusIntegration("tavus-embed");

integration.on("tavus:conversation-started", (e) => {
  console.log("started", e.detail.conversationId);
});

integration.on("tavus:protocol-message", (e) => {
  console.log(e.detail);
});

const interaction: TavusInteraction = {
  event_type: "conversation.respond",
  properties: { text: "Tell me about pricing" },
};
integration.sendMessage(interaction);

// Plain strings are wrapped as conversation.respond for convenience.
integration.sendMessage("Tell me about pricing");

Method	Description
`on(event, handler)`	Subscribes to a typed deployment event.
`off(event, handler)`	Removes a previously added handler.
`startConversation(options?)`	Same as the element’s `startConversation()`.
`createConversation()`	Same as the element’s `createConversation()`.
`endConversation()`	Same as the element’s `endConversation()`.
`sendMessage(interaction \| string)`	Sends a typed interaction. A plain string is wrapped as `conversation.respond`.

The helper looks up the element by tag name in the DOM, so construct it (or make the first call) after the element exists on the page.

TavusIntegration is bundled into the ESM builds of @tavus/widget and @tavus/embed - no extra install. The CDN (IIFE) build stays a pure side-effect drop-in; CDN pages use the DOM APIs above instead.

Letting the PAL act on the page

The PAL cannot touch your page on its own. Every action it can take there, such as adding to a cart, opening a product, filling a form or booking a slot, is a tool defined on the PAL and implemented by your page. Two halves, and both have to exist:

A tool on the PAL. Create it in the PAL Maker or with the Tools API and attach it to the PAL behind the deployment. Give it a name, a description that tells the PAL when to use it, a JSON schema for its parameters, and delivery: { "app_message": true }, which is the default and means the call is sent to the page over the conversation’s data channel. Set on_resolve to generate_response when the PAL should speak from your result (an availability check, a price), or leave the default fire_and_forget for side effects it does not need to narrate. See LLM tool calling and Tool delivery.
A handler on the page. The call arrives as tavus:tool-call with the tool’s name, its arguments as a JSON string written for the schema, and a tool_call_id. The element does not validate the arguments, so parse them in a try/catch and check the values before acting. Do the work, then send conversation.tool_result with the same id. Without a matching id the call times out on the server.

import { TavusIntegration } from "@tavus/embed";

const integration = new TavusIntegration("tavus-embed");

integration.on("tavus:tool-call", (e) => {
  const { name, arguments: args, tool_call_id } = e.detail;
  if (name !== "add_to_cart" || !tool_call_id) return;
  const { product_id, quantity = 1 } = JSON.parse(args);
  const line = cart.add(product_id, quantity);
  integration.sendMessage({
    event_type: "conversation.tool_result",
    properties: {
      tool_call_id,
      output: { added: line.name, quantity, cart_total: cart.total },
      status: "success",
    },
  });
});

output is a string or an object. Send status: "error" and the PAL acknowledges the failure instead of using the result. The PAL only knows about the page what the page tells it. Pass the starting state in conversational-context (the open product, the visitor’s name, what is already in the cart) and send conversation.append_llm_context when it changes during the call, so the PAL’s suggestions match what the visitor sees. Event shapes: tool call and tool result.

Examples

Two pages in tavus-examples use this API end to end: embed-programmatic mounts the element from the page’s own button, starts on tavus:ready and sends suggested questions with conversation.respond; embed-session-flow pre-creates the conversation with createConversation() and builds a live transcript from tavus:protocol-message. See Examples.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Host Communication

Overview

Events

Reading a transcript

Imperative API

Host-provided devices

element.tavus

Interactions

TavusIntegration helper (npm)

Letting the PAL act on the page

Examples

​Overview

​Events

​Reading a transcript

​Imperative API

​Host-provided devices

​element.tavus

​Interactions

​TavusIntegration helper (npm)

​Letting the PAL act on the page

​Examples

Overview

Events

Reading a transcript

Imperative API

Host-provided devices

element.tavus

Interactions

TavusIntegration helper (npm)

Letting the PAL act on the page

Examples