WhatsApp Webhook

Request Method

POST

Webhook payload object common properties

Key	Type	Description
id	String	Unique identifier for the event.
type	String	Type of the event (e.g., whatsapp.business_account.deleted).
apiVersion	String	The API version used to render this event. This property is currently always v2.
createTime	String	The time at which this event is created, formatted in RFC 3339. e.g., 2023-06-01T12:00:00.000Z.

whatsapp.business_account.deleted

Occurs when a WhatsApp Business Account is deleted.

Payload property whatsappBusinessAccount is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2023-10-12T12:00:00.000Z",
  "whatsappBusinessAccount":  {
    "id": "106681...",
    "name": "whatsapp-business-account-name"
  }
}

whatsapp.business_account.updated

Occurs when a policy violation happened, a WhatsApp Business Account has been banned and more.

Payload property whatsappBusinessAccount is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappBusinessAccount":  {
    "id": "106681...",
    "name": "whatsapp-business-account-name",
    "accountReviewStatus": "APPROVED",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "20232-12-12T07:09:27.000Z"
      }
    ],
    "banState": "REINSTATE",
    "banDate": "December 9, 2023",
    "violationType": "SPAM"
  }
}

whatsapp.inbound_message.received

Occurs when a WhatsApp inbound message is received. For more examples, see WhatsApp Inbound Message Webhook Examples.

Payload property whatsappInboundMessage is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappInboundMessage":  {
    "id": "wim123456",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "customerProfile": {
      "name": "John"
    },
    "to": "+447901614024",
    "sendTime": "2023-03-01T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Hi there!"
    }
  }
}

whatsapp.message.updated

Occurs when a WhatsApp outbound message status is updated, and the status changes to failed, sent, delivered, or read. For more examples, see WhatsApp Message Updated Webhook Examples.

Payload property whatsappMessage is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappMessage":  {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "read",
    "type": "text",
    "text": {
      "body": "Your verification code is 123456."
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "type": "REGULAR",
      "originType": "business_initiated",
      "expireTime": "2023-03-02T12:00:00.000Z"
    },
    "totalPrice": 0.085,
    "currency": "USD",
    "createTime": "2023-03-01T12:00:00.000Z",
    "sendTime": "2023-03-01T12:00:01.000Z",
    "deliverTime": "2023-03-01T12:00:02.000Z",
    "readTime": "2023-03-01T12:00:02.000Z",
    "externalId": "ext_123456"
  }
}

Note

There is a charge when the first business message with this conversation ID is delivered, initiating the 24 hour conversation session. totalPrice is only an estimated price before the first message is delivered, and it becomes the final price when the status is delivered or read. 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).
conversation is included after the message is sent. conversation.expireTime is only an estimated time when the first message of this conversation is sent, and it will be refreshed when the first message of this conversation is delivered. See also Tracking Conversations.
It's possible for us to generate more than 1 delivered webhook event for the same message, especially if the end customer is using multiple devices.

The illustration below reflects an extreme example of conversation refreshing.

whatsapp.phone_number.deleted

Occurs when a WhatsApp business account phone number is deleted from YONI-TECH.

Payload property whatsappPhoneNumber is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2023-10-12T12:00:00.000Z",
  "whatsappPhoneNumber":  {
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id"
  }
}

whatsapp.phone_number.name_updated

Occurs when a WhatsApp business account phone number's name has been approved or rejected. See also phone_number_name_update.

Payload property whatsappPhoneNumber is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappPhoneNumber":  {
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "requestedVerifiedName": "requested-verified-name",
    "rejectionReason": "NONE",
    "status": "CONNECTED"
  }
}

whatsapp.phone_number.quality_updated

Occurs when a WhatsApp business account phone number's quality-related status is updated. See also phone_number_quality_update.

Payload property whatsappPhoneNumber is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappPhoneNumber":  {
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "RED",
    "messagingLimit": "TIER_1K",
    "qualityUpdateEvent": "UNFLAGGED",
    "status": "CONNECTED"
  }
}

whatsapp.template.category_updated

Occurs when a WhatsApp template category is updated. The old category will be set to previousCategory.

Meta will begin the first template category migration on March 27, 2023 (2023-03-27T00:00:00 PDT, UTC-07:00) and expect to complete on April 1, 2023.

Payload property whatsappTemplate is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.template.category_updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappTemplate":  {
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_template",
    "language": "en",
    "category": "UTILITY",
    "previousCategory": "TRANSACTIONAL"
  }
}

whatsapp.template.quality_updated

Occurs when a WhatsApp template quality updated, and the qualityRating may change to GREEN, YELLOW, RED, or UNKNOWN. See also Template Quality Rating.

Payload property whatsappTemplate is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.template.quality_updated",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappTemplate":  {
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "qualityRating": "GREEN"
  }
}

whatsapp.template.reviewed

Occurs when a WhatsApp template statusUpdateEvent happened, such as REJECTED, APPROVED, PENDING_DELETION, and the status may change to REJECTED, APPROVED, PAUSED, DISABLED, IN_APPEAL, or DELETED.

Payload property whatsappTemplate is included for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-03-01T12:00:00.000Z",
  "whatsappTemplate":  {
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_template",
    "language": "en",
    "category": "OTP",
    "status": "REJECTED",
    "reason": "The message template is a duplicate of an existing template.",
    "createTime": "2023-03-01T12:00:00.000Z",
    "updateTime": "2023-03-01T12:00:00.000Z",
    "statusUpdateEvent": "REJECTED"
  }
}

Test Examples

curl --location 'https://YOUR-WEBHOOK-URL' \
--header 'Content-Type: application/json' \
--data '{
    "id": "evt_eEVCy8eNqD9EvcFI",
    "type": "whatsapp.message.updated",
    "apiVersion": "v2",
    "createTime": "2023-06-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",
        "createTime": "2023-03-01T12:00:00.000Z",
        "sendTime": "2023-03-01T12:00:01.000Z",
        "bizType": "whatsapp"
    }
}'

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"id\": \"evt_eEVCy8eNqD9EvcFI\",\r\n    \"type\": \"whatsapp.message.updated\",\r\n    \"apiVersion\": \"v2\",\r\n    \"createTime\": \"2023-06-22T12:00:00.000Z\",\r\n    \"whatsappMessage\": {\r\n        \"id\": \"63f5d602367ea403f8175a6c\",\r\n        \"wamid\": \"wamid.BgNODYxN...\",\r\n        \"status\": \"sent\",\r\n        \"conversation\": {\r\n            \"id\": \"00e5a7e14a588d96bd2343d105d03ec5\",\r\n            \"originType\": \"marketing\",\r\n            \"expireTime\": \"2023-02-23T12:00:00.000Z\"\r\n        },\r\n        \"totalPrice\": 0.0,\r\n        \"currency\": \"USD\",\r\n        \"createTime\": \"2023-03-01T12:00:00.000Z\",\r\n        \"sendTime\": \"2023-03-01T12:00:01.000Z\",\r\n        \"bizType\": \"whatsapp\"\r\n    }\r\n}");
Request request = new Request.Builder()
  .url("https://YOUR-WEBHOOK-URL")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();