The history field is the Coexistence chat-history sync field. It is message-path data and can contain prior WhatsApp Business app conversation content. In Dualhook setups, it is routed directly from Meta to your endpoint via Webhook Override.
What history Reports
When a business customer has onboarded a WhatsApp Business app number to Cloud API and agrees to share history, Meta can send prior chat history for up to 180 days before onboarding.
Important constraints:
- group chats are not included,
- media messages usually appear first as
media_placeholder, - separate media-detail webhooks can follow for media sent within roughly 14 days of onboarding,
- a single webhook can contain many threads and many messages.
When It Fires
The field fires after a solution provider requests history sync for a business that was onboarded with a WhatsApp Business app phone number.
There are two outcomes:
| Outcome | Payload |
|---|---|
| Business approved history sharing | One or more history chunks containing thread and message data. |
| Business declined history sharing | A history.errors[] payload, commonly code 2593109. |
How History Sync Is Delivered
History sync is split into phases:
| Phase | Coverage |
|---|---|
0 | onboarding time through day 1 |
1 | day 1 through day 90 |
2 | day 90 through day 180 |
Within a phase, Meta may send multiple chunks. Use chunk_order to order chunks and progress to track overall sync progress. A progress value of 100 means the sync is complete.
Payload Shape
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<CUSTOMER_WABA_ID>",
"changes": [
{
"field": "history",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"history": [
{
"metadata": {
"phase": 0,
"chunk_order": 1,
"progress": 55
},
"threads": [
{
"id": "<WHATSAPP_USER_PHONE_NUMBER>",
"messages": [
{
"from": "<SENDER_PHONE_NUMBER>",
"id": "<WAMID>",
"timestamp": "1739230955",
"type": "text",
"text": {
"body": "Example prior message"
},
"history_context": {
"status": "READ"
}
}
]
}
]
}
]
}
}
]
}
]
}Declined Sharing
If the business declined history sharing, Meta can send an error payload instead of threads.
{
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"history": [
{
"errors": [
{
"code": 2593109,
"title": "History sync is turned off by the business from the WhatsApp Business App"
}
]
}
]
}Live message delivery can still work when history sharing is declined. The error only means pre-onboarding history will not be shared.
Dualhook Handling
Dualhook does not ingest, store, forward, or replay history payloads. This field is direct-routed through Webhook Override, so Meta sends it to your configured endpoint.
During Coexistence onboarding, Dualhook triggers Meta's one-time history sync after Webhook Override is accepted. A successful trigger means Meta accepted the sync request; it does not prove that the business shared history, that chunks were generated, or that your endpoint received every chunk.
If your endpoint misses or drops history chunks, Dualhook has no copy to replay. Fix your webhook handler first, then re-onboard only if you need Meta to attempt a fresh sync and the platform allows it.
Implementation Notes
- Acknowledge quickly and process asynchronously. One webhook can contain thousands of messages.
- Use
phase,chunk_order, andprogressfor ordering and progress tracking. - Treat
media_placeholderas a pointer that may be followed by a separate media-detail webhook. - Make ingestion idempotent by
wamid, phase, and chunk metadata. - If
wa_idfields change during Meta's BSUID transition, handleuser_idand missing phone-number fields as described in the BSUID guide.