WHATSAPP · GUIDE
WhatsApp Cloud API Messages, Templates, and Webhooks
A WhatsApp product needs both outbound API calls and reliable webhook processing. Use Meta's current message categories and template status, and build delivery tracking from webhooks rather than assuming an accepted API request means a message was delivered.
Outbound message flow
Route every send through a server-side service that first authorizes the user's workspace, resolves that workspace's connected phone number and token, checks message eligibility, and records the provider result. Keep message content and recipient data scoped to the owning organization.
Steps
- Check the recipient's opt-in, allowed purpose, and suppression/opt-out status before sending.
- Determine whether the conversation is within Meta's open customer service window. Use an approved template for business-initiated outreach or whenever the applicable rules require one.
- Validate template name, language, category, and parameter count against the connected account's approved template data.
- Enqueue the send with tenant and connection identifiers, apply rate limits, and use safe retry rules that account for ambiguous provider outcomes.
- Store the provider message ID and initial response, then update delivery, read, and failure status from verified webhook events.
Templates and customer service window
Meta template messages are categorized as marketing, utility, or authentication. Non-template service messages are generally used to respond during an open 24-hour customer service window that starts or resets when the user messages the business. Use Meta's current rules for the exact message type, eligibility, and window behavior.
- Provide a template manager that displays approval status and prevents use of rejected, paused, or otherwise unavailable templates.
- Use utility templates for eligible transactional or informational use, authentication templates for verification use cases, and marketing templates for promotional objectives; Meta determines category and policy treatment.
- Handle inbound user messages and customer requests promptly; do not use non-template free-form messages to initiate outreach outside the allowed window.
- Keep consent, opt-out, and suppression state available to the message-sending service.
Receive and validate webhooks
Meta webhooks carry inbound messages, outgoing message status changes, and account/template events. The endpoint must support Meta's verification handshake and validate event authenticity before accepting production events.
Steps
- Create a public HTTPS webhook endpoint and complete Meta's endpoint verification handshake using a server-side verify token.
- Validate the
X-Hub-Signature-256signature against the raw request body and Meta app secret before processing events. - Resolve the connected account/phone identifier to exactly one authorized AtServiceTech tenant; reject or quarantine unknown mappings.
- Persist the event or enqueue it durably, acknowledge promptly, and process it asynchronously.
- Deduplicate by provider event/message identifiers, handle out-of-order status events, and maintain retry/dead-letter monitoring.
- Subscribe only to the webhook fields needed for the launched product and keep subscriptions healthy after onboarding.
- Do not trust a workspace or tenant ID supplied inside an unverified webhook payload.
- Redact credentials and unnecessary message content from logs; restrict webhook payload access.
- See Meta's WhatsApp webhook overview.