Coexistence Webhooks

Here you will find information about history webhooks and message echoes for businesses that have been onboarded to both the WhatsApp Business App and the WhatsApp Cloud API simultaneously.

You will receive the following webhooks related to the onboarded numbers:

• history: Provides details about past messages the business customer has sent or received. Destination: history webhook will be sent to the partner's configured webhook URL in the following minutes after the onboarding succeeds.

• smb_app_state_sync: Describes the business customer's current and new contacts. Destination: smb_app_state_sync webhook will be sent to the partner's configured webhook URL in the following minutes after the onboarding succeeds.

• smb_message_echoes: Describes any new messages the business customer sends with the WhatsApp Business app after onboarding. Destination: smb_message_echoes webhook will be sent to the phone number's webhook URL.

History webhook

The history webhook is triggered when the business approves or declines sharing of their chat history. Below you can find the example structure. Below are the structures for both scenarios:

Chat history sharing approved

{
  "id": "<EVENT_ID>",
  "event": "history",
  "data": {
    "id": "<WABA_ID>",
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
      "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
    },
    "history": [
      {
        "metadata": {
          "phase": "<PHASE>", // Add appropriate phase value
          "chunk_order": <CHUNK_ORDER>,
          "progress": "<PROGRESS_VALUE>" // Add appropriate progress value
        },
        "threads": [
          {
            "id": "<WHATSAPP_USER_PHONE_NUMBER>",
            "messages": [
              {
                "from": "<BUSINESS_OR_WHATSAPP_USER_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>", // Only included if SMB message echo
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<DEVICE_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  "<MESSAGE_CONTENTS>" // Fill in message contents specifics
                },
                "history_context": {
                  "status": "<MESSAGE_STATUS>"
                }
              }
              // Additional message objects in thread would follow, if any
            ]
          }
          // Additional chat history thread objects would follow, if any
        ]
      }
    ]
  }
}

Chat history sharing declined

For more examples of webhook history events, such as media message assets, please refer to the official Meta documentation here.

SMB App State sync webhook

The smb_app_state_sync webhook provides updates about the business customer's contacts, including future additions or changes. Below you can find the example structure.

{
      "id": "DM3",
      "event": "smb_app_state_sync",
      "data": {
        "id": "<WABA_ID>",
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
          "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
        },
        "state_sync": [{
          "type": "contact",
          "contact": {
            "full_name": "<CONTACT_FULL_NAME>",
            "first_name": "<CONTACT_FIRST_NAME>",
            "phone_number": "<CONTACT_PHONE_NUMBER>"
          },
          "action": "<ACTION>",
          "metadata": {
            "timestamp": "<WEBHOOK_TIMESTAMP>"
          }
        },
        * Additional contacts would follow, if any */
      ]
    }
  }

SMB Message Echoes webhook

The smb_message_echoes webhook captures new messages sent by the business customer using the WhatsApp Business app after onboarding. This webhook ensures that partners can track and process these messages in real time. This webhook will be sent to the phone number level webhook. Below you can find the example structure.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "message_echoes": [
              {
                "from": "<BUSINESS_PHONE_NUMBER>",
                "to": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TIMESTAMP>",
                "type": "<MESSAGE_TYPE>",
                "<MESSAGE_TYPE>": {
                  <MESSAGE_CONTENTS>
                }
              }
            ]
          },
          "field": "smb_message_echoes"
        }
      ]
    }
  ]
}