Skip to main content
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.
ModeStartsMicrophoneSpeaker
textMutedNot requestedOff
voiceUn-mutedRequested on openOn
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.
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.

​
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.
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”.

​
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 typeEditor labelHas action_grid
user_initiatesUser InitiatesYes
bot_initiates_staticExact TextYes
bot_initiates_dynamicUse InstructionsYes
An action_grid has two fields:
FieldTypeDefaultDescription
titlestringHow can I help?Optional heading shown above the grid.
itemsarray[]The quick-action buttons.
Each item in items is one button:
FieldTypeDefaultDescription
labelstring—Button text. Sent back verbatim as the action value when the visitor taps it.
iconstringnoneOptional 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
suitcaseruler
truckcredit
headsetstar
reload

​
Suggesting an action grid from instructions

Rather than writing buttons by hand, you can have Anyreach propose them from the agent’s instructions. 
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.
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.

​
Where each setting lives

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.

Web chat widgets and forms

How widgets attach to an agent, plus pre-conversation forms.

Appearance and branding

Theme, colors, avatar, and launcher styling for the widget.