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

# Canvas Interactions

> Record card taps, receive canvas.interaction webhooks, and fetch Canvas interaction history.

**Canvas interactions** record what a user does on a Canvas card: tap, submit, skip, or dismiss. Each interaction is recorded with a POST, delivered to your `callback_url` as a `canvas.interaction` webhook, and queryable with the history GET. Conversations on [Zero Data Retention (ZDR)](#zero-data-retention) are the exception: Tavus delivers each interaction and records none. All endpoints live under `https://tavusapi.com`.

> [!NOTE]
>
> These are card taps on Magic Canvas, not [Interaction Events](https://docs.tavus.io/sections/conversational-video-interface/interactions-protocols/overview.md) (the Daily app-message protocol for controlling a live call).

## When Magic Canvas is active

No per-conversation configuration is required. A PAL gets Canvas actions when both are true:

* The PAL has the **Magic Canvas skill** attached: `PUT /v2/pals/{pal_id}/skills/magic_canvas`, covered in [Configuring your PAL](https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/api/configuration.md).
* The conversation has a rendering surface. Audio-only conversations, chat conversations, and conversations that join an external meeting via `meeting_url` (Zoom, Teams, Google Meet) get no Canvas actions.

When both are true, the PAL gets one action per enabled component, the control action `canvas_clear`, and guidance on when to show each component. See [When cards appear](https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/api/configuration.md#when-cards-appear) for how `usage_guidance`, the system prompt, and conversational context fit together. This applies to every conversation start path, including hosted deployments (`POST /v2/deployments/{deployment_id}/start`).

## Record an Interaction

[`POST /v2/conversations/{conversation_id}/canvas/interactions`](https://docs.tavus.io/api-reference/canvas-interactions/record-canvas-interaction)

The Tavus-hosted embed and `@tavus/cvi-ui` post interactions for you; call this endpoint directly only if you build your own renderer.

```bash theme={null}
curl -X POST https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "Content-Type: application/json" \
  -d '{
    "interaction_id": "ci_call_8f2d41_submit_5e0b7c2a",
    "tool_call_id": "call_8f2d41",
    "component": "canvas.question",
    "component_version": "v1",
    "type": "submit",
    "value": { "selected_option_ids": ["opt_2"], "skipped": false },
    "metadata": { "client": "kiosk-web" }
  }'
```

A successful request returns `200`:

```json theme={null}
{ "success": true }
```

An identical retry returns the same `200`; see [Idempotency and delivery guarantees](#idempotency-and-delivery-guarantees).

### Authentication

No API key or token is required while the conversation is active. Once the conversation ends, every POST is rejected with a 400.

### Rate limiting

The interaction POST is rate-limited at **120 requests per 60-second window** per `(client IP, conversation_id)`. The limit is checked before schema validation or any database work.

When you exceed the limit, the API returns **HTTP 429** with a `Retry-After` header (seconds until the current window resets) and a body of `{ "error": "Too many requests" }`. Back off and retry after that interval.

Custom renderers that post `heartbeat` interactions count toward this limit. Space heartbeats accordingly; the Tavus-hosted embed and `@tavus/cvi-ui` stay within the budget for normal sessions.

> [!WARNING]
>
> Never put your Tavus API key in a browser. The interaction POST doesn't need
> it, and nothing client-side ever should.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `interaction_id` | string | ✅ | 1–128 chars. Your idempotency key: unique per logical interaction, reused verbatim on retries. The Tavus client generates `ci_{tool_call_id}_{type}_{uuid}`. |
| `tool_call_id` | string | ✅ | 1–128 chars. The id of the Canvas invocation that showed the card. Ties the interaction to a specific card instance. |
| `component` | string | ✅ | One of the component ids below. |
| `component_version` | string | ✅ | The component's contract version. `v1` for all current components. |
| `type` | string | ✅ | One of `submit`, `skip`, `dismiss`, `clear`, `error`, `heartbeat`. The component must also allow it (see below). |
| `value` | object | ✅ | The interaction payload. At most 16 KB serialized. Shape depends on `component` and `type`. |
| `metadata` | object | ❌ | Your own annotations, at most 4 KB serialized. Defaults to `{}`. Stored (except under [ZDR](#zero-data-retention)) and delivered as-is; never validated against the component contract. |

Unknown top-level fields are rejected with a 400.

Component ids: `canvas.question`, `canvas.input`, `canvas.calendar`, `canvas.scheduling_embed`, `canvas.text`, `canvas.image`, `canvas.chart`, `canvas.alert`.

> [!NOTE]
>
> This endpoint accepts only the component ids above.

### Interaction Types

| `type` | Sent when | Allowed on |
| - | - | - |
| `submit` | The user completed the card: picked an answer, typed a value, chose a slot, booked a meeting. | `question`, `input`, `calendar`, `scheduling_embed` |
| `skip` | The user explicitly skipped the card without answering. | `question`, `input`, `calendar`, `scheduling_embed` |
| `dismiss` | The user closed the card. | all components |
| `clear` | The card was cleared from the canvas. | all components |
| `error` | The card hit a render or runtime error. | all components |
| `heartbeat` | A liveness ping from a long-lived card. | all components |

Display-only components (`text`, `image`, `chart`, `alert`) allow only the four lifecycle types; sending `submit` to one returns a 400.

### `value` Rules per Component

For `submit` and `skip`, `value` is validated against the component's contract. The lifecycle types (`dismiss`, `clear`, `error`, `heartbeat`) pass `value` through without component-specific validation.

| Component | `skip` rules | `submit` rules |
| - | - | - |
| `canvas.question` | `skipped: true` and no answer payload. | `skipped: false` with at least one selected option or a non-empty `custom_text`. Allowed keys are exactly `selected_option_ids` (list of strings, required), `skipped` (boolean, required), `custom_text` (max 4,000 chars), and `option_texts` (maps option ids to display strings of max 2,000 chars; every key must also appear in `selected_option_ids`). Unknown keys are rejected. |
| `canvas.input` | `{ "skipped": true }` | Requires `input_type` (one of `text`, `email`, `number`, `tel`) and `value`. For `number` the value must be numeric; otherwise it must be a string. |
| `canvas.calendar` | `{ "skipped": true }` | Requires exactly one of: `selected_date` (string), `selected_slot` (`{ "id", "start", "end" }`), `selected_slots` (non-empty list of slots), or `selected_range` (`{ "start", "end" }`). |
| `canvas.scheduling_embed` | Not validated: only `submit` is checked against the contract; other types pass `value` through. | Allowed keys are exactly `provider`, `scheduled`, `event_uri`, `invitee_uri`. `provider` must be `"calendly"` and `scheduled` must be `true`. The URI fields are optional but must be `https` Calendly URLs. |

Example `value` payloads:

```json submit payloads by component [expandable] theme={null}
// canvas.question
{ "selected_option_ids": ["opt_2"], "skipped": false, "option_texts": { "opt_2": "2–10 people" } }

// canvas.input
{ "input_type": "email", "value": "ada@example.com" }

// canvas.calendar
{ "selected_slot": { "id": "slot_tue_10", "start": "2026-06-16T10:00:00Z", "end": "2026-06-16T10:30:00Z" } }

// canvas.scheduling_embed
{ "provider": "calendly", "scheduled": true, "event_uri": "https://api.calendly.com/scheduled_events/AAAA" }
```

### Errors

Schema and contract validation failures return an `{ "error", "fields" }` envelope. Conversation-state errors (400) and conflicts (409) return a `{ "message": "<string>" }` envelope.

| Status | Body | Meaning |
| - | - | - |
| 400 | `{ "error": "Invalid canvas interaction payload.", "fields": ["<field>", "_schema", ...] }` | The body failed schema or contract validation. `fields` lists the offending top-level field names only (max 10, each truncated to 64 chars); cross-field failures surface under the single key `_schema`. No marshmallow detail strings are returned. |
| 400 | `{ "message": "Invalid conversation_id" }` | No conversation exists with this id. Note this is a 400, not a 404. |
| 400 | `{ "message": "Canvas interactions can only be recorded for active conversations." }` | The conversation has ended (or hasn't started). |
| 409 | `{ "message": "Interaction does not match the issued canvas instance for this tool_call_id." }` | The `component` or `component_version` doesn't match the card Tavus issued for this `tool_call_id`. |
| 409 | `{ "message": "interaction_id was already recorded with a different payload." }` | This `interaction_id` was already used with different contents. Retries must be byte-identical; new interactions need a new id. Not returned under [ZDR](#zero-data-retention), which keeps no record to compare against. |
| 429 | `{ "error": "Too many requests" }` | Rate limit exceeded (120 POSTs per 60-second window per client IP and conversation). Response includes a `Retry-After` header. Back off and retry. |

The following checks run internally and all surface through the `{ "error", "fields" }` envelope above; their internal messages (component, component\_version, interaction-type, and size rules) are not returned to the client:

* An unsupported component id.
* A `component_version` that doesn't match the component's current version (`v1`).
* An interaction type the component doesn't allow (for example, `submit` on `canvas.text`).
* `value` over 16 KB or `metadata` over 4 KB serialized.
* A NUL character (`U+0000`) in any string or object key inside `value` or `metadata`.
* A `value` that breaks the component's `submit` or `skip` rules; see the per-component rules above.

The size caps apply to the serialized JSON of `value` and `metadata` individually, not to the raw request body.

## The `canvas.interaction` Webhook

Every recorded interaction is delivered to your conversation webhook as a [`canvas.interaction`](https://docs.tavus.io/sections/event-schemas/canvas-interaction) event, on the same callback pipeline as all other conversation events. Set `callback_url` when creating the conversation and route on `event_type === "canvas.interaction"`; `properties` carries the interaction exactly as recorded. Under [ZDR](#zero-data-retention), each accepted interaction is delivered the same way, though none is recorded.

Tavus sends this event only for conversations with Magic Canvas enabled, and only when the conversation has a `callback_url`.

* **Treat it as untrusted input.** The end user's browser reports each interaction through the public POST. Tavus checks the payload's shape, but the values are whatever the client sent, so validate them before you act on them.
* **The same interaction can be sent more than once.** Treat two events as the same interaction when `conversation_id` and `interaction_id` match, and do not apply the second one again. An `interaction_id` is unique only within its conversation.

```json 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_8f2d41_submit_5e0b7c2a",
    "tool_call_id": "call_8f2d41",
    "component": "canvas.question",
    "component_version": "v1",
    "type": "submit",
    "value": { "selected_option_ids": ["opt_2"], "skipped": false },
    "metadata": { "client": "kiosk-web" },
    "created_at": "2026-06-09T21:14:03.518923"
  }
}
```

`properties` fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `conversation_id` | string | ✅ | The conversation the interaction belongs to. |
| `interaction_id` | string | ✅ | The client's idempotency key for this interaction. |
| `tool_call_id` | string | ✅ | The Canvas invocation that showed the card. |
| `component` | string | ✅ | Component id, e.g. `canvas.question`. |
| `component_version` | string | ✅ | Component contract version, e.g. `v1`. |
| `type` | string | ✅ | One of `submit`, `skip`, `dismiss`, `clear`, `error`, `heartbeat`. |
| `value` | object | ✅ | The interaction payload, exactly as validated and, except under [ZDR](#zero-data-retention), stored. |
| `metadata` | object | ✅ | The client's annotations, passed through unvalidated. |
| `created_at` | string or null | ✅ | When the interaction was recorded or, under [ZDR](#zero-data-retention), when Tavus accepted it. A naive ISO-8601 timestamp with microseconds and **no** timezone suffix (no trailing `Z`). The value is UTC; parse it accordingly. The top-level `timestamp` on the webhook envelope, by contrast, carries a `Z`. |

> [!NOTE]
>
> `skip` and `dismiss` events are delivered as well as `submit`; count them
> if you track completion rates.

## Fetch History

[`GET /v2/conversations/{conversation_id}/canvas/interactions`](https://docs.tavus.io/api-reference/canvas-interactions/list-canvas-interactions)

Requires your API key; you must own the conversation. Call it from your backend, not the browser.

```bash theme={null}
curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"
```

```json theme={null}
{
  "data": [
    {
      "conversation_id": "c123456",
      "interaction_id": "ci_call_8f2d41_submit_5e0b7c2a",
      "tool_call_id": "call_8f2d41",
      "component": "canvas.question",
      "component_version": "v1",
      "type": "submit",
      "value": { "selected_option_ids": ["opt_2"], "skipped": false },
      "metadata": { "client": "kiosk-web" },
      "created_at": "2026-06-09T21:14:03.518923"
    }
  ]
}
```

* Items use the same fields as the webhook's `properties` object.
* Ordered oldest first (`created_at`, then insertion order as a tiebreaker).
* Readable during and after the conversation: writes stop when the call ends, reads don't. Use it for post-call processing and to reconcile against your webhook log.
* Empty for conversations on [ZDR](#zero-data-retention), which record no interactions.

## Idempotency and Delivery Guarantees

Conversations on [ZDR](#zero-data-retention) record no interactions, so the guarantees here that rely on a stored record do not apply to them. That includes idempotent replays, the `409` for a reused `interaction_id`, and the history GET. Under ZDR there is no saved interaction, so a client retry is delivered again.

* **The POST is idempotent on `(conversation_id, interaction_id)`.** An identical retry returns `200`, stores nothing new, and fires no second webhook. Safe to retry on timeouts.
* **"Identical" means `tool_call_id`, `component`, `component_version`, `type`, and `value` all match.** `metadata` is excluded; the first recorded `metadata` is kept and delivered.
* **A reused `interaction_id` with a different payload is a 409**, never a silent overwrite. This check does not run under [ZDR](#zero-data-retention). A payload that does not match the card Tavus issued is still a `409` on every conversation, including ZDR.
* **A retry of a saved interaction does not send another webhook.** The webhook is sent when the interaction is first recorded. Replays, retries, and concurrent duplicates of that saved interaction do not send it again.
* **The same webhook can still arrive twice.** In rare cases your endpoint receives the same event more than once. Treat two events as the same interaction when `conversation_id` and `interaction_id` match, and do not apply the second one again. An `interaction_id` is unique only within its conversation.
* **The interaction store is the source of truth.** In rare failure cases an event may not reach your endpoint even though the interaction was stored. If completeness matters, reconcile with the history GET after the call.
* **Self-generated `interaction_id`s** must be unique per logical interaction and reused on every retry of that interaction. The Tavus client uses `ci_{tool_call_id}_{type}_{uuid}`.

## Zero Data Retention

Zero Data Retention (ZDR) is an account-level setting that your Tavus account team turns on. For conversations that run under ZDR, Tavus delivers each interaction to you and writes no interaction record:

* **No interaction history.** Nothing is stored for the interaction, so the history GET returns `{ "data": [] }`.
* **Delivery by webhook and transcript.** The `canvas.interaction` webhook carries each interaction in full, including `value` and `metadata`. The end-of-call [`application.transcription_ready`](https://docs.tavus.io/sections/webhooks-and-callbacks#application-callbacks) transcript includes the text form of a submit, the words the renderer sends to the PAL for that answer, when it sends one. Only submits have a text form, and the transcript carries no `interaction_id`, so treat the webhook as your record of each interaction.
* **One delivery attempt.** Tavus makes one attempt to deliver each event and doesn't retry it. If delivery fails, for example because your endpoint is down, Tavus can't resend the interaction or return it from the history GET; only its text form may still reach you in the transcript.
* **No reused-id check.** With nothing stored, Tavus can't tell a retry from a new interaction. A repeat under the same `interaction_id` returns `200` and is delivered again, even when the payload differs. The `409` for a reused `interaction_id` with a different payload doesn't apply. A payload that does not match the card Tavus issued is still a `409`. The Tavus-hosted embed and `@tavus/cvi-ui` retry a POST that fails or times out, so expect repeats. Treat two events as the same interaction when `conversation_id` and `interaction_id` match, and do not apply the second one again.
* **`created_at` is the accept time.** It's when Tavus accepted the POST, in the same format as a recorded interaction, so each repeat carries its own `created_at`.
* **A `callback_url` is required to receive answers.** The webhook and the transcript both go to the conversation's `callback_url`. Without one, the answers reach no one: Tavus delivers none of them and keeps no copy. Conversations started by the [Tavus-hosted embed or widget](https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/integrations/hosted.md) have no `callback_url`, so to receive answers under ZDR, create the conversation through the API (`POST /v2/conversations` with a `callback_url`) and render it with [`@tavus/cvi-ui`](https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/integrations/cvi-ui-sdk).

Everything else about the POST is unchanged: schema validation, rate limiting, the active-conversation check, and the issued-card `409` apply as for any conversation.


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