Skip to main content
The text component displays a read-only card of plain text alongside the live video. Users can’t type into or submit from it; to collect an answer, use question or input. text has no component-specific configuration; it’s enabled once the Magic Canvas skill is attached (see Enabling and configuring components). To disable it, set { "components": { "text": { "enabled": false } } } in the skill config.

​
Display Behavior

Enabling the component adds system-prompt guidance to show a text card for reference material the user reads while the conversation continues. The PAL keeps talking while the card is on screen, and updates it via the update_component control action rather than stacking a second one.

​
Arguments

The PAL invokes canvas_show_text; Tavus renders the card. The tool_call_id is echoed back on every interaction the card generates.
FieldTypeRequiredDescription
titlestring❌Short heading above the body. The renderer enforces a 120-character limit.
bodystring✅The text to display, rendered as plain text by default (as Markdown when format is markdown). The renderer enforces a 4,000-character limit.
formatstring❌plain or markdown, controlling how body is rendered. Defaults to plain.
layoutobject❌{ "preferred_slot": "safe-area-right" | "safe-area-left" }, where the card prefers to appear. Defaults to safe-area-right, beside the PAL video. Available on every component.
display_modestring❌inline (the only supported value). Available on every component.
Example call
{
  "title": "Conversation note",
  "body": "Magic Canvas can show supporting text without interrupting the conversation."
}

​
Interactions

text is a lifecycle-only component: it never produces submit or skip interactions. The interactions endpoint accepts four types:
TypeWhen it fires
dismissThe user closed the card via a close control. The stock Tavus text card has an always-present X button (aria-label “Dismiss text”); clicking it fires a recorded dismiss interaction.
clearThe card was removed: the PAL cleared or replaced it. The stock renderer handles canvas_clear and replacement locally without recording an interaction.
errorThe card failed on the client. Stock-renderer failures surface through the SDK’s local onError callback, not as recorded interactions.
heartbeatA liveness signal a custom renderer may post while a card is on screen. The stock renderer never posts heartbeats.
The stock Tavus renderers (hosted embed and @tavus/cvi-ui) post a dismiss interaction for text cards (from the X button). They do not post clear, error, or heartbeat; expect those only from a custom renderer.
Renderers post interactions to a public, conversation-scoped endpoint (no API key), accepted only while the conversation is active. Each interaction fires one canvas.interaction webhook event and appears in the interaction history (requires your API key): 
curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"

​
Webhook Payload

A dismiss for a text card; the other types share the same envelope, with only type (and sometimes value) changing. 
{
  "message_type": "canvas",
  "event_type": "canvas.interaction",
  "properties": {
    "conversation_id": "c123456",
    "interaction_id": "ci_call_8842_dismiss_4f1c2d3e",
    "tool_call_id": "call_8842",
    "component": "canvas.text",
    "component_version": "v1",
    "type": "dismiss",
    "value": {},
    "metadata": {},
    "created_at": "2026-06-09T21:14:03.412305"
  }
}
For lifecycle-only components like text, the value object has no enforced shape; Tavus accepts any JSON object up to 16 KB for these types. Key your logic off component, type, and tool_call_id, not value contents.