messages webhook reference | Developer Documentation

messages webhook reference
Updated: Oct 22, 2025
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 a business:
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:
Note that 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.
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.