--- title: "WhatsApp" source: https://sumgenius.ai/docs/webhook-whatsapp generated: 2026-08-26 --- # WhatsApp Receive WhatsApp messages as webhook events and send free-form text or approved templates through the [Send API](https://sumgenius.ai/docs/send-api). This page covers only what is specific to WhatsApp: the shared envelope and signature verification live on [Receiving Webhooks](https://sumgenius.ai/docs/receiving-webhooks#verify), the full field reference on [Webhook Events](https://sumgenius.ai/docs/webhook-events#envelope), and API keys on [Authentication](https://sumgenius.ai/docs/api-authentication). Add-on · $29/month · Requires Professional+ plan ### Overview ChatGenius routes WhatsApp through Meta's **Cloud API directly** (not Twilio). Meta is the WhatsApp transport sub-processor on this channel. Once provisioned, both inbound forwarding and the outbound Send API work alongside SMS, Facebook DM, and Instagram DM. `source.channel` is always `whatsapp_cloud`. Capabilities - Inbound forwarding Text, image, audio, video, document, sticker, location, contacts, and button replies forwarded as `whatsapp.message_received` events. - Outbound free-form text `send_message` with `message_text`, within the 24-hour customer-care window. See [Sending](#sending). - Outbound templates Approved templates sendable any time via `template_name` + `template_language` + `template_components`. See [Templates](#templates). - Pure-relay mode Turn off the WhatsApp AI Assistant (or enable Global External Reply Mode): inbound still forwards, no AI reply. > **Note** > > **Requirements:** Professional or higher tier (WhatsApp is included), a connected WhatsApp Business Account with a verified phone number, and the Webhook & Send API add-on active. The `whatsapp.message_received` checkbox is disabled until a business number is connected. **Source block on every WhatsApp event** ``` "source": { "platform": "whatsapp", "channel": "whatsapp_cloud" } ``` ### Inbound payload Inbound WhatsApp events use the standard envelope ([field reference](https://sumgenius.ai/docs/webhook-events#envelope)) plus a WhatsApp-specific `message.whatsapp` sub-block. WhatsApp-specific fields - customer.platform_user_idstring WhatsApp `wa_id` (E.164 digits, no leading +). Always present. - customer.phonestring Same value, mirrored for parity with SMS. Present in `full` profile only. - customer.profile_namestring|null WhatsApp profile name from Meta (best-effort). - message.idstring Meta `wamid`. Use for idempotent processing on your side. - message.whatsapp.business_phone_number_idstring The recipient business phone number ID (yours). - message.whatsapp.message_typestring One of `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `contacts`, `interactive`, `button`, `reaction`. - message.whatsapp.context_message_idstring|null The wamid this message replies to (button replies, threaded replies); `null` otherwise. - message.attachmentsarray For media-type messages, populated with `media_id`, `mime_type`, `filename`, etc. Always an array. See [attachment fields](https://sumgenius.ai/docs/webhook-events#attachments). **whatsapp.message_received · full profile** ``` { "event_id": "f8e7d6c5b4a3021918273645ded0c9ba", "event_type": "whatsapp.message_received", "occurred_at": "2026-05-05T18:30:00Z", "source": { "platform": "whatsapp", "channel": "whatsapp_cloud" }, "conversation": { "id": 4982 }, "customer": { "platform_user_id": "15551234567", "phone": "15551234567", "profile_name": "Jane Doe" }, "message": { "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBJCRkE5...", "text_raw": "Yes, please confirm my order", "attachments": [], "whatsapp": { "wa_id": "15551234567", "phone_number": "+15551234567", "business_phone_number_id": "108765432109876", "profile_name": "Jane Doe", "message_type": "text", "context_message_id": null } }, "meta": { "version": "v1", "payload_profile": "full", "generated_at": "2026-05-05T18:30:00Z" } } ``` ### Sending WhatsApp messages Use the shared Send endpoint. Set `platform: "whatsapp"` and `to_phone` in E.164 format (with or without leading `+`). Request bodies, idempotency, response format, and errors are on the [Send API](https://sumgenius.ai/docs/send-api) reference: [send_message](https://sumgenius.ai/docs/send-api#send-message), [idempotency](https://sumgenius.ai/docs/send-api#idempotency), [responses](https://sumgenius.ai/docs/send-api#response-format), [errors](https://sumgenius.ai/docs/send-api#errors). Channel rules - 24-hour customer-care window Free-form text requires the recipient to have messaged you in the last 24 hours (Meta's rule). Outside that window, use a [template](#templates). - Free-form body max4,096 chars - Usage counting Each successful outbound request counts as 1 unit against your outbound counters. Examples on this page use the [Send API](https://sumgenius.ai/docs/send-api). New integrations should prefer [`POST /v1/messages`](https://sumgenius.ai/docs/rest-api#send-message), which accepts the same body and returns the v1 envelope. **Endpoint** ``` POST https://sumgenius.ai/api/meta/webhook-send.php ``` **curl · free-form text (within 24h)** ```bash curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \ -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "wa_20260505_001", "action": "send_message", "platform": "whatsapp", "to_phone": "+15551234567", "message_text": "Thanks, your refill is ready for pickup." }' ``` ### WhatsApp templates Approved templates can be sent any time (no 24h window required). Templates must already be registered and approved on your WhatsApp Business Account. ChatGenius forwards your fields directly to Meta's Cloud API. Template fields - template_namestringrequired Must use Meta's lowercase letters/numbers/underscore format. - template_languagestring Defaults to `en_US` when omitted. - template_componentsarray Must be a JSON array; passed through to Meta verbatim in the Cloud API `components` structure (see [Meta's template documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)). Common component types: `header`, `body`, `button`; each contains a `parameters` array of typed values. Named vs. positional parameters - Positional placeholders{{1}}, {{2}}, ... Older style, matched by order. - Named placeholders{{customer_name}}, ... Newer style; each parameter must include a `parameter_name` field matching the placeholder name. The format your template was registered with determines the shape at send time. If you mix the two or omit `parameter_name` for a named-parameter template, Meta returns `(#100) Invalid parameter` with "Parameter name is missing or empty." Check your template definition in WhatsApp Manager to see which style it was registered with. Template errors from Meta - (#100) Invalid parameter Usually the parameter shape doesn't match the template (positional vs named, or missing `parameter_name`). - 132001 Template does not exist (check name and language). - 132000 Number of parameters does not match the registered template. - 132012 Parameter format does not match (e.g. wrong type for a placeholder). - 131047 Re-engagement message error (24h window expired and no template used). - 132015 Template paused due to low quality. **Template send · request body** ``` { "idempotency_key": "wa_template_20260505_001", "action": "send_message", "platform": "whatsapp", "to_phone": "+15551234567", "template_name": "order_shipped", "template_language": "en_US", "template_components": [ { "type": "body", "parameters": [ {"type": "text", "text": "12345"}, {"type": "text", "text": "May 6"} ] } ] } ``` **Positional component** ``` { "type": "body", "parameters": [ {"type": "text", "text": "12345"}, {"type": "text", "text": "May 6"} ] } ``` **Named component** ``` { "type": "body", "parameters": [ {"type": "text", "parameter_name": "customer_name", "text": "Jared"}, {"type": "text", "parameter_name": "order_number", "text": "SG4324"}, {"type": "text", "parameter_name": "business_name", "text": "SumGeniusAI"}, {"type": "text", "parameter_name": "order_status", "text": "Shipped"} ] } ```