Component: alert

The alert component (canvas.alert, v1) shows a short notice during a conversation. It renders inline in a side rail (default safe-area-right). Alerts are display-only; the only interaction a backend normally receives is a dismiss. alert has no settings beyond enabled (default true); see Enabling and configuring components:

{ "config": { "components": { "alert": { "enabled": false } } } }

Component Behavior

The PAL shows an alert for important notices, warnings, or success confirmations; general reading material belongs in the text component.

Only one alert shows at a time; a new alert replaces the previous.

Alerts are always user-dismissible. There is no non-dismissible option.

Arguments

The PAL invokes canvas_show_alert:

Field	Type	Required	Description
`severity`	string	❌	Visual tone. One of `info`, `success`, `warning`, `error`. Defaults to `info` if absent.
`body`	string	✅	The message itself. 1–1200 characters.
`title`	string	❌	Short heading above the body. 1–120 characters.
`auto_dismiss_seconds`	integer	❌	Auto-dismiss the alert after this many seconds (1–120). The alert stays manually dismissible regardless.

Unknown arguments are rejected (additionalProperties: false).

Example invocation

{
  "title": "Heads up",
  "body": "This is a Magic Canvas alert.",
  "severity": "info",
  "auto_dismiss_seconds": 15
}

Interactions

Alerts are lifecycle-only: they never produce submit or skip; allowed types are dismiss, clear, error, and heartbeat. Each reaches the conversation webhook as a canvas.interaction event:

dismiss event

{
  "event_type": "canvas.interaction",
  "properties": {
    "conversation_id": "c123456",
    "interaction_id": "i-5",
    "tool_call_id": "call_def",
    "component": "canvas.alert",
    "component_version": "v1",
    "type": "dismiss",
    "value": {},
    "metadata": {},
    "created_at": "2026-06-09T21:14:03.123456"
  }
}

created_at is UTC with microsecond precision and no offset suffix (no trailing Z); don’t parse it as strict RFC 3339.

The properties envelope is identical for every type; only type and value change:

`type`	When it fires	`value`
`dismiss`	The alert was dismissed, either by the user clicking close or by the `auto_dismiss_seconds` timer. Exactly one `dismiss` fires per alert, even if the timer and a click race.	`{}`
`clear`	The alert was removed programmatically: the PAL cleared it or the conversation moved on.	`{}`
`error`	The client failed to render or run the alert.	Client-defined diagnostic object. Treat it as opaque.
`heartbeat`	State signal a client may emit while the alert is on screen. The hosted renderer does not post these to the webhook; they only appear from a custom renderer that sends them.	Client-defined state object. Safe to ignore in webhook handlers.

For error and heartbeat, value is a free-form object capped at 16 KB serialized; don’t build logic on its shape.

Don’t expect submit or skip from alerts in event funnels; a dismissed alert produces only a dismiss.

Posting Interactions from a Custom Renderer

Custom renderers report the dismiss via the conversation-scoped, public interactions endpoint (no API key while the conversation is active):

curl -X POST https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "Content-Type: application/json" \
  -d '{
    "interaction_id": "i-5",
    "tool_call_id": "call_def",
    "component": "canvas.alert",
    "component_version": "v1",
    "type": "dismiss",
    "value": {}
  }'

Field	Type	Required	Description
`interaction_id`	string	✅	Max 128 characters. Reuse the same value on network retries; Tavus dedupes, so the webhook fires once.
`tool_call_id`	string	✅	Max 128 characters.
`component`	string	✅	`canvas.alert`
`component_version`	string	✅	`v1`
`type`	string	✅	One of the allowed interaction types.
`value`	object	✅	The interaction value (`{}` for `dismiss`).
`metadata`	object	❌	Up to 4 KB.

The full endpoint contract, including the API-key-authenticated GET for interaction history, is in Canvas interactions.

Getting started

Build

Deploy

Debug

Guides

Resources

Component: alert

Component Behavior

Arguments

Interactions

Posting Interactions from a Custom Renderer

​Component Behavior

​Arguments

​Interactions

​Posting Interactions from a Custom Renderer

Component Behavior

Arguments

Interactions

Posting Interactions from a Custom Renderer