WhatsApp Business App History Message Webhook Examples

For the exhaustive schema-derived catalog, see all examples.

What it is

Handle WhatsApp Business App history synchronization events.

Before you begin

Create a public HTTPS endpoint in your application.
Configure a YCloud webhook endpoint for the event types you need.
Store the endpoint signing secret securely.
Make event processing idempotent.

How it works

YCloud sends an HTTP POST request when the event occurs. Verify the signature, durably record the event, return a 2xx response, and process slow work asynchronously. For events created from a Meta history chunk, YCloud copies the chunk’s phase and progress to the top-level event. Message-bearing chunks include one direction-specific message object. If both threads and errors are empty, YCloud sends one progress-only event without whatsappMessage or whatsappInboundMessage. Deliveries are at least once and can arrive out of order. Deduplicate by event id; do not use phase and progress as a unique delivery key.

Request

The scenarios below show requests delivered to your webhook URL. Treat the event id as the delivery identifier and use type to route the payload.

Response

Return a 2xx status after accepting the event.

HTTP/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

Inbound Text message

In this case, your webhook endpoint received an inbound text message:

Contains plain text that the user sent.
Contains the mentioned message information in context.
Other types of messages can refer to whatsappInboundMessage

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeWick"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Inbound messages are those sent from customers to your business phone numbers.
The context (optional) contains the mentioned message information, typically used to reply to a previous message sent by the user or your business.
- context.from is the WhatsApp ID (phone number without the ’+’ prefix) of the user who sent the mentioned message.
- context.id is the original ID of the mentioned message on WhatsApp’s platform, starting with wamid..

Outbound Text message

In this case, your webhook endpoint received an outbound text message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device:

Contains plain text sent before.
Contains the mentioned message information in context.
Other types of messages can refer to WhatsApp Business App Sent Message Sync Webhook Examples

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId" : "US.13491208655302741918",
    "toParentUserId": "US.11815799212886844830",
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Progress-only history chunk

When a Meta history chunk contains neither threads nor errors, the event still reports its synchronization metadata. The event does not contain a message payload.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_progressOnly73",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:02.000Z",
  "phase": 1,
  "progress": 73
}'

Response

HTTP/1.1 200 OK

Explanation

This event intentionally has no WhatsApp message object. Continue tracking progress and acknowledge it like any other webhook delivery.

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Business App History Message Webhook Examples

What it is

Before you begin

How it works

Request

Response

Inbound Text message

Request

Response

Explanation

Outbound Text message

Request

Response

Explanation

Progress-only history chunk

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Inbound Text message

​Request

​Response

​Explanation

​Outbound Text message

​Request

​Response

​Explanation

​Progress-only history chunk

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Inbound Text message

Request

Response

Explanation

Outbound Text message

Request

Response

Explanation

Progress-only history chunk

Request

Response

Explanation