> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Component: input

> Collect a single typed value (a name, an email, a phone number) and receive it in your webhook.

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`](/sections/conversational-video-interface/magic-canvas/components/question) for multiple-choice answers and [`calendar`](/sections/conversational-video-interface/magic-canvas/components/calendar) for dates and time slots.

The card renders in the `safe-area-right` slot by default.

<Note>
  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.
</Note>

## Configuration

`input` has no component-specific settings; it is enabled whenever the Magic Canvas skill is attached. Disable with:

```json theme={null}
{ "components": { "input": { "enabled": false } } }
```

See [Enabling and configuring components](/sections/conversational-video-interface/magic-canvas/components#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. |
| `input_type` | string | ❌ | One of `text`, `email`, `number`, `tel`. Defaults to `text`. Determines client-side validation and the type of `value` you get back. |
| `allow_skip` | boolean | ❌ | Defaults to `false`. When `true`, the card shows a skip option, which produces a `skip` interaction. |

Inputs are required by default; the user must enter a value to submit. Set `allow_skip` to `true` to let the user skip instead.

```json Example Call theme={null}
{
  "prompt": "What should we call you?",
  "input_type": "text"
}
```

## 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):

```json theme={null}
{ "input_type": "number", "value": 25, "skipped": false }
```

On skip, `skipped` is `true` and `value` is `null`:

```json theme={null}
{ "input_type": "text", "value": null, "skipped": true }
```

<Warning>
  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.
</Warning>

### Webhook Event

Each interaction is delivered once to your conversation's `callback_url` as a `canvas.interaction` event.

```json Example Event [expandable] theme={null}
{
  "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:

```bash theme={null}
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 [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions) 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.