Skip to main content
The input component renders a single text field with a prompt above it. The PAL sees the user’s typed response (or skip) and your webhook receives the value. Use question for multiple-choice answers and calendar for dates and time slots. The card renders in the safe-area-right slot by default; the shared layout, display_mode (inline only in GA), and update_component controls apply (components overview).
The PAL shows the card via canvas_show_input when it needs a single typed response (name, email, phone, or number); there is no API call to trigger it.

​
Configuration

input has no component-specific settings; it is enabled whenever the Magic Canvas skill is attached. Disable with: 
{ "components": { "input": { "enabled": false } } }
See Enabling and configuring components.

​
Arguments

FieldTypeRequiredDescription
promptstring✅The question shown above the field. Maximum 240 characters; the renderer rejects longer prompts and the card fails to render.
placeholderstring❌Hint text inside the empty field. Maximum 160 characters, enforced the same way.
input_typestring❌One of text, email, number, tel. Defaults to text. Determines client-side validation and the type of value you get back.
requiredboolean❌Defaults to false. When true, the user must enter a value to submit.
allow_skipboolean❌Defaults to false. When true, the card shows a skip option, which produces a skip interaction.
Example Call
{
  "prompt": "What should we call you?",
  "placeholder": "Ada",
  "input_type": "text",
  "required": true,
  "allow_skip": false
}

​
Interactions

input is submit-capable and can produce all six interaction types:
TypeWhen it firesvalue shape
submitThe user entered a value and submittedValidated, see below
skipThe user skipped (requires allow_skip)Validated, see below
dismissThe user closed the card. The Tavus-hosted input card has no close button, so this only comes from custom renderersNo fixed shape; typically {}
clearThe card was cleared (PAL moved on, or canvas_clear)No fixed shape; typically {}
errorThe card failed to render or POST. The Tavus-hosted renderer surfaces render failures through the SDK’s onError callback instead of posting themNo fixed shape
heartbeatAccepted by the API for custom renderers; the Tavus-hosted renderer does not post heartbeats, so you will not see this in your webhookNo fixed shape; typically {}

​
Submit and Skip Payloads

value from the Tavus-hosted card always has exactly three fields: input_type, value, and skipped. On submit, skipped is false and value is required: a string for text, email, and tel; a JSON number for number (not a numeric string; booleans rejected): 
{ "input_type": "number", "value": 25, "skipped": false }
On skip, skipped is true and value is null: 
{ "input_type": "text", "value": null, "skipped": true }
For input_type: "email", the renderer trims whitespace and checks the format before submitting; the Tavus API does not re-validate it. Validate again in your backend before sending mail.

​
Webhook Event

Each interaction is delivered once to your conversation’s callback_url as a canvas.interaction event.
Example Event
{
  "message_type": "canvas",
  "event_type": "canvas.interaction",
  "conversation_id": "c123456",
  "timestamp": "2026-06-09T21:14:03Z",
  "properties": {
    "conversation_id": "c123456",
    "interaction_id": "ci_call_8f31_submit_6f2c9a1e",
    "tool_call_id": "call_8f31",
    "component": "canvas.input",
    "component_version": "v1",
    "type": "submit",
    "value": {
      "input_type": "email",
      "value": "ada@lovelace.dev",
      "skipped": false
    },
    "metadata": {},
    "created_at": "2026-06-09T21:14:03.208541"
  }
}
The full interaction history is available at any time, including after the conversation ends: 
curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"

​
Custom Renderers

Custom renderers POST interactions to POST /v2/conversations/{conversation_id}/canvas/interactions with no API key; the endpoint is public while the conversation is active. See the interactions API page for idempotency, replay rules, and size caps. Input-specific validation: submit requires value.value of the type matching input_type (string for text/email/tel, JSON number for number); skip requires skipped: true.