Prerequisites
Make sure that your webhook endpoint is listening for
whatsapp.message.updated
events. See also Configure Webhooks, Retrieve a webhook endpoint API.
Message Failed
In this case, your webhook endpoint received a message failed
event:
- The message
status
isfailed
. - Contains
errroCode
,errorMessage
, andwhatsappApiError
.whatsappApiError.error_subcode
2494010 is most likely that the specific number you are sending this message to is not registered with WhatsApp.
Note:
- These events are intended to notify you of status changes of outbound messages you've previously sent to customers.
- The reason for the messaging failure is typically the message request parameters are invalid, the customer's phone number is not registered, etc.
whatsappApiError
is provided if we tried to submit this message to Meta's WhatsApp platform to help you understand the error details. See also Cloud API Error Codes.- We do not charge you for failed messages.
Code sample:
curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-failed' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "evt_eEVCy8eNqD9EvcFI",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappMessage": {
"id": "63f5d602367ea403f8175a6c",
"wamid": "wamid.BgNODYxN...",
"status": "failed",
"errorCode": "100",
"errorMessage": "Parameter Invalid",
"whatsappApiError": {
"message": "(#100) Invalid parameter",
"type": "OAuthException",
"code": "100",
"error_subcode": "2494010",
"fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
"error_data": {
"messaging_product": "whatsapp",
"details": "Parameter Invalid"
}
},
"totalPrice": 0.0,
"currency": "USD",
"bizType": "whatsapp"
}
}'
Message Sent
In this case, your webhook endpoint received a message sent
event:
- The message
status
issent
. - Contains information about the conversation, including the date when the conversation expires, and the origin type.
- Contains the final
totalPrice
we charged you. - Contains
wamid
, which is the original message ID on WhatsApp’s platform, starting withwamid.
.
Note:
- We do charge you when messages are sent.
- Generally, a
sent
message changes todelivered
orread
soon, except:- The recipient's WhatsApp account is offline, your sent WhatsApp messages won’t be delivered until the recipient has working or active internet services.
- Any messages sent to a contact who has blocked you will always show the message
sent
, and never show the messagedelivered
. - The recipient has turned off read receipts, and you won’t receive the message
read
receipts.
Code sample:
curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-sent' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "evt_eEVCy8eNqD9EvcFI",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappMessage": {
"id": "63f5d602367ea403f8175a6c",
"wamid": "wamid.BgNODYxN...",
"status": "sent",
"conversation": {
"id": "00e5a7e14a588d96bd2343d105d03ec5",
"originType": "business_initiated",
"expireTime": "2023-02-23T12:00:00.000Z"
},
"totalPrice": 0.0,
"currency": "USD",
"bizType": "whatsapp"
}
}'
Message Delivered
In this case, your webhook endpoint received a message delivered
event:
- The message
status
isdelivered
.
Note:
- This event indicates that the message sent by your business was delivered to the user’s device.
- For a status to be
read
, it must have beendelivered
. In some scenarios, such as when a user is in the chat screen and a message arrives, the message isdelivered
andread
almost simultaneously. In this or other similar scenarios, thedelivered
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.
Code sample:
curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-delivered' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "evt_eEVCy8eNqD9EvcFI",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappMessage": {
"id": "63f5d602367ea403f8175a6c",
"wamid": "wamid.BgNODYxN...",
"status": "delivered",
"conversation": {
"id": "00e5a7e14a588d96bd2343d105d03ec5",
"originType": "business_initiated",
"expireTime": "2023-02-23T12:00:00.000Z"
},
"totalPrice": 0.0,
"currency": "USD",
"bizType": "whatsapp"
}
}'
Message Read
In this case, your webhook endpoint received a message read
event:
- The message
status
isread
.
Note:
- This event indicates that the message sent by your business was read by the user.
Code sample:
curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-read' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "evt_eEVCy8eNqD9EvcFI",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappMessage": {
"id": "63f5d602367ea403f8175a6c",
"wamid": "wamid.BgNODYxN...",
"status": "read",
"conversation": {
"id": "00e5a7e14a588d96bd2343d105d03ec5",
"originType": "business_initiated",
"expireTime": "2023-02-23T12:00:00.000Z"
},
"totalPrice": 0.0,
"currency": "USD",
"bizType": "whatsapp"
}
}'