Product Guide

Coexistence Events - Webhooks

Embedded Signup lets businesses onboard using their existing WhatsApp Business account and phone number, enabling them to send messages at scale via your app while still maintaining one-to-one messaging and synced chat history in the WhatsApp Business app.

Synchronizing WhatsApp Business App Data

Use this Sync UI to trigger the history and smb_app_state_sync

Webhook event for history

Use the Sync UI to start message history sync. If the business opts in, history webhooks will be triggered for messages within the selected time range.

{
  "entry": [
    {
      "changes": [
        {
          "field": "history",
          "value": {
            "history": [
              {
                "metadata": {
                  "chunk_order": 1,
                  "phase": 0,
                  "progress": 100
                },
                "threads": [
                  {
                    "id": "917506080480",
                    "messages": [
                      {
                        "from": "918588096070",
                        "history_context": {
                          "from_me": true,
                          "status": "read"
                        },
                        "id": "wamid.HBgMOTE4NTg4MDk2MDcwFQIAERgSQ0FFNjA5RjM4MDdCRDRGMjdFAA==",
                        "text": {
                          "body": "Hi man"
                        },
                        "timestamp": "1775627842",
                        "type": "text"
                      },
                      {
                        "from": "917506080480",
                        "history_context": {
                          "status": "pending"
                        },
                        "id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0ExNDdBQ0ZEODQ3NTQ4MENDMzkA",
                        "text": {
                          "body": "Hi dude"
                        },
                        "timestamp": "1775627825",
                        "type": "text"
                      },
                      {
                        "from": "918588096070",
                        "history_context": {
                          "from_me": true,
                          "status": "read"
                        },
                        "id": "wamid.HBgMOTE4NTg4MDk2MDcwFQIAERgSQThFQzU5NDNFODlFM0IxMjFDAA==",
                        "text": {
                          "body": "Hi Avadoot"
                        },
                        "timestamp": "1775627478",
                        "type": "text"
                      },
                      {
                        "from": "917506080480",
                        "history_context": {
                          "status": "pending"
                        },
                        "id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0EwODFGMjZCNTA2N0VBQTI3OEYA",
                        "text": {
                          "body": "Heyoo"
                        },
                        "timestamp": "1775627414",
                        "type": "text"
                      },
                      {
                        "from": "918588096070",
                        "history_context": {
                          "from_me": true,
                          "status": "delivered"
                        },
                        "id": "wamid.HBgMOTE4NTg4MDk2MDcwFQIAERgUMkFEQkFCMEFCNEVGMDUyMjk0OUYA",
                        "text": {
                          "body": "Hello"
                        },
                        "timestamp": "1775627221",
                        "type": "text"
                      },
                      {
                        "from": "918588096070",
                        "history_context": {
                          "from_me": true,
                          "status": "delivered"
                        },
                        "id": "wamid.HBgMOTE4NTg4MDk2MDcwFQIAERgUMkFFN0RGRTY0RUNCNEVCNTIxNEIA",
                        "text": {
                          "body": "Hey"
                        },
                        "timestamp": "1775626356",
                        "type": "text"
                      }
                    ]
                  },
                  {
                    "id": "447710173736",
                    "messages": [
                      {
                        "errors": [
                          {
                            "code": 131051,
                            "error_data": {
                              "details": "Unsupported message received"
                            },
                            "message": "Message type unknown",
                            "title": "Message type unknown"
                          }
                        ],
                        "from": "447710173736",
                        "history_context": {
                          "status": "pending"
                        },
                        "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSMDkxQTIyRjhFMDFFOTFCOTdEAA==",
                        "timestamp": "1775628342",
                        "type": "errors"
                      },
                      {
                        "errors": [
                          {
                            "code": 131051,
                            "error_data": {
                              "details": "Unsupported message received"
                            },
                            "message": "Message type unknown",
                            "title": "Message type unknown"
                          }
                        ],
                        "from": "447710173736",
                        "history_context": {
                          "status": "pending"
                        },
                        "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSQUE3RTJFNEFEOEJBNDQ2NUQzAA==",
                        "timestamp": "1775625835",
                        "type": "errors"
                      }
                    ]
                  }
                ]
              }
            ],
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918588096070",
              "phone_number_id": "1005385572668707"
            }
          }
        }
      ],
      "id": "1619622649281109"
    }
  ],
  "gs_app_id": "5d873e48-0b81-4e23-801a-13c6db86cf17",
  "object": "whatsapp_business_account"
}
PlaceholderDescriptionExample Value
WABA_ID
String		The business customer’s WhatsApp Business Account ID.102290129340398
BUSINESS_PHONE_NUMBER
String		The business customer’s business phone number.15550783881
BUSINESS_PHONE_NUMBER_ID
String		The business customer’s business phone number ID.106540352242922
PHASE
Integer		Indicates history phase. Values can be: 0 — indicates messages are from day 0 (business onboarding time) through day 1 1 — indicates messages are from day 1 through day 90 2 — indicates messages are from day 90 through day 1801
CHUNK_ORDER
Integer		Integer Indicates chunk number, which you can use to order sets of webhooks sequentially.1
PROGRESS
Integer		Indicates percentage total of synchronization progress. Minimum 0, maximum 100.55
WHATSAPP_USER_PHONE_NUMBER
String		The WhatsApp user’s phone number.16505551234
BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER
String		The business customer’s phone number, or the WhatsApp user’s phone number. If the value is the business’s phone number, the message object describes a message sent by the business to a WhatsApp user. If the value is the WhatsApp user’s phone number, the message object describes a message sent by the WhatsApp user to the business.15550783881
WHATSAPP_USER_PHONE_NUMBER
String		The WhatsApp user’s phone number. The to property is only included if the message object represents an SMB message echo.16505551234
WHATSAPP_MESSAGE_ID
String		WhatsApp message ID.
DEVICE_TIMESTAMP
String		Unix timestamp indicating when the message was received by the recipient’s device.1738796547
MESSAGE_TYPE
String		Message type. 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 for a thread with various message types. 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 payload below describing a media message’s contents.text
MESSAGE_CONTENTS
Object		An object describing the message’s contents. This value will vary based on the message type, as well as the contents message. For example, if a business sends an image message without a caption, the object would not include the caption property. See Sending messages for examples of payloads for each message type.
{"body":"Here's the info you requested! https://www.meta.com/quest/quest-3/"}
MESSAGE_STATUS
String		Indicates the message’s most recent delivery stats. Values can be: DELIVERED ERROR PENDING PLAYED READ SENTREAD

Webhook event for smb_app_state_sync

Describes WhatsApp contacts in a business account. Triggered when contacts are synced or when a customer adds, edits, or removes contacts.

Use this Sync UI to start contact sync (Please note: It's a one-time operation for History and Contact Sync and the same UI. If you have already triggered while initiating history sync, there is no need to retrigger it). Successful requests trigger webhooks for existing and future contact changes. This can be done only once unless the customer offboards and re-onboards.

{
    "entry": [
        {
            "changes": [
                {
                    "field": "smb_app_state_sync",
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "918750963486",
                            "phone_number_id": "950443251490365"
                        },
                        "state_sync": [
                            {
                                "action": "remove",
                                "contact": {
                                    "phone_number": "917715078842"
                                },
                                "metadata": {
                                    "timestamp": "0"
                                },
                                "type": "contact"
                            }
                        ]
                    }
                }
            ],
            "id": "1197332449152321"
        }
    ],
    "gs_app_id": "6d300e4b-426e-4212-8e02-5df480593a5f",
    "object": "whatsapp_business_account"
}
PlaceholderDescriptionExample Value
WABA_ID
String		The business customer’s WhatsApp Business Account ID.102290129340398
BUSINESS_PHONE_NUMBER
String		The business customer’s business phone number.15550783881
BUSINESS_PHONE_NUMBER_ID
String		The business customer’s business phone number ID.106540352242922
CONTACT_FULL_NAME
Integer		The contact’s full name, as it appears in the business customer’s WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book.Pablo Morales
CONTACT_FIRST_NAME
String		The contact’s first name, as it appears in the business customer’s WhatsApp Business app phone address book. Not included when the business customer removes a contact from their WhatsApp Business app phone address book.Pablo
CONTACT_PHONE_NUMBER
String		The contact’s WhatsApp phone number.16505551234
ACTION
String		Indicates if the business customer added, edited, or deleted a contact from their WhatsApp Business app phone address book. Values can be: add — the business added or edited a contact remove — the business removed a contactadd
CONTACT_CHANGE_TIMESTAMP
String		Unix timestamp indicated when the contact was added, edited, or removed.1738346006

Webhook event for smb_message_echoes

Describes a message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device.

{
    "entry": [
        {
            "changes": [
                {
                    "field": "smb_message_echoes",
                    "value": {
                        "message_echoes": [
                            {
                                "from": "918750963486",
                                "id": "wamid.HBgMOTE4NDQ2MDAwOTA5FQIAERgUMkFERTUzRkEzRkI0REE0RkEyNkQA",
                                "text": {
                                    "body": "Hey"
                                },
                                "timestamp": "1773387740",
                                "to": "918446000909",
                                "type": "text"
                            }
                        ],
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "918750963486",
                            "phone_number_id": "950443251490365"
                        }
                    }
                }
            ],
            "id": "1197332449152321"
        }
    ],
    "gs_app_id": "6d300e4b-426e-4212-8e02-5df480593a5f",
    "object": "whatsapp_business_account"
}

PlaceholderDescriptionExample Value
WABA_ID
String		The business customer’s WhatsApp Business Account ID.102290129340398
BUSINESS_PHONE_NUMBER
String		The business customer’s business phone number.15550783881
BUSINESS_PHONE_NUMBER_ID
String		The business customer’s business phone number ID.106540352242922
WHATSAPP_USER_PHONE_NUMBER StringThe WhatsApp user’s phone number.16505551234
WHATSAPP_MESSAGE_ID
String		WhatsApp message ID.
WEBHOOK_TIMESTAMP
String		Unix timestamp indicated when the webhook was triggered.1738796547
MESSAGE_TYPE
String		Message type. 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.text
MESSAGE_CONTENTS
Object		An object describing the message’s contents. This value will vary based on the message type, as well as the contents of the message. For example, if a business sends an image message without a caption, the object would not include the caption property. See Sending messages for examples of payloads for each message type.
{"body":"Here's the info you requested! https://www.meta.com/quest/quest-3/"}


Edit Webhook Event upon Editing Media Message with Caption

{
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "contacts": [
              {
                "wa_id": "917506080480"
              }
            ],
            "messages": [
              {
                "edit": {
                  "message": {
                    "image": {
                      "caption": "Heylooo givig",
                      "id": "903470842067649",
                      "mime_type": "image/jpeg",
                      "sha256": "8V/pEU8aOxbDSZpEYkIE6s7Pr7yJvlZ6tz4PW39Zccs=",
                      "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=903470842067649&source=webhook&ext=1769753821&hash=ARlbBG8TjKXO8ZCHMiykC6rKJ0f1LoKP2g6ul7_6uabn3A"
                    },
                    "type": "image"
                  },
                  "original_message_id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0E0ODM3QUM2Nzc0ODI5ODBDMjkA"
                },
                "from": "917506080480",
                "id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0FCMTZCNkE5RUUxN0MwQTg3MEUA",
                "timestamp": "1769753520",
                "type": "edit"
              }
            ],
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918750963486",
              "phone_number_id": "950443251490365"
            }
          }
        }
      ],
      "id": "1197332449152321"
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

Edit Webhook Even upon Editing Text Message

{
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "contacts": [
              {
                "profile": {
                  "name": "Avadhoot Yadav"
                },
                "wa_id": "917506080480"
              }
            ],
            "messages": [
              {
                "edit": {
                  "message": {
                    "text": {
                      "body": "Hey WA user"
                    },
                    "type": "text"
                  },
                  "original_message_id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0E5M0EzMEYwNzc1Qzg0MjU1MTEA"
                },
                "from": "917506080480",
                "id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0EzQzM1RTA2QkU1QTQxODA4NjkA",
                "timestamp": "1769753418",
                "type": "edit"
              }
            ],
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918750963486",
              "phone_number_id": "950443251490365"
            }
          }
        }
      ],
      "id": "1197332449152321"
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

Revoke Webhook Event upon Deleting a Message

{
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "contacts": [
              {
                "profile": {
                  "name": "Avadhoot Yadav"
                },
                "wa_id": "917506080480"
              }
            ],
            "messages": [
              {
                "from": "917506080480",
                "id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0E4MTkzMDBBQTVEMjJENzkyRUIA",
                "revoke": {
                  "original_message_id": "wamid.HBgMOTE3NTA2MDgwNDgwFQIAEhgUM0FGMTg2MENGRDI1RDQzRTdEODcA"
                },
                "timestamp": "1769753870",
                "type": "revoke"
              }
            ],
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "918750963486",
              "phone_number_id": "950443251490365"
            }
          }
        }
      ],
      "id": "1197332449152321"
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}


Account Level Events

WhatsApp Business Account Update — Primary Inactivity Event

Overview

This webhook payload notifies about a partner removal event from a WhatsApp Business Account. It's triggered when Facebook/Meta disconnects a WhatsApp Business Account due to specific reasons, such as primary inactivity.

Webhook Payload Structure

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1739212624,
      "changes": [
        {
          "value": {
              "phone_number": "15550783881",
              "event": "PARTNER_REMOVED",
              "disconnection_info": {
                "reason": "PRIMARY_INACTIVITY",
                "initiated_by": "SYSTEM"
              }
           },
          "field": "account_update"
        }
      ]
    }
  ]
Field PathTypeDescriptionExample Value
objectStringIndicates the object type"whatsapp_business_account"
entry[0].idStringThe WhatsApp Business Account ID"102290129340398"
entry[0].timeIntegerUnix timestamp when the event occurred1739212624
entry[0].changes[0].fieldStringType of field that changed"account_update"
entry[0].changes[0].value.phone_numberStringThe phone number associated with the WhatsApp Business Account"15550783881"
entry[0].changes[0].value.eventStringType of event"PARTNER_REMOVED"
entry[0].changes[0].value.disconnection_info.reasonStringReason for disconnection"PRIMARY_INACTIVITY"
entry[0].changes[0].value.disconnection_info.initiated_byStringWho initiated the disconnection"SYSTEM"

WhatsApp Business Account Update - Partner App Uninstalled Event

Overview

Your business customers can use the WhatsApp Business app to disconnect from Cloud API by navigating to Settings > Account > Business Platform and clicking the Disconnect Account button. When a business customer disconnects from Cloud API, an account_update webhook with a PARTNER_APP_UNINSTALLED event is triggered.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_APP_UNINSTALLED",
            "waba_info": {
              "owner_business_id": "1903704936437045",
              "partner_app_id": "978415460924688",
              "waba_id": "1197332449152321"
            }
          }
        }
      ],
      "id": "1148530713280127",
      "time": 1769764486
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

WhatsApp Business Account Update — Account Disconnected Event

Overview

Triggered when your client's account is disconnected due to enforcement action, or because your client explicitly deleted their WhatsApp account.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_REMOVED",
            "waba_info": {
              "owner_business_id": "2329417887457253",
              "waba_id": "980198427658004"
            },
            "disconnection_info": {
              "reason": "ACCOUNT_DISCONNECTED",
              "initiated_by": "USER"
            }
          }
        }
      ],
      "id": "2949482758682047",
      "time": 1748477359
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

WhatsApp Business Account Update — Business Downgrade Event

Overview

Triggered when your client registers their business phone number with the consumer WhatsApp app. Registering on the consumer app breaks the coexistence pairing, so the Cloud API connection is removed.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_REMOVED",
            "waba_info": {
              "owner_business_id": "2329417887457253",
              "waba_id": "980198427658004"
            },
            "disconnection_info": {
              "reason": "BUSINESS_DOWNGRADE",
              "initiated_by": "USER"
            }
          }
        }
      ],
      "id": "2949482758682047",
      "time": 1748477359
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

WhatsApp Business Account Update — Change Number Event

Overview

Triggered when your client changes their phone number. The coexistence link is bound to the original number, so changing it disconnects the Cloud API connection.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_REMOVED",
            "waba_info": {
              "owner_business_id": "2329417887457253",
              "waba_id": "980198427658004"
            },
            "disconnection_info": {
              "reason": "CHANGE_NUMBER",
              "initiated_by": "USER"
            }
          }
        }
      ],
      "id": "2949482758682047",
      "time": 1748477359
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

WhatsApp Business Account Update — Companion Inactivity Event

Overview

Triggered when the companion device has been inactive for approximately 30 days. No user action is involved — Meta drops the connection after the inactivity window elapses.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_REMOVED",
            "waba_info": {
              "owner_business_id": "2329417887457253",
              "waba_id": "980198427658004"
            },
            "disconnection_info": {
              "reason": "COMPANION_INACTIVITY",
              "initiated_by": "SYSTEM"
            }
          }
        }
      ],
      "id": "2949482758682047",
      "time": 1748477359
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}

WhatsApp Business Account Update — User Re-Registered Event

Overview

Triggered when your client re-registers on a new device. Re-registration invalidates the existing coexistence pairing, disconnecting Cloud API.

Webhook Payload Structure

{
  "entry": [
    {
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "PARTNER_REMOVED",
            "waba_info": {
              "owner_business_id": "2329417887457253",
              "waba_id": "980198427658004"
            },
            "disconnection_info": {
              "reason": "USER_RE_REGISTERED",
              "initiated_by": "USER"
            }
          }
        }
      ],
      "id": "2949482758682047",
      "time": 1748477359
    }
  ],
  "gs_app_id": "20e0cd5c-0476-4947-9003-532553be24c8",
  "object": "whatsapp_business_account"
}


For more Coex WhatsApp account level events please check out meta documentation here.

Updated 1 day ago

Did this page help you?