Facebook
    Webhooks - Cloud API - Documentation - Meta for Developers
    Cloud API

    Webhooks Notification Payload Reference

    Webhooks are triggered when a customer performs an action or the status for a message a business sends a customer changes. You get a webhooks notification:

    When a customer performs an action

    • Sends a text message to the business
    • Sends an image, video, audio, document, or sticker to the business
    • Sends contact information to the business
    • Sends location information to the business
    • Clicks a reply button set up by the business
    • Clicks a call-to-actions button on an Ad that Clicks to WhatsApp
    • Clicks an item on a business' list
    • Updates their profile information such as their phone number
    • Asks for information about a specific product
    • Orders products being sold by the business

    When the status for a message received by a business changes(includes pricing information)

    • delivered
    • read
    • sent

    Notification Payload Object

    The notification payload is a combination of nested objects of JSON arrays and objects that contain information about a change.

    Example Notification Payload

    {
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
    "changes": [{
      "value": {
         "messaging_product": "whatsapp",
         "metadata": {
           "display_phone_number": "PHONE-NUMBER",
           "phone_number_id": "PHONE-NUMBER-ID"
         },
      # Additional arrays and objects
         "contacts": [{...}]
         "errors": [{...}]
         "messages": [{...}]
         "statuses": [{...}]
      },
      "field": "messages"
    }]
  }]
}

    The Nested Structure of the Notification Payload

    Name
    Description

    object

    string

    The specific webhook a business is subscribed to. The webhook is whatsapp_business_account .

    entry

    array of objects

    An array of entry objects. Entry objects have the following properties:


    • id — String . The WhatsApp Business Account ID for the business that is subscribed to the webhook.
    • changes — Array of objects . An array of change objects. Change objects have the following properties:
      • value — Object . A value object. See Value Object .
      • field — String . Notification type. Value will be messages .

    Value Object

    The value object contains details for the change that triggered the webhook. This object is nested within the changes array of the entry array.

    Name
    Description

    contacts

    array of objects

    Array of contact objects with information for the customer who sent a message to the business. Contact objects have the following properties:


    • wa_id — String . The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.
    • profile — Object . A customer profile object. Profile objects have the following properties:
      • name — String . The customer's name.

    errors

    array of objects

    An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads .


    Webhooks triggered by v15.0 and older requests:


    • code — Integer . Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .

    Webhooks triggered by v16.0 and newer requests:


    • code — Integer . Error code. Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .
    • message — String . Error code message. This value is the same as the title value. For example: Rate limit hit . Note that the message property in API error response payloads pre-pends this value with the a # symbol and the error code in parenthesis. For example: (#130429) Rate limit hit .
    • error_data — Object . An error data object with the following properties:
      • details — String . Describes the error. Example: Message failed to send because there were too many messages sent from this phone number in a short period of time .

    messaging_product

    string

    Product used to send the message. Value is always whatsapp .

    messages

    array of objects

    Information about a message received by the business that is subscribed to the webhook. See Messages Object .

    metadata

    object

    A metadata object describing the business subscribed to the webhook. Metadata objects have the following properties:


    • display_phone_number — String. The phone number that is displayed for a business.
    • phone_number_id — String. ID for the phone number. A business can respond to a message using this ID.

    statuses

    array of objects

    Status object for a message that was sent by the business that is subscribed to the webhook. See Statuses Object .

    Messages Objects

    The messages array of objects is nested within the value object and is triggered when a customer updates their profile information or a customer sends a message to the business that is subscribed to the webhook.

    Name
    Description

    audio

    object

    When the messages type is set to audio , including voice messages, this object is included in the messages object:


    • id — String. ID for the audio file.
    • mime_type — String. Mime type of the audio file.

    button

    object

    When the messages type field is set to button , this object is included in the messages object:


    • payload – String. The payload for a button set up by the business that a customer clicked as part of an interactive message.
    • text — String. Button text.

    context

    object

    Context object. Only included when a user replies or interacts with one of your messages. Context objects can have the following properties:


    • forwarded — Boolean . Set to true if the message received by the business has been forwarded.
    • frequently_forwarded — Boolean . Set to true if the message received by the business has been forwarded more than 5 times.
    • from — String. The WhatsApp ID for the customer who replied to an inbound message.
    • id — String. The message ID for the sent message for an inbound reply.
    • referred_product — Object. Referred product object describing the product the user is requesting information about. You must parse this value if you support Product Enquiry Messages. See Receive Response From Customers . Referred product objects have the following properties:
      • catalog_id — String. Unique identifier of the Meta catalog linked to the WhatsApp Business Account.
      • product_retailer_id — String. Unique identifier of the product in a catalog.

    document

    object

    A document object. When messages type is set to document , this object is included in the messages object. Document objects can have the following properties:


    • caption — String. Caption for the document, if provided.
    • filename — String. Name for the file on the sender's device.
    • sha256 — String. SHA 256 hash.
    • mime_type — _String. _ Mime type of the document file.
    • id — String. ID for the document.

    errors

    array of objects

    An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads .


    Webhooks triggered by v15.0 and older requests:


    • code — Integer . Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .

    Webhooks triggered by v16.0 and newer requests:


    • code — Integer . Error code. Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .
    • message — String . Error code message. This value is the same as the title value. For example: Rate limit hit . Note that the message property in API error response payloads pre-pends this value with the a # symbol and the error code in parenthesis. For example: (#130429) Rate limit hit .
    • error_data — Object . An error data object with the following properties:
      • details — String . Describes the error. Example: Message failed to send because there were too many messages sent from this phone number in a short period of time .

    from

    string

    The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.

    id

    string

    The ID for the message that was received by the business. You could use messages endpoint to mark this specific message as read.

    identity

    object

    An identity object. Webhook is triggered when a customer's phone number or profile information has been updated. See messages system identity . Identity objects can have the following properties:


    • acknowledged — State of acknowledgment for the messages system customer_identity_changed .
    • created_timestamp — String. The time when the WhatsApp Business Management API detected the customer may have changed their profile information.
    • hash — String. The ID for the messages system customer_identity_changed

    image

    object

    When messages type is set to image , this object is included in the messages object.


    • caption — String . Caption for the image, if provided.
    • sha256 — String . Image hash.
    • id — String . ID for the image.
    • mime_type — String . Mime type for the image.

    interactive

    object

    When a customer has interacted with your message, this object is included in the messages object. Interactive objects have the following properties:


    • type — Object with the following properties:
      • button_reply – Sent when a customer clicks a button. Object with the following properties:
        • id — String . Unique ID of a button.
        • title — String . Title of a button.
      • list_reply — Sent when a customer selects an item from a list. Object with the following properties:
        • id — String . Unique ID of the selected list item.
        • title — String . Title of the selected list item.
        • description — String . Description of the selected row.

    order

    object

    Included in the messages object when a customer has placed an order. Order objects have the following properties:


    • catalog_id — String . ID for the catalog the ordered item belongs to.
    • text — String . Text message from the user sent along with the order.
    • product_items — Array of product item objects containing the following fields:
      • product_retailer_id — String . Unique identifier of the product in a catalog.
      • quantity — String . Number of items.
      • item_price — String . Price of each item.
      • currency — String . Price currency.

    referral

    object

    Referral object. When a customer clicks an ad that redirects to WhatsApp, this object is included in the messages object. Referral objects have the following properties:


    • source_url – String . The Meta URL that leads to the ad or post clicked by the customer. Opening this url takes you to the ad viewed by your customer.
    • source_type – String . The type of the ad’s source; ad or post .
    • source_id – String . Meta ID for an ad or a post.
    • headline – String . Headline used in the ad or post.
    • body – String . Body for the ad or post.
    • media_type – String . Media present in the ad or post; image or video .
    • image_url – String . URL of the image, when media_type is an image.
    • video_url – String . URL of the video, when media_type is a video.
    • thumbnail_url – String . URL for the thumbnail, when media_type is a video.
    • ctwa_clid – String . Click ID generated by Meta for ads that click to WhatsApp.

    The referral object can be included in the following types of message: text, location, contact, image, video, document, voice, and sticker.

    sticker

    object

    When messages type is set to sticker , this object is included in the messages object. Sticker objects have the following properties:


    • mime_type – String . image/webp.
    • sha256 – String . Hash for the sticker.
    • id – String . ID for the sticker.
    • animated – Boolean . Set to true if the sticker is animated; false otherwise.

    system

    object

    When messages type is set to system , a customer has updated their phone number or profile information, this object is included in the messages object. System objects have the following properties:


    • body – String . Describes the change to the customer's identity or phone number.
    • identity – String . Hash for the identity fetched from server.
    • new_wa_id – String . New WhatsApp ID for the customer when their phone number is updated. Available on webhook versions v11.0 and earlier.
    • wa_id – String . New WhatsApp ID for the customer when their phone number is updated. Available on webhook versions v12.0 and later.
    • type – String . Type of system update. Will be one of the following:.
      • customer_changed_number – A customer changed their phone number.
      • customer_identity_changed – A customer changed their profile information.
    • customer – String . The WhatsApp ID for the customer prior to the update.

    text

    object

    When messages type is set to text , this object is included. Text objects have the following properties:


    • body — String . The text of the message.

    timestamp

    string

    Unix timestamp indicating when the WhatsApp server received the message from the customer.

    type

    string

    The type of message that has been received by the business that has subscribed to Webhooks. Possible value can be one of the following:


    • audio
    • button
    • document
    • text
    • image
    • interactive
    • order
    • sticker
    • system – for customer number change messages
    • unknown
    • video

    video

    object

    When messages type is set to video , this object is included in messages object. Video objects have the following properties:


    • caption – String . The caption for the video, if provided.
    • filename – String . The name for the file on the sender's device.
    • sha256 – String . The hash for the video.
    • id – String . The ID for the video.
    • mime_type – String . The mime type for the video file.

    Statuses Object

    The statuses object is nested within the value object and is triggered when a message is sent or delivered to a customer or the customer reads the delivered message sent by a business that is subscribed to the Webhooks.

    Name
    Description
    biz_opaque_callback_data
    string

    Arbitrary string included in sent message. See Message object.

    conversation
    object

    Information about the conversation.

    id – Represents the ID of the conversation the given status notification belongs to.

    origin object – Describes conversation category

    type – Indicates conversation category. This can also be referred to as a conversation entry point

    authentication – Indicates the conversation was opened by a business sending template categorized as AUTHENTICATION to the customer. This applies any time it has been more than 24 hours since the last customer message.

    marketing – Indicates the conversation was opened by a business sending template categorized as MARKETING to the customer. This applies any time it has been more than 24 hours since the last customer message.

    utility – Indicates the conversation was opened by a business sending template categorized as UTILITY to the customer. This applies any time it has been more than 24 hours since the last customer message.

    service – Indicates that the conversation opened by a business replying to a customer within a customer service window.

    referral_conversion – Indicates a free entry point conversation .

    expiration_timestamp – Date when the conversation expires. This field is only present for messages with a `status` set to `sent`.


    See Conversations for more information about conversations and conversation categories.

    errors

    array of objects

    An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads .


    Webhooks triggered by v15.0 and older requests:


    • code — Integer . Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .

    Webhooks triggered by v16.0 and newer requests:


    • code — Integer . Error code. Example: 130429 .
    • title — String . Error code title. Example: Rate limit hit .
    • message — String . Error code message. This value is the same as the title value. For example: Rate limit hit . Note that the message property in API error response payloads pre-pends this value with the a # symbol and the error code in parenthesis. For example: (#130429) Rate limit hit .
    • error_data — Object . An error data object with the following properties:
    • details — String . Describes the error. Example: Message failed to send because there were too many messages sent from this phone number in a short period of time .
    id string

    The ID for the message that the business that is subscribed to the webhooks sent to a customer

    pricing object

    An object containing pricing information.

    billable – Indicates if the given message or conversation is billable. Default is true for all conversations, including those inside your free tier limit, except those initiated from free entry points. Free entry point conversatsion are not billable, false . You will not be charged for free tier limit conversations, but they are considered billable and will be reflected on your invoice. Deprecated. Visit the WhatsApp Changelog for more information.

    category – Indicates the conversation category:

    authentication – Indicates an authentication conversation.

    authentication-international – Indicates an authentication-international conversation.

    marketing – Indicates an marketing conversation.

    utility – Indicates a utility conversation.

    service – Indicates an service conversation.

    referral_conversion – Indicates a free entry point conversation .

    pricing_model – Type of pricing model used by the business. Current supported value is CBP


    See Conversations for more information about conversations and conversation categories.

    recipient_id string

    The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.

    status string

    delivered – A webhook is triggered when a message sent by a business has been delivered

    read – A webhook is triggered when a message sent by a business has been read

    sent – A webhook is triggered when a business sends a message to a customer

    timestamp Unix timestamp

    Date for the status message

    For a status to be read , it must have been delivered . In some scenarios, such as when a user is in the chat screen and a message arrives, the message is delivered and read almost simultaneously. In this or other similar scenarios, the delivered notification will not be sent back, as it is implied that a message has been delivered if it has been read. The reason for this behavior is internal optimization.

    Learn more
    Design a Mobile Website
    View Site in Mobile | Classic
    Share by: