> ## 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; the shared `layout`, `display_mode` (inline only in GA), and `update_component` controls apply ([components overview](/sections/conversational-video-interface/magic-canvas/components)).

<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.        |
| `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.                                 |

```json Example Call theme={null}
{
  "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):

```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 the [interactions API page](/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`.