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:
- Off (the default). A customer message that matches nothing is recorded — nothing is lost, nothing is sent — and no fallback reply is created.
- On. With the feature on and the conversation's consent opted in, an unmatched message fires exactly one fallback reply — and a second unmatched message the same day is deduplicated: a customer who pings five times off-script gets one careful fallback, not five. Turning the setting off again restores the default behavior.
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)
- The publish/versions/capacity lifecycle is documented in its own guides on separately-recorded evidence; this guide does not restate their claims.
- Human handover and safe editing appear in the older
docs/user-guidetree on that tree's own standing; they are not re-claimed here. - Live Meta traffic — the signed delivery in the run was harness-signed against the real route; no live Meta delivery, and no customer was messaged.
- AI features are not part of this guide and carry their own plan prerequisites (see the bots plan note).
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.