> ## 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.
* The PAL updates an active alert in place (`update_component`) rather than showing a duplicate.

<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.                                              |
| `layout`               | object  | ❌        | Placement hint. `preferred_slot`: one of `safe-area-right`, `safe-area-left`. The client may adapt it for viewport, keyboard, and safety constraints. |
| `display_mode`         | string  | ❌        | Render mode. Always `inline`.                                                                                                                         |

`layout` and `display_mode` are shared runtime controls on every Canvas action. 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 the [interactions API reference](/sections/conversational-video-interface/magic-canvas/api/interactions).