Resources · Reference architecture
The design we start from for an assistant on the WhatsApp Business Platform that answers order and booking questions, sends the updates people opted into, and passes a chat to your team without losing it. It is a reference design, not a client’s system; the rules Meta sets for webhooks and messaging windows are cited on this page with the date we checked them.
Layer: all four, centred on Reach
The problem
A WhatsApp assistant is a webhook service with rules attached. Meta delivers every message and status update to your endpoint, may deliver the same event more than once, and decides what you may send by how recently the customer wrote to you. Duplicate replies, updates that never send and messages to people who opted out all come from ignoring one of those facts, not from the model.
Components
Checks the X-Hub-Signature-256 header against your app secret, stores the raw event and returns 200 before anything slow runs.
Keeps every event by message id, so a redelivery is dropped and any run can be replayed.
One ordered lane per customer number: a burst of messages is handled in sequence, never in parallel.
Detects intent and language and drafts a reply from approved content or a lookup.
Order status, booking slots and store hours through your systems’ APIs, with scopes that cannot change data.
Checks the service window and consent before every send: inside the window the draft, outside only an approved template.
Paces sends and tracks delivered or failed status for each message.
Where each opt-in came from, its wording and time, opt-out keywords and the full history.
A teammate takes over in the inbox; the summary, consent state and templates sent are written to the contact.
Data flow
How it works
Mechanism 01
Meta retries webhooks it considers failed, and a model call can take seconds. So ingress does only cheap work: signature, store, 200. Everything else runs from a queue, and a retried webhook finds its message id already stored.
Simpler code, until a slow reply triggers a retry and the customer receives the same answer twice.
Mechanism 02
Customers write in bursts: a question, a photo, then the order number. Handling one number’s events in order, with a short pause for the burst to finish, lets the assistant answer the whole turn instead of each fragment.
Faster on paper; in practice replies arrive out of order and contradict each other.
Mechanism 03
Window and consent checks live in one place every send passes through, not in prompts. The model may draft any text; only the gate decides whether it goes out as written, becomes an approved template, or is not sent.
The customer wrote recently, so the reply goes out as drafted.
The draft is replaced by the matching approved template, if the contact opted in to that update.
Nothing is sent; the event is logged against the contact.
Models drift from instructions; a rule about what may legally be sent belongs in code.
Reference diagram
A WhatsApp message passes webhook ingress and a per-customer lane to the router and model, which use a read-only order lookup. Drafts pass a send gate that reads the consent store, then the sender delivers them; handoffs go to the team inbox, which writes a summary to your CRM.
Diagram with 13 parts: WhatsApp message (source), Opt-in form (source), Webhook ingress (processing), Consent store (system of record), Conversation lane (processing), Your order system (system of record), Router + model (model), Read-only lookup (processing), Send gate (control), Team inbox (human), Outbound sender (processing), Customer (human), Your CRM (system of record).
Connections:
Platform
The channel adapter, webhook ingress and the CRM write-back.
The send gate, read-only lookups and the takeover by a person.
The event store, send retries and the dead-letter list.
Answers from approved content when a question is not about an order.
Build or buy
| Option | Fits when | The trade-off |
|---|---|---|
| An inbox tool with a bot builder | Conversations are mostly human, menus are simple, and your team already works in that tool. | Logic sits in the vendor’s builder, and switching means rebuilding. |
| Build on this reference design | Answers need your order or booking data, rules differ by market, or WhatsApp is one channel of several. | You run a webhook service and a queue, and template approvals become your team’s job. |
| Combine | Keep the inbox tool for agents and run the assistant in front of it, passing chats over through its API. | Two systems on one number: the rule for who replies must be explicit, or both will. |
Rollout
Week 1
Your Meta Business account and number, opt-in wording, and the first templates submitted.
Weeks 1–3
Signed webhooks, dedupe, ordering and the send gate, tested with redelivered events.
Weeks 3–4
Intent routing, read-only order lookups and an eval set built from real chats.
Weeks 4–5
Takeover by a person and the CRM write-back, then launch on one click-to-chat link.
After launch
New templates as customers opt in, and per-market rules if you sell in more than one country.
Failure modes
Running cost
Defaults
Limits
Configuration
channel: whatsapp-cloud-api
webhook:
verify_signature: x-hub-signature-256
ack_before_processing: true
dedupe_key: message_id
ordering: one-lane-per-contact
send_gate:
inside_window: draft-allowed
outside_window: approved-template-only
require_opt_in: true
opt_out_keywords: [STOP, UNSUBSCRIBE]
templates:
order_dispatched: { category: utility, status: approved }
handoff:
triggers: [asked-for-person, repeated-confusion, complaint]
target: team-inbox
crm_writeback: [summary, consent_state, templates_sent]FAQ
Meta treats a failed response as a delivery failure and sends the event again. Replying 200 once the event is verified and stored stops those retries; the assistant works from a queue, and a repeat is recognised by its message id.
The send gate does not send it as written. If the contact opted in and an approved template fits, the template goes out with the details filled in; otherwise the message is held and a person decides.
Each customer number has one ordered lane, and the assistant waits briefly for a burst to finish, then answers the whole turn once instead of each fragment.
In your team inbox while the chat is open, then as a summary on the CRM contact with the consent state and templates sent. Raw events stay in the event store for the retention period you set.
We usually connect to the Cloud API on your own Meta Business account, so you own the number with no middle layer. A provider makes sense if your team already works in its inbox; the design stays the same.
Almost all of it. Ingress, dedupe, ordering, the send gate, consent and the CRM write-back make order updates reliable on their own; the router and model sit in the middle and can be added later.
Next step
Book a free 30-minute strategy call. Bring one process you want to automate and we will talk through scope, integrations and a sensible first step.
Free 30-minute call · no commitment