# Coexistence Webhooks

{% hint style="info" %}
All webhooks will be automatically delivered to the Partner Webhook URL provided during the partner onboarding process.
{% endhint %}

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. The webhook will also be sent to the phone number's webhook URL after the URL is set.
* `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. 

<details>

<summary>Chat history sharing approved</summary>

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

</details>

<details>

<summary>Chat history sharing declined</summary>

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

</details>

{% hint style="warning" %}
For more examples of webhook history events, such as media message assets, please refer to the official Meta documentation [here](https://developers.facebook.com/docs/whatsapp/embedded-signup/custom-flows/onboarding-business-app-users/#history).
{% endhint %}

### SMB App State sync webhook

The `smb_app_state_sync` webhook provides updates about the business customer's contacts, including future additions or changes.&#x20;

<details>

<summary>Example structure</summary>

```json
{
      "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 */
      ]
    }
  }
```

</details>

### 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.**&#x20;

<details>

<summary>Example structure</summary>

```json
{
  "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"
        }
      ]
    }
  ]
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/partner/onboarding/whatsapp-coexistence/coexistence-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.