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

# Text, voice, and quick actions

> Choose default text vs voice mode and add quick-action buttons.

A web widget can open in text mode or voice mode, surface a few suggested questions above the launcher, and start the conversation the moment a visitor opens it. Quick-action buttons are configured separately, on the agent version itself. This page covers each of those controls and where they live.

## Default mode

`default_mode` decides how the widget behaves when a session starts. Set it under **Default Mode** in the widget config, with two options: **Text (Keyboard)** and **Voice (Microphone)**. The default is `text`.

| Mode    | Starts   | Microphone        | Speaker |
| ------- | -------- | ----------------- | ------- |
| `text`  | Muted    | Not requested     | Off     |
| `voice` | Un-muted | Requested on open | On      |

In `voice` mode the microphone permission prompt fires as soon as the session opens, so visitors land in a hands-free conversation. In `text` mode the mic stays muted and no permission is requested until the visitor turns voice on.

The mode is only the starting point. Visitors can switch between text and voice within the same session using the in-widget controls, so `default_mode` sets the first impression rather than a hard restriction.

<Note>
  Set `default_mode` to `voice` only when you expect most visitors to talk. The microphone prompt appears immediately, which can feel abrupt on a page where visitors did not expect it.
</Note>

## Auto-start on open

`start_conversation_on_toggle` is a widget config boolean. When `true`, opening the widget starts the conversation automatically instead of waiting for the visitor to send a first message or press a start button. When unset or `false`, the visitor starts the conversation themselves.

This pairs naturally with `default_mode`: a `voice` widget with auto-start opens straight into a live voice session, while a `text` widget with auto-start drops the visitor into an active chat ready for their first message.

## Suggested questions

Suggested questions are short prompts shown above the launcher while the widget is closed. A visitor taps one to open the widget and send that question as their first message.

* Configure them under **Suggested Questions** in the widget config.
* A maximum of **4** are shown.
* They are **desktop only** — suggested questions are not rendered on mobile.
* They appear only while the widget is closed; opening the widget hides them.

Empty entries are ignored, so a blank field will not produce an empty bubble.

<Tip>
  Phrase suggested questions the way a visitor would ask them, not the way you would describe your product. "How much does shipping cost?" converts better than "Shipping information".
</Tip>

## Quick-action buttons (agent action grid)

Quick-action buttons are a grid of tappable buttons rendered inside the conversation on WebRTC sessions. They are **not** part of the widget config. They are configured on the agent version's `starting_message`, in its `action_grid`.

Every starting-message type carries an optional `action_grid`:

| Starting message type   | Editor label     | Has `action_grid` |
| ----------------------- | ---------------- | ----------------- |
| `user_initiates`        | User Initiates   | Yes               |
| `bot_initiates_static`  | Exact Text       | Yes               |
| `bot_initiates_dynamic` | Use Instructions | Yes               |

An `action_grid` has two fields:

| Field   | Type   | Default           | Description                            |
| ------- | ------ | ----------------- | -------------------------------------- |
| `title` | string | `How can I help?` | Optional heading shown above the grid. |
| `items` | array  | `[]`              | The quick-action buttons.              |

Each item in `items` is one button:

| Field   | Type   | Default | Description                                                                   |
| ------- | ------ | ------- | ----------------------------------------------------------------------------- |
| `label` | string | —       | Button text. Sent back verbatim as the action value when the visitor taps it. |
| `icon`  | string | none    | Optional icon key. Falls back to a default icon if omitted or unknown.        |

The `label` is what matters most: when a visitor taps a button, that label is sent into the conversation exactly as written, as if the visitor had typed it. Write labels that read as clear instructions or questions.

### Icon keys

`icon` accepts one of a fixed set of keys. Anything else falls back to a default icon.

| Icon key   |          |
| ---------- | -------- |
| `suitcase` | `ruler`  |
| `truck`    | `credit` |
| `headset`  | `star`   |
| `reload`   |          |

### Suggesting an action grid from instructions

Rather than writing buttons by hand, you can have Anyreach propose them from the agent's instructions.

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/agents/suggest-action-grid \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "<your agent instructions>" }'
```

The endpoint is stateless — it reads only the `instructions` in the request body, so it works on unsaved drafts. It returns a `StartingActionGrid` (`title` plus `items`) that you can review, edit, and save onto the agent version. Requires the `agents:read` or `agents:manage` scope.

<Note>
  `suggest-action-grid` proposes a grid; it does not save one. Apply the returned `title` and `items` to the agent version's `starting_message.action_grid` to make the buttons appear.
</Note>

## Where each setting lives

```text theme={null}
Widget config (per widget)            Agent version (per agent)
─────────────────────────────        ───────────────────────────────
default_mode                          starting_message
start_conversation_on_toggle            └── action_grid
suggestedQuestions (max 4, desktop)           ├── title
                                              └── items[] { label, icon }
```

Text vs voice, auto-start, and suggested questions are widget-level — change them and republish the widget. The action grid is agent-level — change it on the agent version and publish the agent.

## Related

<CardGroup cols={2}>
  <Card title="Web chat widgets and forms" icon="window" href="/agents/web-chat-widgets-and-forms">
    How widgets attach to an agent, plus pre-conversation forms.
  </Card>

  <Card title="Appearance and branding" icon="palette" href="/web-widgets/appearance-and-branding">
    Theme, colors, avatar, and launcher styling for the widget.
  </Card>
</CardGroup>