WhatsApp Message Updated Webhook Examples

🚧

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 is failed.
  • Contains errroCode, errorMessage, and whatsappApiError.

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 '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",
      "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 is sent.
  • Contains information about the conversation, including the time when the conversation expires, and the origin type.
  • Contains the estimated totalPrice we may charge you.
  • Contains wamid, which is the original message ID on WhatsApp’s platform, starting with wamid..

Note:

  • We do charge you when messages are delivered. Thus, the totalPrice is only estimated before the message is delivered. The balance taken up by those messages that are sent but haven't been delivered will not be available until the messages are dropped (Sent messages that are not delivered for 30 days are dropped).
  • The expiration time may refresh after the message is delivered, since the conversation may be in a pre-opened status now.
  • Generally, a sent message changes to delivered or read 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 message delivered.
    • The recipient has turned off read receipts, and you won’t receive the message read receipts.
    • The message changes to failed later with error code 131026, which means "Message Undeliverable.", or "Receiver is incapable of receiving this message". This is most likely that the recipient is not registered, or is using an old WhatsApp version.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-sent' \
--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": "marketing",
      "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 is delivered.

Note:

  • We do charge you when messages are delivered.
  • 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 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.
  • It's possible for us to generate more than 1 delivered webhook event for the same message, especially if the end customer is using multi-device.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-message-delivered' \
--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",
      "type": "REGULAR",
      "originType": "marketing",
      "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 is read.

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 '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",
      "type": "REGULAR",
      "originType": "marketing",
      "expireTime": "2023-02-23T12:00:00.000Z"
    },
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}'