> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Business App History Message Webhook Examples
> Handle WhatsApp Business App history synchronization events.
For the exhaustive schema-derived catalog, see [all examples](/en/api-reference/guides/examples/webhook-examples/webhook-payload-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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
For endpoint setup, signature validation, and retry behavior, see [Configure webhooks](/en/api-reference/guides/api-fundamentals/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](/en/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)
### Request
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/en/api-reference/guides/examples/webhook-examples/whatsapp-business-app-sent-message-sync-webhook-examples)
### Request
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.