WhatsApp message lifecycle

Connect an enrolled business number#

The backend includes a WhatsApp Cloud API adapter bound to a business account and phone-number identity. Setup supplies the attachment, provider credentials, verification token and callback route. Runtime and channel enrollment must be enabled for the environment before customer traffic can be processed.

Verify, store, then acknowledge#

The configured worker exposes GET and POST /v1/webhooks/whatsapp/{attachment_id}. GET handles the verification challenge. POST verifies the exact signed request bytes and checks both business-account and phone-number identity before normalizing messages and status receipts.

The whole accepted batch is persisted before the callback returns 200. Duplicate callbacks are deduplicated. Unsupported media is recorded as unsupported input; it is not silently treated as a supported text message.

Inspect the conversation#

For example, a customer asks for an existing request’s status. A configured agent can call the permitted read tool, use the returned evidence and queue a reply. Read the conversation, turns and operations through the Conversation API to inspect what happened.

WhatsApp ingress comes from its verified channel. POST /v1/conversations/{id}/messages is the API-conversation input path; do not use it to impersonate an inbound WhatsApp message.

Track acceptance and delivery separately#

The outbox checks current send authority, channel capabilities and applicable template approval before dispatch. A provider acceptance is distinct from delivered or read. Missing later receipts do not undo an earlier confirmed state.

Template sends require the approved language and supported body-only positional text parameters. Do not assume attachments, buttons, template translations or a new send are permitted. If an attempt’s outcome is unknown, preserve that state for recovery.