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.

All webhooks will be automatically delivered to the Partner Webhook URL provided during the partner onboarding process.

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 example 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

{
      "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": [{
          "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"
            }
          }]
        }]
      }
    }

SMB App State sync webhook

The smb_app_state_sync webhook provides updates about the business customer's contacts, including future additions or changes.

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.

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"
        }
      ]
    }
  ]
}