Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Conversations

Record Canvas Interaction

Record a Magic Canvas interaction (submit, skip, dismiss, clear, error, or heartbeat) while a conversation is active.

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

Authentication: No API key is required while the conversation is active. Never put your Tavus API key in a browser. Once the conversation ends, every POST is rejected.

Idempotency: Retries with the same (conversation_id, interaction_id) and identical tool_call_id, component, component_version, type, and value return 200 without firing a second webhook. metadata is excluded from the match.

Rate limiting: 120 POSTs per 60-second window per (client IP, conversation_id). Exceeding the limit returns 429 with { "error": "Too many requests" } and a Retry-After header (seconds until the window resets). Custom renderers posting heartbeat interactions count toward this limit.

See Canvas interactions for per-component value rules, webhook delivery, and the full error catalog.

post/v2/conversations/{conversation_id}/canvas/interactions

Request body

interaction_idstring required

Idempotency key. Unique per logical interaction; reuse verbatim on retries. Tavus clients use ci_{tool_call_id}_{type}_{uuid}.

tool_call_idstring required

The id of the Canvas invocation that showed the card. Ties the interaction to a specific card instance.

component'canvas.question' | 'canvas.input' | 'canvas.calendar' | 'canvas.scheduling_embed' | 'canvas.text' | 'canvas.image' | 'canvas.video' | 'canvas.chart' | 'canvas.alert' required

Component id.

component_versionstring required

Component contract version. v1 for all current components.

type'submit' | 'skip' | 'dismiss' | 'clear' | 'error' | 'heartbeat' required

Interaction type. Submit-capable components also allow submit and skip.

valueobject required

Interaction payload. At most 16 KB serialized. Shape depends on component and type.

metadataobject

Optional client annotations, at most 4 KB serialized. Not part of idempotency matching.

Example request

{
  "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"
  }
}

Response

Interaction recorded (or idempotent replay)

successboolean

Example response

{
  "success": true
}