> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggested Messages

> Render clickable follow-up suggestions inside assistant replies using airiaMessageButton, airiaMessageDropdown, airiaMessageRadios, and airiaMessageCheckboxes.

Assistants can end a reply with one or more **suggested next-user-messages**. When a user clicks a suggestion, it is submitted back to the agent as if the user typed it themselves — no extra round-trip, no instruction to "just say X." This turns a reply into a guided fork in the conversation.

There are four tags for this, two compact (hidden behind a trigger) and two inline (all options visible at once):

<CardGroup cols={2}>
  <Card title="airiaMessageButton" icon="square-mouse-pointer">
    A single clickable suggestion. One tap → submit.
  </Card>

  <Card title="airiaMessageDropdown" icon="caret-down">
    One trigger, a dropdown of suggestions. Clicking an option submits it immediately.
  </Card>

  <Card title="airiaMessageRadios" icon="circle-dot">
    An inline radio group plus a Send button. User picks one, then submits.
  </Card>

  <Card title="airiaMessageCheckboxes" icon="square-check">
    One trigger, a checkbox list plus a Send button. Picks are joined into one user message.
  </Card>
</CardGroup>

All four work in `/chat`, `/catalog/chat`, and the embeddable chat widget. They are emitted by the assistant as XML-like tags in the markdown reply; the chat UI parses them and swaps in interactive React components.

***

## When to use which

<Steps>
  <Step title="One obvious follow-up">
    Use **airiaMessageButton**. Best when there is a clear next question and you want to minimize friction.
  </Step>

  <Step title="A small list of alternatives, pick one (compact)">
    Use **airiaMessageDropdown**. Best for 3–8 mutually-exclusive follow-ups with longer labels, or when conversation density matters and you want the suggestions tucked behind a trigger.
  </Step>

  <Step title="A small list of alternatives, pick one (inline)">
    Use **airiaMessageRadios**. Best for 2–5 short labels the user benefits from comparing at a glance before committing. Same single-select intent as the dropdown, but always visible.
  </Step>

  <Step title="A list where combining makes sense">
    Use **airiaMessageCheckboxes**. Best when the user might legitimately want to ask about several topics at once (e.g., "tell me about pricing *and* features").
  </Step>
</Steps>

Rule of thumb: **one suggestion block per reply**. Stacking several is visual noise, and users interpret multiple suggestion surfaces as indecision from the assistant.

***

## airiaMessageButton

A single suggestion. Click submits `buttonText` (or the tag body if `buttonText` is empty) as a new user message.

```xml theme={null}
<airiaMessageButton buttonText="Tell me more about pricing">
Tell me about pricing
</airiaMessageButton>
```

**Attributes**

| Attribute    | Required | Purpose                                                           |
| ------------ | -------- | ----------------------------------------------------------------- |
| `buttonText` | No       | Visible label on the button. Falls back to the tag body if empty. |

The tag body is the message that gets submitted on click. If `buttonText` is provided, it becomes the label and the body becomes the submitted message; if not, the body is used for both.

***

## airiaMessageDropdown

A dropdown of single-submit suggestions. The tag **body is a JSON array** of `{label, message}` objects — `label` is what the user sees in the menu, `message` is what gets submitted when they click that option.

```xml theme={null}
<airiaMessageDropdown buttonText="Tell me more">
[
  {"label": "About pricing",  "message": "Tell me about pricing"},
  {"label": "About features", "message": "Tell me about the features"},
  {"label": "About support",  "message": "Tell me about the support plans"}
]
</airiaMessageDropdown>
```

**Attributes**

| Attribute    | Required | Purpose                                                           |
| ------------ | -------- | ----------------------------------------------------------------- |
| `buttonText` | No       | Label on the dropdown trigger. Falls back to a localized default. |

**Body schema**

```json theme={null}
[
  { "label": "string shown in the menu", "message": "string submitted on click" }
]
```

Clicking an option behaves exactly like clicking an **airiaMessageButton** — it submits the `message` value as a new user turn.

<Note>
  If the body is not valid JSON or not an array of `{label, message}` objects, the dropdown silently renders nothing rather than crashing the message. Always emit valid JSON.
</Note>

***

## airiaMessageRadios

An inline radio group rendered directly in the assistant message, plus an explicit **Send** button below the options. The user picks one option and can change their mind freely until they click Send — only then is the selected `message` submitted as a new user turn. Same single-select intent as `airiaMessageDropdown`, but always-visible rather than hidden behind a trigger.

```xml theme={null}
<airiaMessageRadios buttonText="Pick a topic" sendButtonText="Ask">
[
  {"label": "Pricing",  "message": "Tell me about pricing"},
  {"label": "Features", "message": "Tell me about the features"},
  {"label": "Roadmap",  "message": "Tell me about the roadmap"}
]
</airiaMessageRadios>
```

**Attributes**

| Attribute        | Required | Purpose                                                                    |
| ---------------- | -------- | -------------------------------------------------------------------------- |
| `buttonText`     | No       | Heading rendered above the radio group. Falls back to a localized default. |
| `sendButtonText` | No       | Label on the Send button. Defaults to the localized "Send" string.         |

**Body schema** — identical to `airiaMessageDropdown`:

```json theme={null}
[
  { "label": "string shown next to the radio", "message": "string submitted when Send is clicked" }
]
```

<Note>
  Prefer radios over a dropdown when you have 2–5 short labels and want the user to see every option at once. Prefer a dropdown when labels are longer or the list is bigger and inline rendering would crowd the message.
</Note>

***

## airiaMessageCheckboxes

A checkbox list plus an explicit **Send** button inside the menu. Users tick one or more options, then click Send. The selected `message` values are **joined with newlines** and submitted as a single user turn.

```xml theme={null}
<airiaMessageCheckboxes buttonText="Pick topics" sendButtonText="Ask about these">
[
  {"label": "Pricing",  "message": "Tell me about pricing"},
  {"label": "Features", "message": "Tell me about the features"},
  {"label": "Roadmap",  "message": "Tell me about the roadmap"}
]
</airiaMessageCheckboxes>
```

If the user ticks *Pricing* and *Roadmap* and clicks Send, the agent receives:

```
Tell me about pricing
Tell me about the roadmap
```

**Attributes**

| Attribute        | Required | Purpose                                                                          |
| ---------------- | -------- | -------------------------------------------------------------------------------- |
| `buttonText`     | No       | Label on the trigger that opens the checkbox menu.                               |
| `sendButtonText` | No       | Label on the Send item inside the menu. Defaults to the localized "Send" string. |

**Body schema** — identical to `airiaMessageDropdown`:

```json theme={null}
[
  { "label": "string shown next to the checkbox", "message": "string joined into the submitted message" }
]
```

<Note>
  Checkboxes do not submit on each tick — the menu stays open while the user is choosing, and submission only happens when they click Send. Write `message` values that read naturally when combined with other picks via newlines.
</Note>

***

## Streaming behaviour

All four tags respect streaming. While the closing tag has not yet arrived, the trigger (or the whole inline group, for radios) renders in a disabled state so users cannot click partial suggestions. Once the tag finishes streaming, interaction enables automatically. For dropdowns, radios, and checkboxes, this means a complete, valid JSON body must be fully streamed before interaction is possible.

***

## Prompting the model

These tags are only useful if the underlying model knows when and how to emit them. Add an example like this to your system prompt:

```text theme={null}
When there is a clear single follow-up the user is likely to want,
end your reply with <airiaMessageButton> containing that message.

When there are several possible follow-ups the user might pick between:
- Use <airiaMessageDropdown> when labels are long or there are many options
  and you want them tucked behind a trigger.
- Use <airiaMessageRadios> when labels are short (2–5 options) and showing
  all of them inline helps the user compare before committing.
Both take a JSON array of objects with "label" and "message" string fields.

When the user might legitimately want to ask about multiple topics at
once, use <airiaMessageCheckboxes>. Same JSON body format; selected
option messages are joined with newlines into a single user turn.

Emit at most one suggestion block per reply.
```

For an end-to-end example of weaving these into a prompt, see [Prompts](/building-and-deploying-agents/agent-basics/prompts).