Client Documentation
Get StartedStatus Page
  • 360Dialog
    • Why you should use 360dialog as Business Solution Provider (BSP)
    • Prices, plans and payment options
  • client hub
    • 360Dialog Client Hub
    • Numbers
      • Manage your WABA
        • Account Statuses
    • Activity
    • Funds
      • Month Closing Invoice (MCI)
    • Payment Management
    • API Keys
    • Template Message Management
    • Partner Change
    • Cancellation
    • Downgrade
  • WhatsApp Marketing
    • Best practices to maintain Account Health and prevent being blocked
    • Driving users to your WhatsApp account
      • WhatsApp Channels
    • Business Search
    • Linking a WABA to a Facebook Page /EN
      • Vinculando uma conta WABA à uma página do Facebook /PT
      • Cómo vincular un WABA a una página de Facebook /ES
    • Linking a WABA to Google Message Ads
    • Ads that Click to WhatsApp (CTWA) /EN
      • Anúncios de Clique para o WhatsApp (CTWA) /PT
        • Como usar o WhatsApp para marketing e vendas? /PT
      • Anuncios que Click to WhatsApp (CTWA) /ES
        • ¿Cómo usar WhatsApp para marketing y ventas? /ES
    • Conversions API (CAPI)
    • Create Ads lookalike audience based on WhatsApp events
    • MM Lite API Beta
      • Onboarding
      • Sending Messages
  • waba basics
    • WhatsApp Business Platform
    • WhatsApp Accounts structure
    • WABA for Government Agencies
    • WABA Policy Enforcement
    • Architecture and Security
    • The Basics (Overview)
    • Webhook Events and Notifications
    • Messaging API
      • Messaging Health Status
      • Step to Step to move to Cloud API
        • [will be deprecated] WABA Integration (On-Premise)
    • Migrating Phone Numbers
      • Migrate number from Meta or alternate BSP to 360dialog Cloud API
      • Migrate a phone number to a new WABA
      • Migrate to alternate BSP
  • waba management
    • Creating new WABA
      • Using a new phone number
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
    • Display Name Guidelines
    • Meta Business Verification
    • Official Business Account (OBA) or blue badge
    • WABA Profile Info
    • Capacity, Quality Rating, and Messaging Limits
      • Accelerated Onboarding
    • Hosting type Change
  • waba Messaging
    • Sandbox (Test API Key)
    • Receiving messages
    • Before sending a message
      • Checklist for Message Broadcasts and Campaigns
    • Conversations
    • Messaging
    • Conversational Components
    • Media Messages
      • Upload, retrieve or delete media
    • Template Messages
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Interactive Messages
      • Single and Multi Product Messages
      • Location Request Message
    • Flows
    • Products & Catalogs
    • Contacts and Location Messages
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore only)
      • Receive WhatsApp Payments via Stripe
  • Partners
    • Partner Documentation
  • Support
    • Help and Support
      • Opening Hours & Response Time
      • Status Pages
      • Meta Support
      • Common Issues
      • How to contact Support
    • Error Messages
    • Imprint & Data Privacy
    • FAQ
Powered by GitBook
On this page
  • Messaging Webhooks (associated with Messaging API)
  • Text Messages
  • Reaction Messages
  • Media Messages
  • Unknown Messages
  • Location Messages
  • Contacts Messages
  • Received Callback from a Quick Reply Button
  • Received Answer From List Message
  • Received Answer to Reply Button
  • Received Message Triggered by Click to WhatsApp Ads
  • Flow completed
  • Request_message
  • Product Inquiry Messages
  • Order Messages
  • User Changed Number Notification
  • Template held for Pacing
  • Message Status Updates
  • Status: Message Sent
  • Status: Message Delivered
  • Status: Message Read
  • Status: Message Deleted
  • Status: Message Failed
  • Status: Message Undeliverable (Experiments)

Was this helpful?

  1. waba basics

Webhook Events and Notifications

PreviousThe Basics (Overview)NextMessaging API

Last updated 1 year ago

Was this helpful?

Messaging Webhooks (associated with Messaging API)

, it will receive notifications about events. These events are grouped and can be used for:

  • Inbound Message Notifications: Use it to get a notification when a customer performs an action, such as:

  • 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

Message Status Notifications: Use it to monitor the status of sent messages.

  • delivered

  • read

  • sent

If a webhook event isn't delivered for any reason (e.g., the client is offline) or if the webhook request returns a HTTP status code other than 200, we retry the webhook delivery. We continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.

For Cloud API, the object is always whatsapp_business_account but the field will be indicative of the type of information being sent.

{
  "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
        },
        "contacts": [{
          "profile": {
            "name": "NAME"
          },
          "wa_id": PHONE_NUMBER
        }],
        "messages": [{
          "from": PHONE_NUMBER,
          "id": "wamid.ID",
          "timestamp": TIMESTAMP,
          "text": {
            "body": "MESSAGE_BODY"
          },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

[will be deprecated] For On-premise API, the object will be contacts and messages, errors, or statuses and pricing.

{
  "contacts": [{
    "profile": {
      "name": "NAME"
    },
    "wa_id": "WHATSAPP_BUSINESS_ACCOUNT_ID"
  }],
  "messages":[{
    "from": "PHONE_NUMBER",
    "id": "wamid.ID",
    "timestamp": "TIMESTAMP",
    "text": {
      "body": "MESSAGE_BODY"
    },
    "type": "text"
  }]
} 

Text Messages

The following is an example of a text message you received from a customer:

Example 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
              },
              "contacts": [{
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": PHONE_NUMBER
                }],
              "messages": [{
                  "from": PHONE_NUMBER,
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "text": {
                    "body": "MESSAGE_BODY"
                  },
                  "type": "text"
                }]
          },
          "field": "messages"
        }]
  }]
}

Reaction Messages

The following is an example of a reaction message you received from a customer. You will not receive this webbook if the message the customer is reacting to is more than 30 days old.

Example 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
            },
            "contacts": [{
                "profile": {
                  "name": "NAME"
                },
                "wa_id": PHONE_NUMBER
              }],
            "messages": [{
                "from": PHONE_NUMBER,
                "id": "wamid.ID",
                "timestamp": TIMESTAMP,
                "reaction": {
                  "message_id": "MESSAGE_ID",
                  "emoji": "EMOJI"
                },
                "type": "reaction"
              }]
        },
        "field": "messages"
      }]
}]
}

Note that for reactions, the timestamp value indicates when the customer sent the reaction, not when the webhook was generated.

Media Messages

When a message with media is received, the WhatsApp Business Platform downloads the media. A notification is sent to the Webhook once the media is downloaded.

Example 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
              },
              "contacts": [{
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "WHATSAPP_ID"
                }],
              "messages": [{
                  "from": PHONE_NUMBER,
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "type": "image",
                  "image": {
                    "caption": "CAPTION",
                    "mime_type": "image/jpeg",
                    "sha256": "IMAGE_HASH",
                    "id": "ID"
                  }
                }]
          },
          "field": "messages"
        }]
    }]
}

When you receive a sticker, you will get the following notification:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "PHONE_NUMBER",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "NAME"
                },
                "wa_id": "ID"
              }
            ],
            "messages": [
              {
                "from": "SENDER_PHONE_NUMBER",
                "id": "wamid.ID",
                "timestamp": "TIMESTAMP",
                "type": "sticker",
                "sticker": {
                  "mime_type": "image/webp",
                  "sha256": "HASH",
                  "id": "ID"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Unknown Messages

It's possible to receive an unknown message callback notification. For example, a customer could send you a message that's not supported, such as a disappearing message (in which case Meta notifies the that the message type is not supported).

Example Payload

The following is an example of a message you received from a customer that is not supported.

{
  "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" 
              },
              "contacts": [{
                  "profile": { 
                    "name": "NAME" 
                  }, 
                  "wa_id": "WHATSAPP_ID"
                }],
              "messages": [{
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID", 
                  "timestamp": "TIMESTAMP",
                  "errors": [ 
                    { 
                      "code": 131051, 
                      "details": "Message type is not currently supported",
                      "title": "Unsupported message type"
                    }],
                   "type": "unknown"
                   }]
            }
            "field": "messages"
        }],
    }]
}

Location Messages

The following is an example of a location message you received from a customer:

Example 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"
              },
              "contacts": [{
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "WHATSAPP_ID"
                }],
              "messages": [{
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID",
                  "timestamp": "TIMESTAMP",
                 "location": {
                    "latitude": LOCATION_LATITUDE,
                    "longitude": LOCATION_LONGITUDE,
                    "name": LOCATION_NAME,
                    "address": LOCATION_ADDRESS,
                 }
                }]
          },
          "field": "messages"
        }]
    }]
}

Contacts Messages

The following is an example of a contact message you received from a customer:

Example 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"
          },
        "contacts": [{
          "profile":{
            "name":"NAME"
            },
          "wa_id":"WHATSAPP_ID"
          }],
        "messages":[{
          "from":"PHONE_NUMBER",
          "id":"wamid.ID",
          "timestamp":"TIMESTAMP",
          "contacts":[{
            "addresses":[{
              "city":"CONTACT_CITY",
              "country":"CONTACT_COUNTRY",
              "country_code":"CONTACT_COUNTRY_CODE",
              "state":"CONTACT_STATE",
              "street":"CONTACT_STREET",
              "type":"HOME or WORK",
              "zip":"CONTACT_ZIP"
            }],
            "birthday":"CONTACT_BIRTHDAY",
            "emails":[{
              "email":"CONTACT_EMAIL",
              "type":"WORK or HOME"
              }],
            "name":{
              "formatted_name":"CONTACT_FORMATTED_NAME",
              "first_name":"CONTACT_FIRST_NAME",
              "last_name":"CONTACT_LAST_NAME",
              "middle_name":"CONTACT_MIDDLE_NAME",
              "suffix":"CONTACT_SUFFIX",
              "prefix":"CONTACT_PREFIX"
              },
            "org":{
              "company":"CONTACT_ORG_COMPANY",
              "department":"CONTACT_ORG_DEPARTMENT",
              "title":"CONTACT_ORG_TITLE"
              },
            "phones":[{
              "phone":"CONTACT_PHONE",
              "wa_id":"CONTACT_WA_ID",
              "type":"HOME or WORK>"
              }],
            "urls":[{
              "url":"CONTACT_URL",
              "type":"HOME or WORK"
              }]
            }]
          }]
        },
      "field":"messages"
    }]
  }]
}

Received Callback from a Quick Reply Button

Example 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
              },
              "contacts": [{
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "WHATSAPP_ID"
                }],
              "messages": [{
                  "context": {
                    "from": PHONE_NUMBER,
                    "id": "wamid.ID"
                  },
                  "from": "16315551234",
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "type": "button",
                  "button": {
                    "text": "No",
                    "payload": "No-Button-Payload"
                  }
                }]
          },
          "field": "messages"
        }]
    }]
}

Received Answer From List Message

The following webhook notification is received when a user clicks on an item from a list message you sent:

Example 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",
              },
              "contacts": [
                {
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "PHONE_NUMBER_ID"
                }
              ],
              "messages": [
                {
                  "from": PHONE_NUMBER_ID,
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "interactive": {
                    "list_reply": {
                      "id": "list_reply_id",
                      "title": "list_reply_title",
                      "description": "list_reply_description"
                    },
                    "type": "list_reply"
                  },
                  "type": "interactive"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Received Answer to Reply Button

The following webhook notification is received when a user clicks on a reply button you sent:

Example 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,
              },
              "contacts": [
                {
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "PHONE_NUMBER_ID"
                }
              ],
              "messages": [
                {
                  "from": PHONE_NUMBER_ID,
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "interactive": {
                    "button_reply": {
                      "id": "unique-button-identifier-here",
                      "title": "button-text",
                    },
                    "type": "button_reply"
                  },
                  "type": "interactive"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Received Message Triggered by Click to WhatsApp Ads

You get the following webhook when a conversation is started after a user clicks an ad with a Click to WhatsApp’s call-to-action:

Example Payload
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "PHONE_NUMBER",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "NAME"
                },
                "wa_id": "ID"
              }
            ],
            "messages": [
              {
                "referral": {
                  "source_url": "AD_OR_POST_FB_URL",
                  "source_id": "ADID",
                  "source_type": "ad or post",
                  "headline": "AD_TITLE",
                  "body": "AD_DESCRIPTION",
                  "media_type": "image or video",
                  "image_url": "RAW_IMAGE_URL",
                  "video_url": "RAW_VIDEO_URL",
                  "thumbnail_url": "RAW_THUMBNAIL_URL",
                  "ctwa_clid": "CTWA_CLID"
                },
                "from": "SENDER_PHONE_NUMBERID",
                "id": "wamid.ID",
                "timestamp": "TIMESTAMP",
                "type": "text",
                "text": {
                  "body": "BODY"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Flow completed

When the user completes the flow, a message is sent to WhatsApp chat. You will receive that message through a webhook which you normally use to process chat messages from the user.

Example Payload
{
  "messages": [{
    "context": {
      "from": "16315558151",
      "id": "gBGGEiRVVgBPAgm7FUgc73noXjo"
    },
    "from": "<USER_ACCOUNT_NUMBER>",
    "id": "<MESSAGE_ID>",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "response_json": {
            "flow_token": "<FLOW_TOKEN>", 
            "optional_param1": "<value1>",
            "optional_param2": "<value2>"
        }
      }
    },
    "timestamp": "<MESSAGE_SEND_TIMESTAMP>"
  }]
}

Request_message

Example Payload
{
  "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>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "type": "request_welcome"  // Indicates first time message from WhatsApp user
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Product Inquiry Messages

A Product Inquiry Message is received when a customer asks for more information about a product. These can happen when:

  • a customer accesses a business's catalog via another entry point, navigates to a Product Details page, and clicks Message Business about this Product.

A webhooks notification for a Product Inquiry Message looks like this:

Example Payload
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "ID",
      "changes": [
        {
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                   "display_phone_number": "PHONE_NUMBER",
                   "phone_number_id": "PHONE_NUMBER_ID",
              },
              "contacts": [
                {
                  "profile": {
                    "name": "NAME"
                  },
                  "wa_id": "PHONE_NUMBER_ID"
                }
              ],
              "messages": [
                {
                  "from": "PHONE_NUMBER",
                  "id": "wamid.ID",
                  "text": {
                    "body": "MESSAGE_TEXT"
                  },
                  "context": {
                    "from": "PHONE_NUMBER",
                    "id": "wamid.ID",
                    "referred_product": {
                      "catalog_id": "CATALOG_ID",
                      "product_retailer_id": "PRODUCT_ID"
                    }
                  },
                  "timestamp": "TIMESTAMP",
                  "type": "text"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Order Messages

A webhooks notification for when a customer places an order looks like this:

Example Payload
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "8856996819413533",
      "changes": [
        {
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                   "display_phone_number": "16505553333",
                   "phone_number_id": "phone-number-id",
              },
              "contacts": [
                {
                  "profile": {
                    "name": "Kerry Fisher"
                  },
                  "wa_id": "16315551234"
                }
              ],
              "messages": [
                {
                  "from": "16315551234",
                  "id": "wamid.ABGGFlCGg0cvAgo6cHbBhfK5760V",
                  "order": {
                    "catalog_id": "the-catalog_id",
                    "product_items": [
                      {
                        "product_retailer_id":"the-product-SKU-identifier",
                        "quantity":"number-of-item",
                        "item_price":"unitary-price-of-item",
                        "currency":"price-currency"
                      },
                      ...
                    ],
                    "text":"text-message-sent-along-with-the-order"
                  },
                  "context": {
                    "from": "16315551234",
                    "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
                  },
                  "timestamp": "1603069091",
                  "type": "order"
                }
              ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

User Changed Number Notification

When a user changes their phone number on WhatsApp, you receive a system message notification:

Example 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
              },
              "messages": [{
                  "from": PHONE_NUMBER,
                  "id": "wamid.ID",
                  "system": {
                    "body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER",
                    "new_wa_id": NEW_PHONE_NUMBER,
                    "type": "user_changed_number"
                  },
                  "timestamp": TIMESTAMP,
                  "type": "system"
                }]
          },
          "field": "messages"
        }]
    }]
}

Template held for Pacing

Example Payload

Messages will have one of the following statuses which will be returned in each of the messages objects

  • "message_status":"accepted" : means the message was sent to the intended recipient.

  • "message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point.

      {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
          "message_status": "Message has been held because quality assessment is pending",
          //"message_status": "accepted",
        }
      ]
    }

Message Status Updates

The order of these events may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.

Status: Message Sent

Example 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"
      },
    "statuses": [{
      "id": "wamid.ID",
      "status": "sent",
      "timestamp": TIMESTAMP,
      "recipient_id": PHONE_NUMBER,
      "conversation": {
        "id": "CONVERSATION_ID",
        "expiration_timestamp": TIMESTAMP,
        "origin": {
          "type": "referral_conversion"
          }
      },
      "pricing": {
        "billable": false,
        "pricing_model": "CBP",
        "category": "referral_conversion"
        }
     }]
    },
    "field": "messages"
   }]
 }]
}
Example 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"
      },
    "statuses": [{
      "id": "wamid.ID",
      "recipient_id": "PHONE_NUMBER",
      "status": "sent",
      "timestamp": "TIMESTAMP",
      "conversation": {
        "id": "CONVERSATION_ID",
        "expiration_timestamp": TIMESTAMP,
        "origin": {
          "type": "business_initated"
          }
        },
      "pricing": {
        "pricing_model": "CBP",
        "billable": true,
        "category": "business_initated"
        }
      }] 
    },
    "field": "messages"
    }]
 }]
}
Example Payload
{
  "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": "sent",
                "timestamp": "TIMESTAMP",
                "recipient_id": "CUSTOMER_PHONE_NUMBER",
                "conversation": {
                  "id": "CONVERSATION_ID",
                  "expiration_timestamp": "CONVERSATION_EXPIRATION_TIMESTAMP",
                  "origin": {
                    "type": "user_initiated"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Status: Message Delivered

Example 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"
      },
    "statuses": [{
      "id": "wamid.ID",
      "recipient_id": "PHONE_NUMBER",
      "status": "delivered",
      "timestamp": "TIMESTAMP",
      "conversation": {
        "id": "CONVERSATION_ID",
        "expiration_timestamp": TIMESTAMP,
        "origin": {
          "type": "user_initiated"
         }
        },
      "pricing": {
        "pricing_model": "CBP",
        "billable": true,
        "category": "service"
        }
      }]
     },
    "field": "messages"
  }]
 }]
Example 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"
      },
    "statuses": [{
      "id": "wamid.ID",
      "recipient_id": "PHONE_NUMBER",
      "status": "delivered",
      "timestamp": "TIMESTAMP",
      "conversation": {
        "id": "CONVERSATION_ID",
        "expiration_timestamp": TIMESTAMP,
        "origin": {
          "type": "business_initiated"
        }
      },
      "pricing": {
        "pricing_model": "CBP",
        "billable": true,
        "category":"business-initiated"
      }
    }]
    },
    "field": "messages"
  }]
 }]
}
Example 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"
      },
    "statuses": [{
      "id": "wamid.ID",
      "status": "sent",
      "timestamp": "TIMESTAMP",
      "recipient_id": "PHONE_NUMBER",
      "conversation": {
        "id": "CONVERSATION_ID",
        "expiration_timestamp": TIMESTAMP,
        "origin" {
          "type": "referral_conversion"
          }
        },
      "pricing": {
        "billable": false,
        "pricing_model": "CBP",
        "category": "referral_conversion"
      }
    }]
    },
    "field": "messages"
  }]
 }]
}

Status: Message Read

Example Payload
{
  "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": "read",
                "timestamp": "TIMESTAMP",
                "recipient_id": "CUSTOMER_PHONE_NUMBER"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Status: Message Deleted

Currently, the Cloud API does not support webhook status updates for deleted messages. If a user deletes a message, you will receive a webhook with an error code for an unsupported message type:

Example 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
      },
      "contacts": [{
        "profile": {
          "name": "NAME"
          },
        "wa_id": PHONE_NUMBER
        }],
    "messages": [{
      "from": PHONE_NUMBER,
      "id": "wamid.ID",
      "timestamp": TIMESTAMP,
      "errors": [{
        "code": 131051,
        "details": "Message type is not currently supported",
        "title": "Unsupported message type"
        }],
      "type": "unsupported"
      }]
    },
    "field": "messages"
    }]
  }]
}

Status: Message Failed

Example Payload
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTIxMTU1NTc5NDcVAgARGBIyRkQxREUxRDJFQUJGMkQ3NDIA",
                "status": "failed",
                "timestamp": "1689380458",
                "recipient_id": "15551234567",
                "errors": [
                  {
                    "code": 131014,
                    "title": "Request for url https://URL.jpg failed with error: 404 (Not Found)"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Status: Message Undeliverable (Experiments)

Example Payload
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398 ",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTIxMTU1NTc5NDcVAgARGBIyRkQxREUxRDJFQUJGMkQ3NDIA",
                "status": "failed",
                "timestamp": "1689380458",
                "recipient_id": "15551234567",
                "errors": [
                  {
                    "code": 130472,
                    "title": "User's number is part of an experiment",
                    "message": "User's number is part of an experiment",
                    "error_data": {
                      "details": "Failed to send message because this user's phone number is part of an experiment"
                    },
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

See

See .

See .

The Webhook notification contains information that identifies the media object and enables you to find and retrieve the object. .

See.

See .

See

When your customer clicks on a quick reply button in an , a response is sent. Below is an example of the callback format.

See

See

See .

a customer replies to , or

See

The receives an event when the message is sent, delivered, and read.

The following notification is received when a business sends a message as part of a (if that conversation did not originate in a free entry point):

The following notification is received when a business sends a message in reply to a originating from :

The following notification is received when a business sends a message as part of :

The following notification is received when a business’ message is delivered and that message is part of a (if that conversation did not originate in a ):

The following notification is received when a business’ message is delivered and that message is part of a :

The following notification is received when a business’ message is delivered and that message is part of a originating from a :

Please note that there are other user behaviors that can trigger this same error message. See .

See

Media Messages
Use the media endpoints to retrieve the media
Contacts Messages
Interactive Messages.
interactive message template
Interactive Messages.
Interactive Messages.
Conversational Components
Single or Multi-Product Messages
Order Details Template Messages
Messaging webhook
user-initiated conversation
a business-initiated conversation
business-initiated conversation
Error Messages
messaging
After the webhook is set for the number
user-initiated conversation
user-initiated conversation
user-initiated conversation
Reaction Messages
Location Messages
Text Messages.
free entry points
free entry point
free entry point
Experiments in Marketing Messages.