WhatsApp Cloud API

Status messages webhook reference

This reference describes trigger events and payload contents for WhatsApp Business Account status messages webhook.

Triggers

  • Your message is sent to a WhatsApp user.
  • Your message is delivered to a WhatsApp user's device.
  • Your message is displayed (i.e. "read") in the WhatsApp client on a WhatsApp user's device.
  • Your message is unable to be sent to a WhatsApp user.
  • Your message is unable to be delivered to a WhatsApp user's device.

A status is considered read only if it has been delivered. In some cases, like when a user receives a message while in the chat screen, the message is both delivered and read at the same time. In these cases, the "delivered" webhook is not sent because it's implied that the message was delivered since it was read. This behavior is due to internal optimization.

Syntax

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "statuses": [
              {
                "id": "<WHATSAPP_MESSAGE_ID>",
                "status": "<STATUS>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "recipient_id": "<WHATSAPP_USER_ID>",
                "recipient_identity_key_hash": "<IDENTITY_KEY_HASH>", <!-- only included if identity change check enabled -->
                "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA>", <!-- only included if message sent with biz_opaque_callback_data -->

                <!-- (1) only included with sent status, and one of either delivered or read status
                     (2) starting July 1, 2025, for webhooks v24.0 and higher,
                         conversation object omitted entirely unless webhook
                         is for a free entry point conversation -->
                "conversation": {
                  "id": "<CONVERSATION_ID>",
                  "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",
                  "origin": {
                    "type": "<CONVERSATION_CATEGORY>"
                  }
                },
                
                <!-- only included with sent status, and one of either delivered or read status -->
                "pricing": {
                  "billable": <IS_BILLABLE?>,
                  "pricing_model": "<PRICING_MODEL>",
                  "type": "<PRICING_TYPE>", <!-- available starting July 1, 2025 -->
                  "category": "<PRICING_CATEGORY>"
                },
                
                <!-- only included if failure to send or deliver message -->
                "errors": [
                  {
                    "code": <ERROR_CODE>,
                    "title": "<ERROR_TITLE>",
                    "message": "<ERROR_MESSAGE>",
                    "error_data": {
                      "details": "<ERROR_DETAILS>"
                    },
                    "href": "<ERROR_CODES_URL>"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Parameters

PlaceholderDescriptionExample value

<BUSINESS_DISPLAY_PHONE_NUMBER>

String

Business display phone number.

15550783881

<BUSINESS_OPAQUE_DATA>

String

String assigned by the business to the biz_opaque_callback_data property in the send message request.

Only included if the business set a biz_opaque_callback_data value when sending the message.

1744434060

<BUSINESS_PHONE_NUMBER_ID>

String

Business phone number ID.

106540352242922

<CONVERSATION_CATEGORY>

String

Conversation category. Values can be:

authentication — Indicates an authentication conversation.

authentication_international — Indicates an authentication-international conversation.

marketing — Indicates a marketing conversation.

marketing_lite — Indicates a Marketing Messages Lite API conversation.

referral_conversion — Indicates a free entry point conversation.

service — Indicates a service conversation.

utility — Indicates a utility conversation.

service

<CONVERSATION_EXPIRATION_TIMESTAMP>

String

Unix timestamp indicating when the conversation will expire.

The expiration_timestamp property is only included for sent status.

1744434060

<CONVERSATION_ID>

String

Version 24.0 and higher:

The conversation object will be omitted entirely, unless the webhook is for a message sent within an open free entry point window, in which case the value will be unique per window.

Version 23.0 and lower:

Value will now be set to a unique ID per-message, unless the webhook is for a message sent with an open free entry point window, in which case the value will be unique per window.

8f842dbba350821654c9dfed31f5635c

<ERROR_CODE>

Integer

131050

<ERROR_CODES_URL>

String

https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/

<ERROR_DETAILS>

String

Error code details.

In order to maintain a healthy ecosystem engagement, the message failed to be delivered.

<ERROR_MESSAGE>

String

Error code message. This value is the same as the title property value.

This message was not delivered to maintain healthy ecosystem engagement.

<ERROR_TITLE>

String

Error code title. This value is the same as the message property value.

This message was not delivered to maintain healthy ecosystem engagement.

<IDENTITY_KEY_HASH>

String

Identity key hash. Only included if you have enabled the identity change check feature.

DF2lS5v2W6x=

<IS_BILLABLE?>

Boolean

Indicates if the message is billable (true) or not (false).

Note that the billable property will be deprecated in a future versioned release, so we recommend that you start using pricing.type and pricing.category together to determine if a message is billable, and if so, its billing rate.

true

<PRICING_CATEGORY>

String

Pricing category (rate) applied if billable. Values can be:

authentication — Indicates authentication rate applied.

authentication-international — Indicates authentication-international rate applied.

marketing — Indicates marketing rate applied.

marketing_lite — Indicates a Marketing Messages Lite API pricing applied.

referral_conversion — Indicates a free entry point conversation.

service – Indicates service rate applied.

utility — Indicates utility rate applied.

service

<PRICING_MODEL>

String

Pricing model. Values can be:

CBP — Indicates conversation-based pricing applies. Will only be set to this value if the webhook was sent before July 1, 2025.

PMP — Indicates per-message pricing applies.

PMP

<PRICING_TYPE>

String

Pricing type. Available starting July 1, 2025. Values can be:

regular — Indicates the message is billable.

free_customer_service — Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.

free_entry_point — Indicates the message is free because it was sent within an open free entry point window.

regular

<STATUS>

String

Message status. Values can be:

delivered — Indicates message was successfully delivered to the WhatsApp user's device.

failed — Indicates failure to send or deliver the message to the WhatsApp user's device.

read — Indicates the message was displayed in an open chat thread in the WhatsApp user's device.

sent — Indicates the message was successfully sent from our servers.

read

<WEBHOOK_TRIGGER_TIMESTAMP>

String

Unix timestamp indicating when the webhook was triggered.

1739321024

<WHATSAPP_BUSINESS_ACCOUNT_ID>

String

WhatsApp Business Account ID.

102290129340398

<WHATSAPP_MESSAGE_ID>

String

WhatsApp message ID.

wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=

<WHATSAPP_USER_ID>

String

WhatsApp user ID. Note that a WhatsApp user's ID and phone number may not always match.

16505551234

Examples

This example webhook describes a marketing message that has been successfully sent from our servers.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

This example v24.0 webhook describes a marketing message that has been displayed in the WhatsApp client (i.e. "read"). Notice that in this case, the conversation object is omitted because it's a v24.0 webhook, and the pricing object is omitted because it happened to be displayed in an associated delivered status messages webhook (the object can only appear in one or the other).

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

This example describes a message that failed to be sent.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}