Historical messages

Field	Data type	Required	Description
wabaId	String	Yes	WabaId
sender	String	Yes	sender number
phoneNumberId	String	Yes	sender ID
history	Array	No	The business phone number display name collected when creating the number, or the name submitted when editing an approved display name
--metadata		No
-- --phase	Integer	Yes	Parameter value to monitor stage progress. The value2indicates the current stage has completed. Indicates history recordsstage. The value can be: * 0— Indicates messages from day 0 (merchant onboarding time) to day 1* 1— Indicates messages from day 1 to day 90* 2— Indicates messages from day 90 to day 180
-- --chunk_order	Integer	Yes	The parameter value orders these chunks in sequence, since they may not be delivered in order. Indicateschunknumber, which can be used to sort a series of Webhooks.
-- --progress	Integer	Yes	Parameter value to monitor overall progress. The value100indicates synchronization is complete. Indicates the total percentage of sync progress. The minimum value is0, maximum value is100.
--threads		No
-- --id	String	Yes	The WhatsApp user's phone number.
-- --messages	String	Yes	Message array
-- -- --from	String	Yes	Business customer's phone number or the WhatsApp user's phone number. If this value is the business's phone number, the message object describes a message sent by the business to the WhatsApp user. If this value is the WhatsApp user's phone number, the message object describes a message sent by the WhatsApp user to the business.
-- -- --id	String	Yes	WhatsApp message ID.
-- -- --timestamp	String	Yes	Unix timestamp indicating when the recipient's device received the message. Example: 1738796547
-- -- --type	String	Yes	Message type. Note that this placeholder appears twice in the above syntax because it is used both astypea placeholder for the attribute value and its matching attribute name. Seethe Payload example below, to see a conversation containing various message types. If this value is set tomedia_placeholder, then the message object describes a message containing media assets. In this case, the message content will be ignored. Instead, a separate history Webhook will later be sent describing the message content and media asset ID, but only for messages sent within the two weeks prior to the query. See below for thePayload example.
-- -- --text	Object		An object describing the message content. This value varies depending on the message type and message content. For example, if the business sends animagemessage, this object will not containcaptionproperty. SeeSend message, for Payload examples for each message type.
-- -- -- --body	String
-- -- --history_context	Object	Yes
-- -- -- --status	String	Yes	Indicates the latest delivery status of the message. The value can be: * DELIVERED* ERROR* PENDING* PLAYED* READ* SENT
errors	String	No

The following Webhook examples describe two message conversations: (1) a conversation containing a text message and a video message sent to a WhatsApp user, and the WhatsApp user's reply; (2) a conversation containing a text message sent to another WhatsApp user (thanking the user for placing an order).

Note that the media message content in the first conversation is not described, but instead triggersthe second Webhook, which describes the content of that media message.

{
    "id": "fd201190-50dc-4151-baec-1d16c8a704e1",
    "type": "whatsapp_history_message",
    "eventTime": "2023-10-16T13:04:57.644Z",
    "body": {
        "wabaId": "110129512080569",
        "sender": "108672736726376",
        "phoneNumberId": "123123123123123",
        "history": [
            {
                "metadata": {
                    "phase": 0,
                    "chunk_order": 1,
                    "progress": 55
                },
                "threads": [
                    {
                        "id": "16505551234",
                        "messages": [
                            {
                                "from": "15550783881",
                                "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
                                "timestamp": "1739230955",
                                "type": "text",
                                "text": {
                                    "body": "Here's the info you requested! https://www.meta.com/quest/quest-3/"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            },
                            {
                                "from": "15550783881",
                                "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
                                "timestamp": "1739230970",
                                "type": "media_placeholder",
                                "history_context": {
                                    "status": "PLAYED"
                                }
                            },
                            {
                                "from": "16505551234",
                                "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks!"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            }
                        ]
                    },
                    {
                        "id": "12125557890",
                        "messages": [
                            {
                                "from": "15550783881",
                                "id": "wamid.BIyNDlBOEI5N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGQUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks for your order! As a thank you, use code THANKS30 to get 30% of your next order."
                                },
                                "history_context": {
                                    "status": "DELIVERED"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

The following Webhook example describes the content of the media message.

{
    "id": "fd201190-50dc-4151-baec-1d16c8a704e1",
    "type": "whatsapp_history_message",
    "eventTime": "2023-10-16T13:04:57.644Z",
    "body": {
        "wabaId": "110129512080569",
        "sender": "108672736726376",
        "phoneNumberId": "123123123123123",
        "messages": [
              {
                "from": "16505551234",
                "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
                "timestamp": "1738796547",
                "type": "image",
                "image": {
                  "caption": "Black Prince echeveria",
                  "mime_type": "image/jpeg",
                  "sha256": "3f9d94d399fa61c191bc1d4ca71375a035cd9b9f5b1128e1f0963a415c16b0cc",
                  "id": "24230790383178626",
                  "url":"https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=1808746433445380&source=webhook&ext=1786588846&hash=ATzuMr2uvZF_ilTxLF2sxHhzkfLBbPIRVfXxN2p2lX9MaA"
                }
              }
         ]
    }
}

Chat history sharing has been denied

{
    "id": "fd201190-50dc-4151-baec-1d16c8a704e1",
    "type": "whatsapp_history_message",
    "eventTime": "2023-10-16T13:04:57.644Z",
    "body": {
        "wabaId": "110129512080569",
        "sender": "108672736726376",
        "phoneNumberId": "123123123123123",
        "history": [
            {
                "errors": [
                    {
                        "code": 2593109,
                        "title": "History sync is turned off by the business from the WhatsApp Business App",
                        "message": "History sync is turned off by the business from the WhatsApp Business App",
                        "error_data": {
                            "details": "History sharing is turned off by the business"
                        }
                    }
                ]
            }
        ]
    }
}