Integration: Tavus-Hosted Embed and Widget

The Tavus-hosted embed and widget render a full Magic Canvas conversation from a single HTML tag. The element joins the call, renders cards, and posts interactions back to Tavus; the host page contains no Canvas code.

<tavus-embed> renders the conversation inline and fills its container.
<tavus-widget> renders a floating launcher; clicking it opens the conversation.

Both share one engine and render in a shadow DOM, isolating page and element styles.

Quickstart

Create a deployment

Follow Deployments overview to create a widget or embed deployment in the PAL Maker. For installation, sizing, and attributes, see Widget and Embed.

Attach the Magic Canvas skill to the PAL

curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{ "config": {} }'

Attaching the skill enables every component with defaults. To disable a component or configure scheduling_embed (the one component that requires config to activate), add entries under config.components; see Canvas configuration.

Hosted client behavior

The hosted client handles everything the @tavus/cvi-ui integration requires you to wire up:

Rendering. Cards overlay the call within the element’s bounds and are cleaned up when the conversation moves on.
Interaction delivery. User interactions post to POST /v2/conversations/{conversation_id}/canvas/interactions. The endpoint is public during an active conversation.
Sandboxing. Components render in sandboxed iframes and load from Tavus-approved hosts only.

Card interactions are not emitted as host-page tavus:* events. For browser-side callbacks, use the onInteraction prop in the @tavus/cvi-ui integration. For server-side handling, fetch interaction history (requires your API key):

curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"

Conversations started by the hosted embed or widget have no callback_url, so under Zero Data Retention (ZDR) their Magic Canvas answers are neither stored nor delivered. To receive answers under ZDR, create the conversation through the API (POST /v2/conversations with a callback_url) and render it with @tavus/cvi-ui.

Local development override

Both elements accept the same attributes:

Field	Type	Required	Description
`deployment-id`	string	✅	Loads the deployment’s configuration from `GET /v2/deployments/:id/init`.
`override-config`	JSON string	❌	Deep-merged over the fetched configuration. If `deployment-id` is omitted, the override is used as-is and nothing is fetched (useful for local UI work).
`conversational-context`	string	❌	Per-page context sent to the PAL when the call starts. A non-empty value replaces the deployment-level context for that call.
`custom-greeting`	string	❌	Replaces the line the PAL opens with.
`memory-stores`	string	❌	Legacy comma-separated memory tags, sent to `/start` as `memory_stores`. See Tag-based memories. `memory_store_id` is not supported by the hosted element.
`token`	string	❌	Preview or auth token forwarded to `/init` and `/start`. Flips the element into preview mode.
`base-url`	string	❌	API base URL. Defaults to `https://tavusapi.com`.

There is no API-key attribute. The deployment endpoints the element calls (/init, /start, /end) are public and scoped to the deployment. token is a preview token, not an API key. Never put a Tavus API key in page markup.

Override example (field names match the deployment configuration schema):

<tavus-embed
  deployment-id="YOUR_DEPLOYMENT_ID"
  override-config='{"customization":{"style":{"mode":"dark","style":"silk"}}}'>
</tavus-embed>

If deployment-id is omitted, the override is used as-is and nothing is fetched.

Host-page events

For lifecycle events, tool calls, and protocol interactions from your page, see Host communication.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Integration: Tavus-Hosted Embed and Widget

Quickstart

Hosted client behavior

Local development override

Host-page events

​Quickstart

​Hosted client behavior

​Local development override

​Host-page events

Quickstart

Hosted client behavior

Local development override

Host-page events