Message events

These events state the status of the message sent using the send message API to the WhatsApp API client(which essentially sends out a message to the customer). The WhatsApp Business API client will send notifications to inform you of the status of the messages between you and users. When you send a message successfully, you will receive a notification on your callback URL stating when the message was sent, delivered, and read. The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary. The notifications you may receive are:

{
   "app":"DemoAPI",
   "timestamp":1580546677791,
   "version":2,
   "type":"message-event",
   "payload":{
      "id":"59f8db90-c37e-4408-90ab-cc54ef8246ad"(Gupshup Message ID)|"gBEGkYaYVSEEAgnZxQ3JmKK6Wvg" (WhatsApp Message ID)
      "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35" (Gupshup Message ID - This property is only applicable for DLR events)
      "type":"enqueued"|"failed"|"sent"|"delivered"|"read|"deleted"",
      "destination":"91XX985XX10X",
      "payload": ## This varies according to 'type' property value
   }
}

πŸ“˜

Events received after a week of sending the message will not have the GSID available in the notification payload.

Common payload object description

KeyDescriptionExample
idThis is Gupshup Message Id for message-event types: enqueued and failed
In case of failed please check the below Sync and Async section.
For the DLR events sent, delivered, read it is always WhatsApp Message ID.
59f8db90-c37e-4408-90ab-cc54ef8246ad
OR
gBEGkYaYVSEEAgnZxQ3JmKK6Wvg
gsIdThis is Gupshup Message Id and only present for message-event types: DLR events: sent, delivered, read.59f8db90-c37e-4408-90ab-cc54ef8246ad
typeThe type of message-event received on your webhook
Must be one of these: enqueued, failed, sent, delivered, read.
Refer to the description given below.
destinationUser's phone number918x98xx21x4
tsThe timestamp of the event in seconds. This property is received for events sent, delivered, and read.1585344475

Types of message events

{
  "app": "DemoAPI",
  "timestamp": 1580546677791,
  "version": 2,
  "type": "message-event",
  "payload": {
    "id": "59f8db90-c37e-4408-90ab-cc54ef8246ad",
    "type": "enqueued",
    "destination": "91XX985XX10X",
    "payload": {
      "whatsappMessageId": "gBEGkYaYVSEEAgkD7bRi9syGnBk",
      "type": "session"
    }
  }
}
{
    "app": "DemoAPI",
    "timestamp": 1580311136040,
    "version": 2,
    "type": "message-event",
    "payload": {
        "id": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
        "type": "failed",
        "destination": "918x98xx21x4",
        "payload": {
            "code": 1008,
            "reason": "User is not Opted in and Inactive"
        }
    }
}
{
    "app": "DemoAPI",
    "timestamp": 1663138637856,
    "version": 2,
    "type": "message-event",
    "payload": {
        "id": "9163a016-710e-41ee-978b-79a1adbd734e",
        "gsId": "72f61f22-5aa4-4615-a970-943edf6da01c",
        "type": "failed",
        "destination": "918x98xx21x4",
        "payload": {
            "code": 470,
            "reason": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
        }
    }
}
{
   "app":"DemoAPI",
   "timestamp":1580546677791,
   "version":2,
   "type":"message-event",
   "payload":{
      "id":"59f8db90-c37e-4408-90ab-cc54ef8246ad",
      "gsId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
      "type":"sent",
      "destination":"91XX985XX10X",
      "payload":{
         "ts":1585344475
      },
      "conversation":{
         "id":"532b57b5f6e63595ccd74c6010e5c5c7",
         "expiresAt":1518780636,
         "type":"marketing/authentication/utility/service/FEP"
      },
      "pricing":{
         "policy":"CBP/NBP",
         "category":"marketing/authentication/utility/service/FEP"
      }
   }
}
{
  "app": "DemoAPI",
  "timestamp": 1585344476683,
  "version": 2,
  "type": "message-event",
  "payload": {
    "id": "gBEGkYaYVSEEAgnZxQ3JmKK6Wvg",
    "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
    "type": "delivered",
    "destination": "918x98xx21x4",
    "payload": {
      "ts": 1585344476
    }
  }
}
{
  "app": "DemoAPI",
  "timestamp": 1585344602933,
  "version": 2,
  "type": "message-event",
  "payload": {
    "id": "gBEGkYaYVSEEAgnZxQ3JmKK6Wvg",
    "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
    "type": "read",
    "destination": "918x98xx21x4",
    "payload": {
      "ts": 1585344602
    }
  }
}
{
  "app": "demoapp",
  "timestamp": 1654703394680,
  "version": 2,
  "type": "message-event",
  "payload": {
    "id": "ABEGkZhngpgo-sJRwQ6dszYhU",
    "type": "deleted",
    "destination": "919867XX9135",
    "payload": {
      "ts": 1654703389
    }
  }
}

Enqueued

This event is received when a message is successfully sent to the WhatsApp Business API client(docker).

KeyDescriptionExample
whatsappMessageIdThe WhatsApp message id generated while sending a message to an end-user on WhatsAppgBEGkYaYVSEEA
gkD7bRi9syGnBk
typeIndicates the type of message

See different types of messages you can send to users.
session

Sync Failed

This event is received when the message sending has failed. You will receive the reason for failure on your callback URL

KeyDescriptionExample
codeThe failure/exception code1002
reasonMessage failure reason with respect to the error code.

See error and status messages.
Number Does Not Exists On WhatsApp
idid is WhatsApp Message IDee4a68a0-1203-4c85-8dc3-49d0b3226a35

Async Failed

This event is received when messages have been failed by Whatsapp docker.

KeyDescriptionExample
codeThe failure/exception code1002
reasonMessage failure reason with respect to the error code.

See error and status messages.
Number Does Not Exists On WhatsApp
gsIdgsId is Gupshup Message ID72f61f22-5aa4-4615-a970-943edf6da01c

Sent

The sent event is received when the message is sent to the end-user.

conversation object description

KeyDescriptionExample
idUnique ID for a conversation.532b57b5f6e63595ccd74c6010e5c5c7
expiresAtConversation expiration timestamp in seconds1518780636
typeThe type of conversation. Possible values:

- FEP (Free entry point)
- Marketing
- Authentication
- Utility
-Service
Marketing

pricing object description

KeyDescriptionExample
policyThe pricing policy applied for this message. Possible values:

- CBP (Conversation based pricing)
- NBP (Notification based pricing)
CBP
categoryThe pricing category. Possible values:

- FEP
- Marketing
- Utility
- Authentication
- Service
Marketing

Delivered

This event is received when the message sent by your business was delivered to the user's device.

Read

The read event is received when the message sent by your business is read by the user. Read notifications will only be available for users who have read receipts enabled. For users that do not have it enabled, you will only receive the delivered notification.

For status to be read, it must have been delivered. In some scenarios, such as when a user is on the chat screen and a message arrives, the message is delivered and read almost simultaneously. In this or other similar scenarios, the given notification will not be sent back, as it is implied that a message has been delivered if it has been read.

Delete

[No longer supported by Meta] The delete event is received when a user deletes a message for everyone (not 'delete for me') which they have sent to your WhatsApp Business API.

Others

Other events are miscellaneous events received asynchronously on your callback. These are ad hoc events received from your WABAs docker.

Mismatch

This event is only triggered when the destination number provided in the API request does not match the WhatsApp ID. The mismatch event does not require a subscription and will help you manage user conversations more effectively. Learn more about the mismatch event.

KeyDescriptionExample
wa_idWhatsApp ID of the destination number5593587654321
phoneDialable number/given destination number553587654321

What’s Next

In the next chapter of this guide, you'll learn about inbound events type: Billing events