# messages webhook reference



The **messages** webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user.


## Payload structures

### Incoming messages

Messages webhooks describing a message sent by a WhatsApp user — either directly, via an ad, or via a UI component in a previously received message — all have the same common structure. You can easily identify these webhooks because they include a `messages` array. For example, this webhook describes a text message sent to a business:

```json
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson"
                },
                "wa_id": "16505551234"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
                "timestamp": "1749416383",
                "type": "text",
                "text": {
                  "body": "Does it come in another color?"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
```

Objects in the `messages` array can vary greatly based on message type (indicated by the object's `type` property). For this reason, each incoming message type has a dedicated reference, linked in the menu on the left.

### Outgoing messages

Messages webhooks describing a message sent by a business to a WhatsApp user have a different structure. You can easily identify these because they include a `statuses` array. For example, this webhook describes a message that has been delivered to a WhatsApp user's device:

```json
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3MTE5MjVBOTE3MDk5QUVFM0YA",
                "status": "delivered",
                "timestamp": "1750263773",
                "recipient_id": "16505551234",
                "conversation": {
                  "id": "6ceb9d929c9bdc4f90e967a32f8639b4",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}
```

These webhooks don't describe the contents of the outgoing message itself, only its status, and each outgoing message can have up to three separate webhooks (one for a status of sent, one for delivered, and one for read).

Status webhooks also have a [dedicated reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status).

## Errors

Errors in messages webhooks can be surfaced in three places:

- System-, app-, and account-level errors appear as a `value` object property (`entry.changes.value.errors`). See the [errors](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/errors) reference.
- Incoming message errors appear in the `messages` array (`entry.changes.value.messages.errors`). These webhooks have `type` set to `unsupported`. See the [unsupported](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/unsupported) reference.
- Outgoing message errors appear in the `statuses` array (`entry.changes.value.statuses.errors`). See the [status](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status) reference.


---

Full documentation index for this product: https://developers.facebook.com/documentation/business-messaging/whatsapp/llms.txt