Text only
text_only is a widget config boolean (Text only in the widget editor). When true the widget never opens a realtime voice session: conversations are created on the webchat channel, answered by the async engine over HTTP, and show in the dashboard as “Web widget (text-only)”. Everything else works as before — widgets, forms, image uploads, quick-action buttons and human handoff — but there is no microphone, no speaker, and no voice/keyboard toggle, so default_mode and the toggle setting below do not apply.
Turning it on changes which agent settings apply: the agent’s webchat per-channel configuration (see Per-channel configuration) instead of its webrtc one. Existing widgets are unaffected until the toggle is switched on.
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.
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 on the Suggestions tab of the widget config.
- A maximum of 4 are shown on a page.
- They are desktop only unless Show on phones is on (see Display).
- They appear only while the widget is closed; opening the widget hides them.
Different questions per page
The Suggestions tab has four parts:- Default questions — the list shown on any page no rule matches.
- Page rules — a URL path pattern and the list to show on matching pages. Rules are checked top to bottom and the first match replaces the default list; to keep a question on every page, include it in each list.
- Named questions — questions written once and referenced by name (for example
order_status) from any list. Edit the text once and every page that uses it changes. - Page values — values read from the page the widget is on, inserted with
{{name}}.
* matches within one path segment and ** across any number. Shopify also serves products under /collections/<name>/products/<handle>, so start product rules with **/. The editor warns when an earlier rule takes a rule’s pages first.
Page values
A page value is a CSS selector plus an optional attribute (without one, the element’s text is used). The widget’s loader reads only the selectors you declare, never reads form fields, and passes the values to the widget alone — they do not appear in host-page events. A widget reads up to 10 page values, each with a selector of up to 300 characters. On sites that fill values in after a page change, the loader waits until they stop changing (at most 1.5 seconds) before the questions update. Before a value goes into a question it is cleaned up, in this order:- Extract (optional regex) — keeps the first capture group, or the whole match. No match counts as missing.
- Cut at — keeps the text before whichever separator appears first. The defaults are a spaced hyphen, en dash, em dash and pipe (
-,–,—,|), which stores use to append things to product names. Periods and commas are not defaults because they appear inside names and prices. - Max length — cuts back to the last whole word within the limit (80 characters by default), never mid-word. A first word longer than the limit counts as missing.
<meta property="og:title" content="Ooni Koda 16 Gas Powered Pizza Oven - 1st Generation">. With selector meta[property="og:title"], attribute content and max length 15, Tell me about the {{product}} becomes “Tell me about the Ooni Koda 16”.
Use {{product|this oven}} to supply text for pages where the value is missing. A question that uses a missing value with no fallback is left out on that page. Paste a real value into the variable’s Sample from your page box to see the cleaned result (the cleanup options are under Cleanup). Type a URL into Preview a page to see which rule it matches; the launcher preview then shows that page’s questions, filled in from your samples.
Teasers
The default and each rule can also have a teaser: one message in the agent’s voice, shown above the questions, such as “Questions about the ? I can help.” Clicking it opens the chat. A teaser can be a named question or one-off text, and uses page values and fallbacks the same way questions do; if its value is missing with no fallback, the teaser is left out and the questions still show. A matching rule replaces the default’s teaser along with its questions, so a rule without a teaser shows none. To keep the same teaser on every page, reference one named question from each.Display
The Display section sets how the bubbles appear, for every page. Without changes they behave exactly as plain suggested questions always have. The bubbles use the chat’s body font (Theming → Typography → Body), so they match the chat they open; a body weight replaces their own.
A visit is the loader’s 30-minute session on your site, so a closed teaser or a played entrance is remembered across pages and open tabs until the visitor has been inactive for half an hour. Nothing animates while the page is in a background tab; the entrance starts when the visitor first looks at it. Visitors who have asked their system for reduced motion get the questions without cycling or animation. Use Replay next to Preview a page to watch the entrance in the launcher preview.
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’sstarting_message, in its action_grid.
Every starting-message type carries an optional action_grid:
An
action_grid has two fields:
Each item in
items is one button:
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.
Suggesting an action grid from instructions
Rather than writing buttons by hand, you can have Anyreach propose them from the agent’s instructions.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
Related
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.