Skip to main content
POST
/
v2
/
conversations
/
{conversation_id}
/
canvas
/
interactions
Record Canvas Interaction
curl --request POST \
  --url https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'
{
  "success": true
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.
See Canvas interactions, webhooks, and history for per-component value rules, webhook delivery, and the full error catalog.

Path Parameters

​
conversation_id
string
required

The unique identifier of the conversation.

Example:

"c123456"

Body

application/json

Body for Record Canvas Interaction. value validation depends on component and type - see Canvas interactions.

​
interaction_id
string
required

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

Required string length: 1 - 128
Example:

"ci_call_8f2d41_submit_5e0b7c2a"

​
tool_call_id
string
required

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

Required string length: 1 - 128
Example:

"call_8f2d41"

​
component
enum<string>
required

Component id.

Available options:
canvas.question,
canvas.input,
canvas.calendar,
canvas.scheduling_embed,
canvas.text,
canvas.image,
canvas.video,
canvas.chart,
canvas.alert
Example:

"canvas.question"

​
component_version
string
required

Component contract version. v1 for all current components.

Example:

"v1"

​
type
enum<string>
required

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

Available options:
submit,
skip,
dismiss,
clear,
error,
heartbeat
Example:

"submit"

​
value
object
required

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

Example:
{
  "selected_option_ids": ["opt_2"],
  "skipped": false
}
​
metadata
object

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

Example:
{ "client": "kiosk-web" }

Response

Interaction recorded (or idempotent replay)

​
success
boolean
Example:

true