Building a bot flow — the building blocks, and what happens when no block matches

Who this guide is for: customer ADMINISTRATORS who build bots. You need a plan that includes bots and a seat with bot-management permission (see the bots plan note — Basic excludes bots entirely).

The other bots guides follow one bot through publishing, versions and copying. This guide covers two different things: what a flow is made of (the block types you can use, and the rules that keep the flow valid), and what happens when a customer writes something no block matches — the no-match fallback.

About the evidence. The bots, flows and inbound messages in the run behind this guide were test data, and the "Meta webhook" was a real signed delivery to the real route — the signature was computed by the test harness over the payload, not a live Meta delivery. No live WhatsApp/Meta message was sent.

What a flow is made of — the block types

When you create a bot, it starts as a new draft flow. Your bot list shows only your business's bots — another business sees none of them (verified). Inside the draft you can author each of these block types:

Block What it does Rule you may meet
Trigger (keywords) Starts the flow on exact, contains or starts_with matching An unknown matching mode is refused
Text + Buttons A message with tappable buttons The send shape is capped by the product
Plain message A text-only block Editable
Media + Buttons An image/document with a caption —
List Menu A menu with at most 10 items More than 10 is refused
API Request Calls an event by its slug A bad slug is refused (drafts only)
Ask Question Asks the customer and stores the answer in a variable Drafts only
Set Attribute Stores a key/value pair —
Carousel A TEMPLATE-typed card carousel (template name + cards) —
Location Request Asks for the customer's location Refused until your account is granted location messaging
If/else branch Splits the flow by conditions; branch labels travel on the lines —
Commerce (View Catalog / View Product / product list) Commerce blocks Refused without the commerce-catalog grant
Web View A button opening a web page The address must be https on a public host, with display/body text

Editing a block changes its settings and label, and reloading the flow returns exactly what you authored — positions and labelled lines verbatim. The connection rules refuse a line from a block to itself, duplicate lines, and lines that would cross into another bot: the flow's integrity is enforced by the server, not left to hope.

The keyword trigger's matching mode is honored at match time too: a miss is recorded honestly rather than forced into a hit.

Permissions: bot building is administrator territory — a member seat trying a bot write is refused with 403 SCOPE_DENIED.

The no-match fallback — "what if the customer says something my flow doesn't recognize?"

This is a behavior switch in your bot settings:

The front door — and the forged knock

Before any of the above can happen, an inbound message must pass the door. A properly signed webhook for a number your business owns is accepted. An inbound for a number your business does not own, or a forged signature, is refused and creates nothing — no message record, no reply intent, no side effect.

If you see an error

What you see What it means What to do
403 SCOPE_DENIED on a bot write Your seat is a member, not an administrator with bot permission Ask your administrator
Refusal on a List Menu with 11+ items Menus cap at 10 items Split into multiple menus or trim items
Refusal on Location Request Your account lacks the location-messaging grant Request the grant first
Refusal on Commerce blocks Your account lacks the commerce-catalog grant Request the grant first
Refusal on a Web View block The address must be https on a public host with display/body text Fix the address or add the required text
Bad-slug refusal on API Request The event slug does not exist Correct the slug (drafts only)

What this guide does NOT claim (kept honest)


Evidence record (kept for honesty). The FULL3747-O14EV lane executed suite o14-ev3747-s2-bots.pg.test.mjs — 26/26 cases passed, commit 3f49f092 on the combined candidate (C:/CT-ZC-FULL3747, branch codex/zcode-full3747) — real compiled application over real loopback HTTP against a throwaway PostgreSQL 16 cluster, including a real signed Meta-webhook ingress and the ADR005 drainProviderProjections runtime fallback. Verbatim case receipt: C:/CT-ZC-FULL3747/tools/zcode-integration3723/runtime/FULL3747-O14EV/evidence/O14EV-S2-BOTS-CASES.json (suite S2-bots, started 2026-10-25T00:12:16.287Z); cases cover matrix rows O02.01–O02.03, O03.01–O03.21, O04.04–O04.05. Standing: local-candidate, test-harness evidence; Chief acceptance and publication OPEN; no live or Main-built runtime claimed. The bot-lifecycle browser guides (publish and simulator, capacity and rollback, copy, export/import) stand on their own separately-recorded evidence.