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. 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 is sent.
  • 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 with wamid..

Note:

  • We do charge you when messages are sent.
  • 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.

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 is delivered.

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 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.

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 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 '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"
  }
}'