# history webhook reference | Developer Documentation

<div id="bkmrk-history-webhook-refe">## history webhook reference

<div><span>Updated: Dec 12, 2025</span></div><div>This reference describes trigger events and payload contents for the WhatsApp Business Account `history` webhook.</div><div>The **history** webhook is used to synchronize the [WhatsApp Business app chat history](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) of a business customer onboarded by a solution provider.</div><div id="bkmrk-triggers"><div id="bkmrk-triggers-1"><div>### Triggers

</div></div></div><span>a solution provider [synchronize the WhatsApp Business app chat history](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) of a business customer who they have onboarded with a WhatsApp Business app phone number, and who has agreed to share their chat history</span><span>a solution provider [synchronize the WhatsApp Business app chat history](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation) of a business customer who they have onboarded with a WhatsApp Business app phone number, but the customer has declined to share their chat history</span><div id="bkmrk-chat-history-sharing"><div id="bkmrk-chat-history-sharing-1"><div>### Chat history sharing approved

</div></div></div><div id="bkmrk-chat-history-content"><div id="bkmrk-chat-history-content-1"><div>#### Chat history contents

</div></div></div><div>If the business customer has already approved chat history sharing when the solution provider requests the business's chat history, a series of history webhooks will be triggered, describing all messages sent or received within 180 days of the time when the business was onboarded onto Cloud API.</div><span>Messages that are part of a group chat will not be included.</span><span>Media messages will not include media asset IDs. Instead, additional history webhooks containing media message asset IDs will be sent separately, but only for media messages sent within 14 days of onboarding.</span><div>Note that for efficiency purposes, a single webhook could potentially describe thousands of messages, so we recommend that you capture its contents first, then process the contents asynchronously.</div><div id="bkmrk-phases-and-chunks"><div id="bkmrk-phases-and-chunks-1"><div>#### Phases and chunks

</div></div></div><div>Webhooks are divided into three history phases, where day 0 indicates the time when the business was onboarded onto Cloud API:</div><span>phase 0: day 0 through day 1</span><span>phase 1: day 1 through day 90</span><span>phase 2: day 90 through day 180</span><div>For each phase, chat history webhooks may be sent in separate chunks, depending on the total number of messages that comprise the thread.</div><span>You can use the `chunk_order` parameter value to arrange these chunks in their sequential order, as they may not be delivered sequentially.</span><span>You can use the `phase` parameter value to monitor phase progress. A value of `2` indicates that the current phase is complete.</span><span>You can use the `progress` parameter value to monitor the overall progress. A value of `100` indicates that synchronization is complete.</span><div>If there is no chat history available for a given phase, no corresponding webhooks will be sent.</div><div id="bkmrk-parameters"><div id="bkmrk-parameters-1"><div>#### Parameters

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th><th><span>Example value </span></th></tr></thead><tbody><tr><td><div><div>`<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>The business customer's phone number, or the WhatsApp user's phone number.</div><div>If the value is the business's phone number, the message object describes a message sent by the business to a WhatsApp user.</div><div>If the value is the WhatsApp user's phone number, the message object describes a message sent by the WhatsApp user to the business.</div></div></td><td><div><div>`15550783881`</div></div></td></tr><tr><td><div><div>`<CHUNK_ORDER>`</div><div>*Integer*</div></div></td><td><div><div>Indicates [chunk](#bkmrk-phases-and-chunks-1) number, which you can use to order sets of webhooks sequentially.</div></div></td><td><div><div>`1`</div></div></td></tr><tr><td><div><div>`<CUSTOMER_WABA_ID>`</div><div>*String*</div></div></td><td><div><div>The business customer's WhatsApp Business Account ID.</div></div></td><td><div><div>`102290129340398`</div></div></td></tr><tr><td><div><div>`<CUSTOMER_DISPLAY_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>The business customer's business phone number.</div></div></td><td><div><div>`15550783881`</div></div></td></tr><tr><td><div><div>`<CUSTOMER_PHONE_NUMBER_ID>`</div><div>*String*</div></div></td><td><div><div>The business customer's business phone number ID.</div></div></td><td><div><div>`106540352242922`</div></div></td></tr><tr><td><div><div>`<DEVICE_TIMESTAMP>`</div><div>*String*</div></div></td><td><div><div>Unix timestamp indicating when the message was received by the recipient's device.</div></div></td><td><div><div>`1738796547`</div></div></td></tr><tr><td><div><div>`<MESSAGE_CONTENTS>`</div><div>*Object*</div></div></td><td><div><div>An object describing the message's contents. This value will vary based on the message type, as well as the contents message.</div><div>For example, if a business sends an `image` message without a caption, the object would not include the `caption` property.</div><div>See [Sending messages](/books/meta-whatsapp/page/sending-messages-developer-documentation) for examples of payloads for each message type.</div></div></td><td></td></tr><tr><td><div><div>`<MESSAGE_STATUS>`</div><div>*String*</div></div></td><td><div><div>Indicates the message's most recent delivery stats. Values can be:</div><span>`DELIVERED`</span><span>`ERROR`</span><span>`PENDING`</span><span>`PLAYED`</span><span>`READ`</span><span>`SENT`</span></div></td><td><div><div>`READ`</div></div></td></tr><tr><td><div><div>`<MESSAGE_TYPE>`</div><div>*String*</div></div></td><td><div><div>[Message type](/books/meta-whatsapp/page/messages-webhook-reference-developer-documentation). Note that this placeholder appears twice in the syntax above, as it serves as a placeholder for the `type` property's value and its matching property name. See the [example payload below](#bkmrk-examples-1) for a thread with various message types.</div><div>If this value is set to `media_placeholder`, the message object describes a message that contained a media asset. In this case, the message contents will be omitted. Instead, a separate history webhook will follow, describing the content of the message and the media asset ID, but only if the message was sent within the last two weeks of your query. See the [example payloads below](#bkmrk-examples-1) describing a media message's contents.</div></div></td><td><div><div>`text`</div></div></td></tr><tr><td><div><div>`<PHASE>`</div><div>*Integer*</div></div></td><td><div><div>Indicates history [phase](#bkmrk-phases-and-chunks-1). Values can be:</div><span>`0` - indicates messages are from day 0 (business onboarding time) through day 1</span><span>`1` - indicates messages are from day 1 through day 90</span><span>`2` - indicates messages are from day 90 through day 180</span></div></td><td><div><div>`1`</div></div></td></tr><tr><td><div><div>`<PROGRESS>`*Integer*</div></div></td><td><div><div>Indicates percentage total of synchronization progress.</div><div>Minimum `0`, maximum `100`.</div></div></td><td><div><div>`55`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_MESSAGE_ID>`</div><div>*String*</div></div></td><td><div><div>WhatsApp message ID.</div></div></td><td><div><div>`wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_USER_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>The WhatsApp user's phone number.</div><div>The `to` property is only included if the message object represents an [SMB message echo](/books/meta-whatsapp/page/onboarding-whatsapp-business-app-users-aka-coexistence-developer-documentation).</div></div></td><td><div><div>`16505551234`</div></div></td></tr></tbody></table>

</div><div id="bkmrk-chat-history-sharing-3"><div id="bkmrk-chat-history-sharing-4"><div>### Chat history sharing declined

</div></div></div><div id="bkmrk-parameters-3"><div id="bkmrk-parameters-4"><div>#### Parameters

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th><th><span>Example value </span></th></tr></thead><tbody><tr><td><div><div>`<CUSTOMER_DISPLAY_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>The business customer's business phone number.</div></div></td><td><div><div>`15550783881`</div></div></td></tr><tr><td><div><div>`<CUSTOMER_PHONE_NUMBER_ID>`</div><div>*String*</div></div></td><td><div><div>The business customer's business phone number ID.</div></div></td><td><div><div>`106540352242922`</div></div></td></tr></tbody></table>

</div></div>