Skip to main content
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.
  • The PAL updates an active alert in place (update_component) rather than showing a duplicate.
Alerts are always user-dismissible. There is no non-dismissible option.

​
Arguments

The PAL invokes canvas_show_alert:
FieldTypeRequiredDescription
severitystring❌Visual tone. One of info, success, warning, error. Defaults to info if absent.
bodystring✅The message itself. 1–1200 characters.
titlestring❌Short heading above the body. 1–120 characters.
auto_dismiss_secondsinteger❌Auto-dismiss the alert after this many seconds (1–120). The alert stays manually dismissible regardless.
layoutobject❌Placement hint. preferred_slot: one of safe-area-right, safe-area-left. The client may adapt it for viewport, keyboard, and safety constraints.
display_modestring❌Render mode. Always inline.
layout and display_mode are shared runtime controls on every Canvas action. 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:
typeWhen it firesvalue
dismissThe 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.{}
clearThe alert was removed programmatically: the PAL cleared it or the conversation moved on.{}
errorThe client failed to render or run the alert.Client-defined diagnostic object. Treat it as opaque.
heartbeatState 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": {}
  }'
FieldTypeRequiredDescription
interaction_idstring✅Max 128 characters. Reuse the same value on network retries; Tavus dedupes, so the webhook fires once.
tool_call_idstring✅Max 128 characters.
componentstring✅canvas.alert
component_versionstring✅v1
typestring✅One of the allowed interaction types.
valueobject✅The interaction value ({} for dismiss).
metadataobject❌Up to 4 KB.
The full endpoint contract, including the API-key-authenticated GET for interaction history, is in the interactions API reference.