Starter questions

A shopper who doesn't know what to ask usually asks nothing. Starter questions are the short, tappable questions that give them a first move: tap one and the conversation opens with that question already sent.

They live in one place per site (a library) and they are shown on up to four surfaces at once: the chat welcome screen, the question bar, the chat bubble and the inline Starters card. You write a question once; every surface that has starter questions switched on picks it up. You can also have AISA write questions for you from your pages: they land in the same library, switched off for you to review, unless you switch generated questions on.

Open Engagement → Questions in the dashboard sidebar for a site, or go to /dashboard/sites/{siteId}/questions.

They apply immediately: no draft, no publishCopy Anchor Link

A starter question is not versioned. Creating one, rewriting its text, changing where it can show, switching it off or deleting it takes effect at once, everywhere, on your live storefront included. There is no draft to publish and no version history to roll back to.

What is versioned is the switch that decides whether a surface shows chips at all:

So the content is live and the on/off is versioned. That's deliberate: fixing a typo in a shopper-facing question shouldn't wait for a release, while turning a whole surface on or off is a configuration change you may want to publish, keep, or revert.

What a question is made ofCopy Anchor Link

A question has no name of its own: the grid identifies it by its text in the site's default language, or by any language it does carry.

Write a questionCopy Anchor Link

Creating and editing each happen on their own page, not in a dialog.

• New question sits beside the page title and opens /dashboard/sites/{siteId}/questions/new. On an empty library that button isn't there; the empty state's Write your first question goes to the same page.
• Edit, in a row's ⋯ menu, is an ordinary link to /dashboard/sites/{siteId}/questions/{questionId}, so middle-click and "open in new tab" work. Clicking anywhere else on the row does the same thing.

An edit page holds the question's own Live switch and current status above the two cards below, and a Delete this question section beneath them.

• The Live switch and its status hint (the same label and hint the grid shows, e.g. "Shows in French only") writes immediately, same as the grid's switch. Deactivating a currently Live question asks for confirmation first; every other toggle applies at once.
• Delete this question removes the question everywhere, with the same confirmation as the grid's Delete; if the question is currently Live, the confirmation also offers Turn it off instead as a non-destructive alternative.

The two cards in between hold the actual content.

Wording holds the text for each language your site has enabled. On a one-language site it's just the fields below. With several languages, a compact language list sits before the language's fields and shows the code of the language on screen (EN). Open it to switch: it lists every language by code and name, your site's default language first, marked Main, and shown when the form opens. Language names follow the language of your own dashboard profile. No other language is offered, and a language your site hasn't enabled is refused on save.

Per language:

• Question, up to 60 characters with a live counter under the field. What the shopper reads on the chip. On the chat bubble a chip that doesn't fit is clipped to one line with an ellipsis. On the question bar and the Starters card it wraps onto a second line and is cut with an ellipsis after two.
• Message sent, badged Optional, up to 500 characters. Use it when the chip should read short but the message sent should be precise: question "Find my size", message "Help me find my size in this product". Empty means the question itself is sent.

A question is optional in every language: nothing is filled in for you and an empty language never blocks the save. Until you write the question in at least one language, every empty language reads "Not written yet". Once one language has text, leave another blank and its fields say so: "Not offered in French". If it's the default language you leave blank while another is written, the same words show under the default language's fields. A language you leave blank isn't saved as an empty string. It's saved as "this question doesn't exist in that language", which is exactly how it behaves.

Where it can show is the second card: choose exactly one of All pages, Page types, or Specific URLs, never a combination. Switching mode clears whatever the question had recorded for the other two.

• Page types needs at least one of Home, Category, Product, Content, Blog checked, matched against the page's type: the one your tag declares or, when it declares none, the one your site's Pages hold for that address.

• Specific URLs matches the shopper's actual address instead of a declared page type. Add up to 10 patterns, 200 characters each; the question is eligible the moment any one pattern matches. A pattern uses a single wildcard, *, standing for any sequence of characters. There's no regular-expression syntax:

  Pattern	Matches
  produits/*	Any address starting with produits/ (every product page, if that's your URL structure)
  */promo/*	Any address that contains /promo/ anywhere
  checkout	Only the address checkout, exactly (no * at all)

  Write patterns without a leading slash (produits/*, not /produits/*): matching strips it for you. Matching is case-sensitive.

  A site holds at most 100 questions with a * pattern, switched on or off. Past that, saving, duplicating or creating one over the API is refused (wildcard_question_limit_reached) and nothing is changed. Delete a wildcard question or use exact patterns. Exact patterns, like checkout, don't count.

Create question (new) and Save changes (existing) stay disabled until at least one language carries a question. Cancel is a link back to the library and saves nothing. A successful save takes you back to the library too.

The library gridCopy Anchor Link

Rows are shown in library order by default, 50 to a page. The number in the first column is the position that decides which questions win a slot, counted across pages (the second page starts at 51). It is shown only in the library's own order: while a search, a filter or a sort is on, the column is empty, because the rows are no longer in that order. Click anywhere on a row to open its edit page.

• Question: the text the site's default language carries, with a note when that language sends a different message than the question.
• Target pages: All pages, the checked page types, No page when nothing is selected, or Specific URLs for a question in URL-pattern mode (the badge names the mode and, under it, the pattern itself). For a generated question, the pattern links to the page it was written from while that page still exists.
• Type: Written by you, AI or AI, edited. See Generated questions.
• Status: see below.
• CTR · 14 days: how often a shown question gets tapped. See How well a question performs.
• Performance: the same section's verdict.
• Updated: when the question last changed, text edits included.

Status, CTR, Performance and Updated sort the whole library, not only the rows on screen: click a column header to sort by it, click again to reverse direction, click a third time to clear the sort and return to library order. Status sorts by Live → Partial → Needs setup → Offline, not alphabetically. CTR sorts numerically, with a question that's never been shown always sorted to the bottom rather than read as a 0% rate. Performance sorts by where the work is first: Underperforming → Promising → Not enough data → Workhorse → Never shown. Questions that tie keep their library order.

Search, filters and pagesCopy Anchor Link

Search and the filters are applied to the whole library, then the result is cut into pages of 50. They, the sort and the page you are on are kept in the address, so a link or a reload brings you back to the same view.

• Search matches both the questions and the messages, in every language, and the address of the page a generated question was written from: paste a page's URL to find the questions AISA wrote from it.
• Page type, Type (All types, Written by you, AI-generated and AI-generated, edited, each one on its own) and Status narrow the list. The page-type filter keeps the questions that reach that page type: an All pages question reaches every type, a Page types question reaches the ones it lists. A Specific URLs question carries no page type, so it drops out whenever that filter is set to anything but "All".
• Language has two choices for each language your site serves: Has text in the language, or Missing text in it. Use the second to find the questions a shopper in that language never sees.
• Changing a search, a filter or a sort takes you back to the first page.

The last row of the grid shows the range ("51 to 100 of 212") and, when the result spans more than one page, Previous and Next to move one page at a time. When everything fits on one page, the range stays and the buttons don't show. When something narrows the list, the count of the whole library follows ("212 in the library"). A search or filter that matches nothing shows No question matches and a button to clear them.

From this page. On a page's view under Pages, the Starter questions card has a Review in Questions link. It opens this grid filtered to the questions generated from that page, with a chip reading "From" and the page's address. Click the chip to remove the filter. If the page was removed, the chip reads "From a removed page". This filter has no select of its own.

The four statusesCopy Anchor Link

Partial is the one status with no widget equivalent, and it exists because a widget's own text falls back to your site's default language while a starter question never does. See Missing text is silence, not a fallback.

Row actionsCopy Anchor Link

The Live switch sits in the Status column, beside the state label, and applies immediately. The same switch is also in the ⋯ menu, as Activate / Deactivate. Taking a currently Live question offline (from either the switch or the menu) asks for confirmation first; every other transition (turning one on, or turning off a question that isn't Live) applies at once. The ⋯ menu also holds:

• Edit: opens the question's own page. Saving applies at once.
• Duplicate: copies the text and targeting (page scope or URL patterns, whichever the question uses) into a new question at the top of the library, not next to the original.
• Move up / Move down: one place at a time. There's no drag-and-drop.
• Delete: asks for confirmation first, then removes the question everywhere. This can't be undone.

On a view-only role (Starter questions: View without Edit) the grid, the filters and the statuses all stay readable, and every write affordance is simply absent: no New question, no switch, no ⋯ menu. Opening a question's page still works and shows it read-only, with every field disabled and no Cancel / Save changes footer at all. Opening the create page instead sends you back to the library, since there'd be nothing on it to read.

Generated questionsCopy Anchor Link

AISA can write starter questions from any page it has read under Pages: product, category, home, content and blog pages, and pages whose type it could not tell. A generated question is an ordinary library question with a few differences.

• It starts switched off, unless the site switches it on. By default it reaches no shopper until you switch it on. With Switch generated questions on set in Site access, or the box ticked in the Generate dialog, it is live on its page as soon as it is written. The setting changes only the questions written from then on.
• It targets the page it came from. Its mode is Specific URLs, with the page's own path and query as the one pattern. The one exception is your site's home page (/): a URL pattern cannot name the site root, so a question written from it uses Page types with Home checked, and shows on every page of that type.
• It has one language. The language of the page. Write the other languages yourself if you want them.
• It is marked. The Type column reads AI, and the row is tinted slightly.

Because a generated question usually uses Specific URLs, it has that mode's limits: it matches the shopper's real address, so it works on the question bar and chat bubble widgets. On the chat welcome screen it is matched against that surface's own address and will in practice almost never show. See the warning under Write a question.

After your first edit of its wording or its targeting, a generated question reads AI, edited. It stays that way. Switching it on or off, and moving it, do not count as an edit. Duplicating a generated question makes a Written by you copy.

The review noticeCopy Anchor Link

When at least one generated question is switched off, a notice above the grid says how many are waiting: "3 generated questions are waiting for review". Show generated sets the Type filter to All AI-generated, which holds both kinds, and the Status filter to Offline. The notice counts edited questions that are still off too, and it appears for a view-only role as well, since the button only filters the list.

A generated question's own pageCopy Anchor Link

Opening one shows a banner above the wording: the badge (AI-generated or AI-generated, edited), when AISA wrote it (and when it was edited), and a link to the page it was written from. If the page was removed, the banner says so and the question stays. While the question is off, the banner adds that it stays off until you switch it on. If it is still AI-generated, it adds that editing keeps it off and changes its type.

When the question was checked against page text instead of your catalog, the banner says "Checked against the page text, not your catalog." and "The assistant may not be able to answer it until it can read your pages." See Evidence.

For a content, blog or unknown page this is the usual case. Whether the assistant can read the page during a conversation depends on its agent version: only a version with the Site page tools can, and a version created before them does not have them. A question generated from such a page can ask about the page itself, and the assistant may answer it only in part. Read these before you switch them on.

The Performance block works as for any other question. A question that was never shown reads "No impressions yet".

Replacing generated questionsCopy Anchor Link

Generating again for a page deletes that page's earlier generated questions that nobody edited or switched on or off, when new ones are written, unless you untick Replace earlier generated questions. Whether such a question is on or off does not matter: a question that was written switched on by the site setting is replaced too, as long as no member touched it. A question a member switched on or off, a question edited, and any question you wrote, is never replaced. An automatic generation goes further and skips a page that already has live questions of that kind, so it never replaces what shoppers see. Removing a page, then adding it again, makes a new page: its questions are not linked to the old ones, so both sets stay. Questions are not regenerated when a page changes.

Where the chips show upCopy Anchor Link

The chat welcome screenCopy Anchor Link

Before the first message, up to three chips sit under the welcome message, in the AI Storefront, the embedded panel and every Playground pane. This surface is gated by the agent version serving the conversation.

The version's Alignment control (Left / Center / Right) positions the chip column here. See Conversation starters.

A question too long for one line wraps onto as many lines as it needs inside its chip, and the wrapped lines follow the version's Alignment setting.

The question bar and the chat bubbleCopy Anchor Link

With Show starter questions on in a widget's Content tab and the draft gone live, the widget renders up to three chips stacked directly above itself, inside the widget's own surface. Their alignment isn't configurable: a question bar's chips align to its bar's leading edge, a chat bubble's to the corner it's docked to. Colours are the widget's own resolved foreground and background, inverted, so the chip is a filled pill in the widget's text colour.

A question bar shows no chip at rest. Its chips appear, one by one with the bottom one first, when the shopper puts focus in the bar, and go away when focus leaves. At rest the bar types the same questions into its empty field instead. A question bar's chips are 14px (15px at 767px or less), as wide as the question needs up to the bar's engaged width, and wrap onto two lines at most. In French, a narrow no-break space goes before ?, !, :, ; and ». See The question bar.

Because the chips live inside the widget, they follow it: they disappear while the conversation panel is open, and a widget its page targeting excludes takes its chips with it.

The inline Starters cardCopy Anchor Link

The Starters widget places the same chips inside your page layout, in a card with a heading you can switch off and a free-text field. It has no on/off switch for chips: it always shows the ones the library resolves for the page. In the report and on a question's page, this surface is named Starter questions.

Which three questions get shownCopy Anchor Link

Every surface shows at most three chips, and the selection is the same for all of them: walk the library in order and take the first three questions that qualify. There is no per-surface choice, no rotation and no randomisation, so a question bar and a chat bubble on the same page show the same three chips.

A question qualifies when all of these hold:

1. Its Live switch is on.
2. It carries text in the language the surface resolved to.
3. Its targeting admits the page (page scope for an All pages/Page types question, at least one matching URL pattern for a Specific URLs one), and, on a widget, the widget's own page targeting admits it too. All applicable rules are applied; none overrides another.

When more than three questions can reach the same page type, only the first three in library order actually render. The rest sit idle. Nothing on the grid names the contest up front any more; instead, a question that never wins a slot reads Never shown in the Performance column, with "never wins a slot against its higher-ordered siblings" as the reason on hover. Reorder with Move up / Move down, right there in the same row, to give it a chance.

Missing text is silence, not a fallbackCopy Anchor Link

A question with no text for the shopper's language is skipped. It doesn't render blank and it doesn't fall back to another language, not even to your site's default. It also doesn't consume one of the three slots, so three German-authored questions always give a German shopper three chips even if the library holds twenty French-only ones.

This is deliberately stricter than a widget's own text: a chat bubble's label or a question bar's placeholder does fall back to your site's default language. The chips don't, because a chip has to agree with the panel it opens, and that panel shows nothing for a language you haven't written.

The practical consequence: watch the Partial status. A question missing one language is invisible to the shoppers who speak it, and nothing on the storefront will tell you.

Where there is no page context, page scope isn't appliedCopy Anchor Link

The AI Storefront, the Playground, and a page on your storefront that has no page type (nothing declared, none held in Pages) have no merchant page to match against, the widget's chips included. There, page scope is ignored entirely and every enabled question with text in that language is eligible, so a question scoped to Product still appears in the Playground. That's on purpose twice over: a page-scoped question you're testing would otherwise show nowhere you can see it, and a widget's chips and the panel they open must never offer different questions on the same page.

This "no context, so always eligible" rule is specific to Page types scope. A Specific URLs question is never given that free pass. See the callout above.

How well a question performsCopy Anchor Link

Every question that's actually shown to a shopper is measured: one impression when it renders on screen, one click when a shopper taps it. On a question bar, a chip counts as shown once the bar has revealed it, never when the typewriter typed the question. The grid's CTR · 14 days column and Performance column, and a matching block on the question's own edit page, turn that into a verdict, so you can tell a question that's earning its slot from one that's wasting it, without reading a report.

The verdict, and what to do about itCopy Anchor Link

"Enough impressions" means 200 or more in the 14-day window. Below that, a rate is too noisy to call a win or a loss, so the verdict says so instead of guessing. Promising and Not enough data are both below that floor; the only difference between them is whether the rate already looks strong.

"Above" or "below" your site's own average is judged against your site's own click-through rate over the same 14 days, never an industry number, and never another merchant's. A question within 15% of that average, in relative terms, still reads as Workhorse, so a question a fraction of a point off the average doesn't flip label every time the page refreshes.

The window is fixed at 14 days everywhere the grid and the editor show it. There's no way to widen or narrow it on these two surfaces. The Starter performance tab of the Engagement report covers the same numbers over whatever date range you pick there, one page of 50 questions at a time, sortable by impressions, clicks and click-through rate.

Every verdict is shown next to the numbers it comes from (impressions, clicks, and the rate), never as a bare label. Hover a verdict for the sentence explaining it.

Never shown, and whyCopy Anchor Link

A question with no impressions in the last 14 days reads Never shown, always with one of these five reasons:

• Too recent. Created after the 14-day window opened: there hasn't been time to measure it yet.
• Disabled. Its Live switch is off, so it's served to nobody.
• No page types. Selected page types with nothing checked, so it targets no page.
• No content. No text in any language yet.
• Never wins a slot. It's otherwise eligible (enabled, targets a page, has text), but higher-ordered siblings always fill the three available slots first. Move it up to give it a chance.

These five cover every case, in this order of precedence: a question created too recently always reads "too recent" first, even if it also happens to be disabled or untargeted. "Not yet measured" is the honest read for a question you just wrote. A question you switch off keeps showing "too recent" only if it's genuinely brand new; otherwise the reason moves down this list.

On the question's own pageCopy Anchor Link

Open a question and its Performance block sits above the wording, inside the same status card: the verdict, the three raw figures (impressions, clicks, CTR), a 14-day rate-over-time chart, and a table breaking the same numbers down by surface (welcome screen, question bar, chat bubble, Starter questions), so you can see where the taps actually come from. A surface the question never rendered on reads Not shown here, never a 0% rate. A Full report link opens the Starter performance tab of the Engagement report, which covers your questions over a range you choose.

A question with zero impressions shows only the verdict and its reason. There's nothing else to evidence yet.

Removing a language deletes its questions' textCopy Anchor Link

Removing a language from your site's enabled languages permanently deletes that language's question and message from every starter question on the site. The Languages card counts starter-question text when it decides whether to ask you to confirm.

The question itself survives even if it ends up with no text in any language: it keeps its targeting and its place in the library, and the grid reports it as Needs setup so you can write new text instead of rebuilding it.

PermissionsCopy Anchor Link

Viewing this page requires Starter questions: View; creating, editing, reordering, switching, duplicating or deleting a question requires Starter questions: Edit. Both built-in roles, Admin and Member, hold both. Without either, Questions doesn't appear in the Engagement section of the sidebar at all, and opening the URL directly shows a restricted-access message naming what you're missing. Asking for questions from your pages is a separate step with its own permission: see Pages. See Roles.

Over the API and MCPCopy Anchor Link

The library is available over the REST API and the MCP server, under the same rules as the dashboard.

• REST: list, read, create, edit, duplicate, move and delete questions, under /api/v1/sites/{siteId}/starter-questions. A question created over the API is hand-written (the request cannot set a source) and is live at once unless you send enabled: false. A language the site does not serve is refused with language_not_enabled. The list shows each question's state, source and 14-day performance, and can show what a shopper would be offered on a given page. It takes the same search, filters and sorts as the dashboard (search, reachesPageType, language with languageMatch, source=generated for both kinds of generated question, sort and order), and meta.matching counts the questions the filters leave. See List a site's starter questions.
• MCP: list_starter_questions reads the library (with the same search, filters and sorts as the list endpoint), and create_starter_questions, update_starter_questions, set_starter_questions_enabled and delete_object write to it, in batches of up to 50. get_report with the starter_questions report gives each question's impressions and clicks over a period you choose, one page at a time. See the tools.
• Performance over a period: GET /api/v1/sites/{siteId}/starter-questions/performance returns the figures of the Starter performance tab.

Writing over MCP needs the member who connected to hold Starter questions: Edit. Each change is recorded in Admin activity, and an edit that changes a generated question's wording or targeting marks it AI, edited exactly as in the dashboard.

Not in this versionCopy Anchor Link

• No automatic publishing of AI-written questions. AISA can write questions from your pages, but every one starts switched off and waits for you, unless you chose to switch generated questions on in Site access.
• No regex or device targeting. URL targeting is single-wildcard glob only, and (see the callout above) it only works reliably on the question bar and chat bubble widgets, not the chat welcome screen.
• No per-surface selection. You can't give the chat bubble a different three than the question bar.
• No breakdown by page type. The verdict and the report both cover a question's performance as a whole, not split by page type.
• No per-widget comparison. If a question shows on both a question bar and a chat bubble, there's a per-surface split (see How well a question performs), but not a comparison across the widgets configured on your site.
• No link to sales. A verdict tells you whether a question gets tapped, not whether that conversation led to a purchase.
• No per-language performance. A question's rate is measured across every language it's shown in, combined, not broken out per language.