Skip to main content
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

1

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.
2

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. Your conversation webhook receives the canvas.interaction event.
  • 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, use your webhook or fetch interaction history (requires your API key): 
curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"

​
Local development override

Both elements accept the same attributes:
FieldTypeRequiredDescription
deployment-idstring✅Loads the deployment’s configuration from GET /v2/deployments/:id/init.
override-configJSON 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-contextstring❌Per-page context sent to the PAL when the call starts. A non-empty value replaces the deployment-level context for that call.
custom-greetingstring❌Replaces the line the PAL opens with.
memory-storesstring❌Comma-separated memory store ids, sent to /start as memory_stores.
tokenstring❌Preview or auth token forwarded to /init and /start. Flips the element into preview mode.
base-urlstring❌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.