Canvas components are the cards a PAL can render on the Magic Canvas surface during a conversation. Four are interactive, three display-only:
Magic Canvas adds Canvas actions - built-in LLM functions such as canvas_show_question - when the skill is attached. These are not the same as Tools you create via the Tools API and attach to a PAL. If a name collides, your Tools API definition wins.
| Component | Description | Interactive |
|---|
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 | 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 bar, line, or pie chart | Dismiss only |
alert | Show a dismissible notice | Dismiss only |
v1.
Enabling and configuring components
Components come from the PAL’s magic_canvas skill. Attach it:
curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
-H "x-api-key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{ "config": {} }'
config.components is a sparse overlay, not an allowlist; add an entry only to configure or disable:
{ "config": { "components": { "chart": { "enabled": false } } } }
- Per-component
enabled defaults to true.
scheduling_embed stays inactive until scheduling_url is set; a bare attach doesn’t error.- Unknown component names and stray fields inside a component entry are rejected with a
400.
Tavus compiles Canvas actions only for conversations with a rendering surface.
Audio-only, text-chat, and external meeting_url (Zoom, Teams, Meet)
conversations get no Canvas actions, regardless of PAL configuration.
Control actions
Each active component gives the PAL one canvas_show_<component> action. With at least one component active, the PAL also gets two control actions:
| Action | Description |
|---|
canvas_clear | Remove a card by its tool_call_id, or clear the whole canvas when no target is given. |
update_component | Revise a visible card in place (new chart data, reworded text, updated options) without dismissing and re-showing it. The card keeps its tool_call_id, so interactions stay tied to the same instance. |
Shared layout and display_mode controls
Every Canvas action accepts two optional shared arguments, placement hints the PAL sets when showing a card:
| Field | Type | Values | Description |
|---|
layout | object | preferred_slot: one of safe-area-right, safe-area-left | Placement hint. The client may adapt it for viewport, keyboard, and safety constraints. |
display_mode | string | inline | Cards render inline within their slot. inline is the only supported value. |
preferred_slot at the top level as shorthand for layout.preferred_slot. Steer placement from the system prompt, for example “keep cards on the left.”
Default placement
GA renders every card in a side rail (safe-area-right), inline, regardless of the component or the hint the PAL passes, so the effective placement is the same for all components:
| Component | Effective slot |
|---|
question, input, calendar, scheduling_embed | safe-area-right |
text, chart, alert | safe-area-right |
