Magic Canvas Quickstart

Magic Canvas lets a PAL show interactive cards, such as questions, calendars, and charts, during a conversation. The PAL’s LLM decides when to show one; user input flows back to the conversation and your webhook.

Attach the Magic Canvas skill

Attaching the skill enables the available components with default settings:

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": {} }'

config.components is a sparse overlay, not an allowlist; add an entry only to configure or disable a component:

Disable charts

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": { "components": { "chart": { "enabled": false } } } }'

Later components are enabled automatically on PALs with the skill attached; disable them the same way. See Configuring your PAL for all component settings and when cards appear to steer timing.

The skill has no effect on echo and speech-to-speech PALs.

Create the conversation

Every video conversation with this PAL gets Canvas. Set callback_url; interactions arrive there in step 4:

curl -X POST https://tavusapi.com/v2/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "face_id": "r79e1c033f",
    "pal_id": "p5317866",
    "callback_url": "https://yourapp.example.com/webhooks/tavus"
  }'

Audio-only, text-chat, and Zoom/Teams/Meet (meeting_url) conversations never receive Canvas actions.

Conversation creation uses your API key; call it from your backend, never the browser.

Render the canvas

With the Tavus-hosted embed or widget, Canvas renders automatically:

<script src="https://unpkg.com/@tavus/embed"></script>
<tavus-embed deployment-id="YOUR_DEPLOYMENT_ID"></tavus-embed>

For React, add the @tavus/cvi-ui component:

npx @tavus/cvi-ui@latest add magic-canvas

Mount it inside the same CVIProvider as your conversation UI:

import { CVIProvider } from "./components/cvi/components/cvi-provider";
import { Conversation } from "./components/cvi/components/conversation";
import { MagicCanvas } from "./components/cvi/components/magic-canvas";

<CVIProvider>
  <Conversation conversationUrl={conversationUrl} />
  <MagicCanvas
    onInteraction={(event) => console.log("user interacted:", event)}
  />
</CVIProvider>

The default class sets position: fixed (full-viewport overlay). To keep cards inside your player, wrap both in a position: relative container and pass a className that sets position: absolute !important.

Receive interactions

Each interaction arrives at your callback_url as a canvas.interaction event:

canvas.interaction

{
  "properties": {
    "conversation_id": "c123456",
    "interaction_id": "ci_call_abc123_submit_8f3d2a",
    "tool_call_id": "call_abc123",
    "component": "canvas.question",
    "component_version": "v1",
    "type": "submit",
    "value": { "selected_option_ids": ["opt_2"], "skipped": false },
    "metadata": {},
    "created_at": "2026-06-09T21:14:03.412210"
  },
  "conversation_id": "c123456",
  "message_type": "canvas",
  "event_type": "canvas.interaction",
  "timestamp": "2026-06-09T21:14:03.498Z"
}

A retry of the same saved interaction does not send another webhook. The same webhook can still arrive twice. Treat two events as the same interaction when conversation_id and interaction_id match, and do not apply the second one again. Under Zero Data Retention there is no saved interaction, so a client retry is delivered again. See delivery guarantees.Fetch the full history any time with your API key:

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

The response is { "data": [ ... ] }, oldest first, with the same fields as the webhook’s properties. It’s empty for conversations on Zero Data Retention, which record no interactions.

See Canvas components for the full component list and per-component reference. scheduling_embed needs a booking link (provider plus scheduling_url) configured before it activates:

"config": {
  "components": {
    "scheduling_embed": {
      "provider": "calendly",
      "scheduling_url": "https://calendly.com/your-team/30min"
    }
  }
}

Cards render in a sandboxed iframe on Tavus infrastructure that isolates styles and scripts in both directions. Your webhook receives skip and dismiss interactions in addition to submit.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Magic Canvas Quickstart