Callback URL WhatsApp Business

In this section, we help you to provide indications of how the callback URL service should be built to receive the status of the whatsApp messages of your campaign.

If you want to receive the status of the whatsApp message you've sent to your subscribers, we can have them delivered to you in real-time. Specify your endpoint and we will send the status of the outbound messages to you as soon as they are delivered to us by a meta operator. Your endpoint must have a POST access method and receive a JSON body.

You must provide us with the following URL structure:

POST https://Your_Domain/Your_Path

📘
NOTE
Send WhatsApp Message API will make a POST request to your URL.

The URL is the external callback where the events of the WhatsApp message will be registered and published. That is, the following example parameters sent to your callback URL will be the events to be recorded in the callback once the message has been sent to the recipients:

Parameter	Description
callback	Webhook URL to notify about the events of the whatsApp message. Date when the API receives the WhatsApp message status. The date is represented with date in UTC Zulu format: (yyyy-mm-dd-Thh:mm:ss.ssZ).
date	Date when the API receives the WhatsApp message status. The date is represented with date in UTC Zulu format: (yyyy-mm-dd-Thh:mm:ss.ssZ).
externalId	Alphanumeric identifier used to identify your whatsApp messages uniquely for reporting purposes.
campaignId	Campaign identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
from	Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number used to originate and send the whatsApp message
id	Unique identifier of the WhatsApp message.
providerId	Unique message identifier assigned by Meta.
to	Destination address of the message.
message	Content of the whatsApp message that was sent to the end user.
username	Owner or creator of the WhatsApp message.
status	When a whatsApp Message is sent, the system assigns one of the following possible statuses to an message: `SENT`: Message was sent to the outbound delivery system. `DELIVERED`: Message was delivered to the end-device of the user. `READ`: Message has been opened or acknowledged by the end user. Note: The READ status may not be displayed because an end user can block the read option. `CODE_NOT_ALLOWED`: Sender of the WhatsApp Business Account is not valid to send the message. `FAILED`: Message delivery failed. `QUOTA_EXCEEDED`: WhatsApp Business Account exceeded the message sending limit. For more information about Messaging Limits go to: Capacity, Quality Rating, and Messaging Limits section. `EXPIRED`: Message was too old to be sent. `INCOMPLETE`: Applies to messages based on templates. Placeholders (personalized fields) of the message sent through templates must be complete.
detail	Only applies if the `"status"` is `"FAILED"`. Provides more context about why a message failed. This enhancement helps users understand the specific reason behind a failed delivery. For example: `"Re-engagement message. Message failed to send because more than 24 hours have passed since the customer last replied to this number."`
webhook	Origin of the event. `true`: The event originated if the service provider (meta) sent us the information. That is, if meta reports any event, it will be true. `false`: The event originated if we sent the information. That is, if we report any event, it will be false.

Below are two sample callback payloads to illustrate how the status and detail fields behave depending on message delivery outcomes.

When a message is successfully sent, the status is "SENT" and the payload does not include the "detail" field.
When the message fails to send, the status remains "FAILED", but a "detail" field is added to provide the reason for the failure.

These examples help demonstrate how to handle different scenarios when integrating with WhatsApp callback.

Successful Send

{
  "callback": "https://webhook.site/45654",
  "date": "2023-01-02T19:35:19.300Z",
  "externalId": "external-id-001",
  "campaignId": null,
  "from": "130523",
  "id": "id.HBgIxNTU2",
  "providerId": "wamid.45675",
  "to": "+105500000000",
  "message": "message text body",
  "username": "development",
  "status": "SENT",
  "webhook": true
}

Failed Send

{
  "callback": "https://webhook.site/45654",
  "date": "2023-01-02T19:35:19.300Z",
  "externalId": "external-id-001",
  "campaignId": null,
  "from": "130523",
  "id": "id.HBgIxNTU2",
  "providerId": "wamid.45675",
  "to": "+105500000000",
  "message": "message text body",
  "username": "development",
  "status": "FAILED",
  "detail": "Re-engagement message. Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
  "webhook": true
}

📘NOTE

📘
NOTE