Magic Canvas overview

Magic Canvas lets a PAL show interactive cards, such as multiple-choice questions, calendars, charts, and text, during a live video conversation. User responses flow back to the PAL and your backend. The PAL decides when to show a card; there is no per-card API call.

PAL invokes a Canvas action  →  card renders in the call
User responds to the card    →  PAL reacts to the response
                             →  your webhook receives the interaction

Conversation Flow

Attach the Magic Canvas skill

Attach via PUT /v2/pals/{pal_id}/skills/magic_canvas; remove with DELETE on the same path:

{
  "config": {}
}

Attaching enables every component with default settings, including components Tavus adds later. The exception is scheduling_embed, which stays inactive until you set its scheduling_url.config.components is a sparse overlay: add an entry only to configure or disable a component ({"enabled": false}); unlisted components stay on. See Configuring your PAL.

Create a conversation

Video conversations get Canvas actions automatically. Audio-only, text-chat, and external-meeting (meeting_url, e.g. Zoom/Teams/Meet) conversations never get them.

PAL shows a card

The PAL invokes a Canvas action; the card renders in a side rail beside the PAL video, and the PAL can clear it mid-conversation.

Interaction flows back

When the user submits, skips, or dismisses a card:

The PAL responds to it, as it does to speech.
Tavus records it and delivers a canvas.interaction event to your conversation webhook, once per interaction.

Fetch a conversation’s full Canvas interaction history with your API key; see Canvas interactions.

When cards appear

The PAL decides when to show a card; you do not call an API to trigger one. Steer that behavior with usage_guidance on the skill, the PAL’s system prompt, or per-conversation context. See When cards appear for how each lever fits.

Hosted vs SDK

Both use the same PALs, components, and webhook; the difference is how much of the UI you own.

	Hosted embed / widget	`@tavus/cvi-ui` SDK
What it is	A `<tavus-embed>` or `<tavus-widget>` tag you drop on any page	A `<MagicCanvas>` React component you add next to your conversation UI
Rendering & interaction posting	Automatic	Automatic, with `onInteraction` / `onError` callbacks for your app
Custom look	Tavus-designed cards	Cards by default, or bring your own React renderers per component
Best for	Fastest path; any site, no framework needed	Apps that own their conversation UI

Components

Seven components: four interactive (submit an answer or skip) and three display-only (dismiss only).

Component	What the PAL can do with it	User can answer?
`question`	Ask a multiple-choice question, optionally with a free-text “Other”	Yes
`input`	Ask for a single typed value: text, email, number, or phone (tel)	Yes
`calendar`	Let the user pick a date, a time slot, or a date range	Yes
`scheduling_embed`	Embed your real scheduling page (e.g. Calendly) for live booking	Yes
`text`	Show a card of formatted text	Dismiss only
`chart`	Show a chart of data from the conversation	Dismiss only
`alert`	Show a dismissible notice	Dismiss only

Rendering

Components render in a sandboxed iframe that isolates styles and scripts in both directions, served from Tavus infrastructure. To render cards in your own React tree, register a renderer per component in the SDK; interactions flow back identically. See Custom rendering.

Next Steps

Configuring your PAL: attach the skill and configure components
Hosted embed and widget: the no-code path
React SDK: <MagicCanvas> in your own app
Canvas interactions: webhooks, recording, and history

Getting started

Build

Deploy

Debug

Guides

Resources

Magic Canvas overview

Conversation Flow

When cards appear

Hosted vs SDK

Components

Rendering

Next Steps

​Conversation Flow

​When cards appear

​Hosted vs SDK

​Components

​Rendering

​Next Steps

Conversation Flow

When cards appear

Hosted vs SDK

Components

Rendering

Next Steps