WhatsApp Business Platform

messages webhook reference

Updated: Nov 4, 2026
Copy for LLM
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:
{
  "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",
                "user_id": "US.13491208655302741918"
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "from_user_id": "US.13491208655302741918",
                "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:
{
  "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",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI3MTE5MjVBOTE3MDk5QUVFM0YA",
                "status": "delivered",
                "timestamp": "1750263773",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "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.

User identifiers

Incoming user messages and individual-message status webhooks (sent, delivered, and read) identify the WhatsApp user by their business-scoped user ID (BSUID). The user’s phone number is omitted when the user has adopted a username and their phone number is unavailable, so build your integration to identify users by BSUID. An integration that relies only on phone number fields will not be able to process messages from these users.

Incoming messages

FieldUser has a usernameUser does not have a username
contacts.user_id, messages.from_user_id
Included
Included
contacts.wa_id, messages.from
Included if the phone number is available
Always included
contacts.parent_user_id, messages.from_parent_user_id
Included if parent BSUIDs are enabled
Included if parent BSUIDs are enabled
contacts.profile.username
Always included
Not included

Outgoing message statuses

These fields apply to sent, delivered, and read status webhooks. Failed status webhooks omit the contacts array. If the original message was sent to a phone number, statuses.recipient_user_id is also omitted. Use statuses.id to correlate the failure with the original send request. See the status reference.
FieldSent to phone numberSent to BSUID
contacts.user_id, statuses.recipient_user_id
Included
Included
contacts.wa_id, statuses.recipient_id
Always included
Included if the phone number is available
contacts.parent_user_id, statuses.recipient_parent_user_id
Included if parent BSUIDs are enabled
Included if parent BSUIDs are enabled
contacts.profile.username
Included in delivered/read if the user has a username
Included in delivered/read if the user has a username
To send a message to a user identified only by BSUID, set the recipient field to their BSUID. See Business-scoped user IDs.

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 reference.
  • Incoming message errors appear in the messages array (entry.changes.value.messages.errors). These webhooks have type set to unsupported. See the unsupported reference.
  • Outgoing message errors appear in the statuses array (entry.changes.value.statuses.errors). See the status reference.