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

# Component: alert

> Show a dismissible notice (info, success, warning, or error) inside a live conversation.

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](/sections/conversational-video-interface/magic-canvas/components#enabling-and-configuring-components):

```json theme={null}
{ "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`](/sections/conversational-video-interface/magic-canvas/components/text) component.

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

<Note>
  Alerts are always user-dismissible. There is no non-dismissible option.
</Note>

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

```json Example invocation theme={null}
{
  "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:

```json dismiss event theme={null}
{
  "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"
  }
}
```

<Note>
  `created_at` is UTC with microsecond precision and no offset suffix (no trailing `Z`); don't parse it as strict RFC 3339.
</Note>

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.

<Warning>
  Don't expect `submit` or `skip` from alerts in event funnels; a dismissed alert produces only a `dismiss`.
</Warning>

## 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):

```bash theme={null}
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](/sections/conversational-video-interface/magic-canvas/api/interactions).


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