Component: input

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

Field	Type	Required	Description
`prompt`	string	✅	The question shown above the field. Maximum 240 characters; the renderer rejects longer prompts and the card fails to render.
`placeholder`	string	❌	Hint text inside the empty field. Maximum 160 characters, enforced the same way.
`input_type`	string	❌	One of `text`, `email`, `number`, `tel`. Defaults to `text`. Determines client-side validation and the type of `value` you get back.
`required`	boolean	❌	Defaults to `false`. When `true`, the user must enter a value to submit.
`allow_skip`	boolean	❌	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:

Type	When it fires	`value` shape
`submit`	The user entered a value and submitted	Validated, see below
`skip`	The user skipped (requires `allow_skip`)	Validated, see below
`dismiss`	The user closed the card. The Tavus-hosted input card has no close button, so this only comes from custom renderers	No fixed shape; typically `{}`
`clear`	The card was cleared (PAL moved on, or `canvas_clear`)	No fixed shape; typically `{}`
`error`	The card failed to render or POST. The Tavus-hosted renderer surfaces render failures through the SDK’s `onError` callback instead of posting them	No fixed shape
`heartbeat`	Accepted by the API for custom renderers; the Tavus-hosted renderer does not post heartbeats, so you will not see this in your webhook	No 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.

​Configuration

​Arguments

​Interactions

​Submit and Skip Payloads

​Webhook Event

​Custom Renderers

Configuration

Arguments

Interactions

Submit and Skip Payloads

Webhook Event

Custom Renderers