WhatsApp Business

Three properties drive the whole design. Inbound traffic is a webhook, so the adapter is a public HTTPS endpoint that must authenticate Meta and must answer fast. Outbound traffic is a plain REST call authenticated with a bearer token, so the adapter owns a long-lived credential. And the conversation is governed by a 24-hour window that decides whether you may send free-form text or only a pre-approved template.

The Cloud API is the hosted version of the WhatsApp Business Platform: Meta runs the infrastructure, you call the Graph API. (The older on-premises API has been retired in favour of it; check the current documentation for its status if you inherit an old integration.) The objects you create, in order, are below.

The practical consequences for the adapter are about configuration. It needs five values, all supplied from the environment and never committed: the phone number ID, the access token, the app secret, a verify token that you invent, and the Graph API version. Store them in a secrets manager (for Azure, see Key Vault and Secrets) and rotate the system-user token on a schedule. The verify token is only a shared string used once during subscription; it is not a credential for the API, but it should still be random and kept out of source control.

Source: WhatsApp Business Platform: get started

You give Meta one callback URL in the app dashboard and subscribe the WABA to the messages webhook field. Two kinds of request then arrive at that URL.

Verification (GET). When you save the callback URL, Meta sends a GET request with the query parameters hub.mode (subscribe), hub.verify_token (the string you typed in the dashboard) and hub.challenge (a random string). If the token matches your configured value, the endpoint answers 200 with the challenge echoed back as the body; otherwise it answers with a client error. This proves that you control the URL; it proves nothing about who calls it later.

Notifications (POST). Every event is a JSON POST carrying an X-Hub-Signature-256 header of the form sha256=<hex digest>. The digest is an HMAC-SHA256 of the raw request body keyed with the app secret. The adapter must compute the same digest over the exact bytes it received and compare in constant time; parsing the JSON first and re-serializing it will change the bytes and break the check. Anyone who knows your URL can otherwise forge a message and make the assistant answer on behalf of an arbitrary "user", so this check is not optional. The endpoint should also return 200 quickly: Meta retries failed deliveries with decreasing frequency for up to seven days, payloads can batch several updates, and the same message can therefore arrive more than once. Deduplicate on the WhatsApp message ID (the wamid…​ string) and push slow work to a background task, as described in Channel-Agnostic Architecture.

The notification body has a fixed envelope. An abbreviated inbound text message looks like this (identifiers are placeholders):

Source: WhatsApp webhooks overview

The same value object carries a statuses array instead of messages when the event is a delivery receipt (sent, delivered, read, failed); the adapter should ignore those for answering but log failures. Other message types (image, audio, location, interactive replies, button) arrive in the same array with a different type, so the adapter must branch on type and politely decline what it does not support rather than assuming text.

The sender’s wa_id (in practice the phone number in international format) is the natural userId: WhatsApp has already verified that the person controls it. The conversationId can be the pair of the wa_id and your phone_number_id because a WhatsApp chat between a user and a business number is a single continuous thread; there are no threads inside it. A consequence worth planning for is that a very long single thread is also a very long memory, so the core should summarize or truncate as in Conversational RAG & Memory. The access-control rules from RAG Access Control & Privacy apply to this userId; if the assistant serves customers, map wa_id to a customer record (for example after a one-time linking flow) before you let the retriever see anything beyond public documents. Phone numbers are personal data: do not put them in logs or traces in clear text.

Every outbound message is a POST to https://graph.facebook.com/<version>/<phone-number-id>/messages with the bearer token and a JSON body that always contains "messaging_product": "whatsapp". A plain text reply to a user who wrote to you in the last 24 hours looks like this:

Adding "context": { "message_id": "wamid.<message-id>" } makes the reply appear as a quote of the user’s message, which helps when several answers are in flight. A successful call returns the new message’s ID, which you can correlate with the later status webhooks. The API also offers separate calls to mark an inbound message as read and to show a typing indicator; the adapter should use them as the equivalent of the typing state that XMPP gives you (see XMPP Bots), because retrieval plus generation can take several seconds. Text bodies are limited in length (currently a few thousand characters); the adapter should split long answers on paragraph boundaries and keep the first message self-sufficient, since there is no streaming to soften a long wait.

Source: Send messages

When a user messages your number, a 24-hour customer service window opens (and is renewed by each new user message). Inside it you can send free-form messages of any supported type, which is everything the DocsAssistant normally does. Outside it, only a template message is allowed: a message whose structure, language and category were submitted to Meta and approved in advance, with numbered or named placeholders filled at send time. Categories are utility (transactional updates), authentication (one-time codes) and marketing (promotions); the category influences price, review strictness and whether the user has to have opted in to that kind of message. Review is automatic and usually quick but can take up to a day, and an approved template can later be paused or disabled if recipients block or report it.

A template send names the template and fills its components:

Source: Message templates overview

For an assistant the window has two design consequences. First, an answer that takes longer than the window to arrive (for example after a human handoff, see Human in the Loop) cannot be delivered as free text and needs a template, so keep a small approved "your answer is ready, reply to see it" template for that case, and reply to it to reopen the window. Second, proactive messages (reminders, release announcements) are always templates and are subject to opt-in and to Meta’s marketing rules, so do not use the assistant as a broadcast tool.

WhatsApp supports a small set of structured messages that map well to RAG answers. Reply buttons offer up to three short choices, list messages offer a menu of selectable rows grouped in sections, and call-to-action URL buttons open a link. When the user taps a button or a row, the webhook delivers an interactive message whose button_reply or list_reply contains the id and title you assigned, which is an easy way to implement "show source", "this helped" and "talk to a person" without natural-language parsing. Button reply titles and list row titles have tight length limits, so use short verbs and keep the real payload in the id.

Source: Send messages

Citations have no card format on WhatsApp. The pragmatic rendering is numbered markers in the text plus a final line of short URLs (WhatsApp makes them tappable), or a list message whose rows are the sources. The layout choices and the feedback loop are discussed in Citations & Grounding and Agent UX. WhatsApp also renders a limited text markup (asterisks for bold, underscores for italics, backticks for monospace), which is not Markdown; convert the core’s Markdown output rather than sending it as is.

Since 2025-07-01 the platform charges per delivered template message according to its category and the recipient’s country, while free-form messages inside an open customer service window are not charged per message. Rates, free-entry-point rules and volume tiers change often and differ by market, so this page deliberately gives no numbers: read the official pricing page and its rate cards when you size a deployment. For capacity planning the useful quantity is the number of template messages per month, \( N_{\text{tmpl}} \), times the per-message rate of each category and country; an assistant that only answers inside the window has \( N_{\text{tmpl}} \approx 0 \) apart from re-engagement templates, and its main variable cost is the model, not the channel. A separate quality rating and messaging-limit system governs how many distinct users you may start conversations with each day and is raised by business verification and good user feedback.

WhatsApp restricts what kind of AI product may run on its business API, and that restriction is the first thing to check before you plan a deployment. The authoritative text is the WhatsApp Business Solution Terms (the address redirects to the current Meta-hosted page). The terms were updated with an AI-related clause that Meta announced would apply to all accounts from 2026-01-15. The text of that clause could not be re-read while this page was written, so what follows is the commonly reported reading and not a quotation: general-purpose AI assistants, that is chatbots whose primary function is to be an open-ended assistant or large-language-model service offered to the public, are not permitted on the Business Solution, while AI used by a business for its own customer interactions, such as support, sales assistance or answering questions over its own knowledge, remains allowed. Read the current terms yourself, with your legal or compliance contact, and re-read them whenever you ship a material change to the assistant, because the wording, the examples and the enforcement practice are Meta’s to change.

How the DocsAssistant pattern sits against that reading is a design question you can influence:

Two implementation habits reduce the risk regardless of the exact wording. Identify the bot as automated in the profile and first message and offer a path to a human (see Human in the Loop), and keep an audit trail of what the bot is configured to do. Policy, privacy and data-processing questions for the model provider that sits behind the core are separate and are covered in RAG Access Control & Privacy.

The webhook is one FastAPI app with a GET route for the handshake and a POST route for events. The handler reads the raw body for the signature check, returns 200 straight away and schedules the answer as a background task. ask is the async generator of the LangChain core (create_agent, retriever tool, Postgres checkpointer) described in Channel-Agnostic Architecture; for the underlying framework see Agents with create_agent and Short-Term Memory & Checkpointers. Deployment of the app behind HTTPS is covered in Serving RAG as an API.

Source: Create a webhook endpoint and FastAPI background tasks

Several details are deliberate. The GET handler uses the dotted query names through Query(alias=…​) because FastAPI cannot declare a parameter called hub.mode otherwise. The signature is checked with hmac.compare_digest over the raw bytes before any JSON is parsed. The in-memory seen set makes the example short but is wrong for more than one worker or for restarts; use a shared store with an expiry slightly longer than Meta’s retry horizon, or make the handler idempotent by keying the checkpoint on the message ID. FastAPI’s background tasks run in the same process after the response, which is fine for a few seconds of generation but loses work if the process dies; for slow or critical answers use the queue-and-worker variant from the architecture page. Finally, nothing here prevents two concurrent messages from the same user from running at once; serialize per conversation_id, because the checkpointer does not order concurrent writes for you.

The Spring adapter has the same three parts: a controller with the handshake and the notification endpoints, a signature check over the raw body, and a client that calls the Graph API. The AssistantCore.ask method returns a Flux<CoreEvent> as in the architecture page; the adapter collects it into one message with reduce, because WhatsApp cannot show partial text. See ChatModel and ChatClient, Chat Memory Repositories and Production and Deployment for the core, and REST APIs for the controller basics.

Source: Create a webhook endpoint and Spring Framework REST clients

Because citations in the core are emitted after or among the tokens, the reducer simply appends them as text lines; a production adapter would instead collect tokens and citations separately and format the final message once. The @RequestBody byte[] parameter is what gives the signature check the unmodified bytes: if you bind to a JSON type first, Spring re-serializes and the HMAC no longer matches. The property names in @Value are placeholders for Spring configuration that is itself fed from environment variables or a secrets store; do not hard-code them in application.yml. Everything said about deduplication, per-conversation serialization and queues in the Python section applies unchanged, and the observability hooks of Observability cover tracing a turn across the webhook and the model call.

Twilio is one of the Business Solution Providers that resell WhatsApp access. You keep the same assistant core but replace the Meta app, WABA and token plumbing with a Twilio account: Twilio registers the sender, hosts the webhook contract and bills you for both its own fee and the WhatsApp charges. For development it offers a sandbox number that any WhatsApp user can join by sending a keyword, which is the quickest way to try an adapter without a business verification. The main differences from the direct Cloud API are listed below.

The Twilio adapter in FastAPI is shorter because the SDK validates the signature and sends the reply:

Source: Twilio WhatsApp and Twilio webhook security

Twilio waits at most 15 seconds for the webhook response and otherwise logs error 11200, which a full generation can easily exceed, so the handler only validates the request, schedules the answer as a background task and returns an empty TwiML document at once. The Twilio client is synchronous, so the background task calls it through run_in_threadpool to keep the event loop free (a durable worker is the production equivalent), and note that Twilio imposes its own shorter message length limit. Using a provider does not remove the Meta policies: the Business Solution Terms, the AI-provider rules and the opt-in requirements still apply to your use, and the provider’s own terms apply on top.

Meta requires that a person has opted in to receive messages from your business on WhatsApp before you message them outside a conversation they started. For an inbound-only assistant the user’s message is the opt-in for the answer, but anything proactive needs a recorded consent that names the business and the kind of messages, collected on a form, in person, on the web or inside another channel. Keep the consent record (who, when, what wording, which number), honour opt-outs immediately (a keyword such as STOP should switch off proactive messages, and the assistant must not reply to it with more marketing), and expect Meta to rate-limit or restrict numbers that users block or report. The remaining obligations are ordinary data-protection ones, and they apply with extra force because the phone number is the identifier:

The signature, retry, deduplication and secret-handling practices for all channels are collected in Operating Chat Channels, and the one-page summary is in the Cheat Sheet (PDF).