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
}
}
Common payload object description
Key | Description | Example |
---|---|---|
id | This is Gupshup Message Id for message-event types: enqueued and failed For the DLR events sent , delivered , read it is always WhatsApp Message ID. | 59f8db90-c37e-4408-90ab-cc54ef8246ad OR gBEGkYaYVSEEAgnZxQ3JmKK6Wvg |
gsId | This is Gupshup Message Id and only present for message-event types: DLR events: sent , delivered , read . | 59f8db90-c37e-4408-90ab-cc54ef8246ad |
type | The type of message-event received on your webhook Must be one of these: enqueued , failed , sent , delivered , read . | Refer to the description given below. |
destination | User's phone number | 918x98xx21x4 |
ts | The 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":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":"FEP/UIC/BIC"
},
"pricing":{
"policy":"CBP/NBP",
"category":"FEP/UIC/BIC"
}
}
}
{
"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":1638607221146,
"version":2,
"type":"message-event",
"payload":{
"id":"499a3642-5d41-477f-8bdc-58985e9c6996",
"type":"mismatch",
"destination":"5535987654321",
"payload":{
"phone":"553587654321",
"wa_id":"5593587654321"
}
}
}
{
"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).
Key | Description | Example |
---|---|---|
whatsappMessageId | The WhatsApp message id generated while sending a message to an end-user on WhatsApp | gBEGkYaYVSEEA gkD7bRi9syGnBk |
type | Indicates the type of message See different types of messages you can send to users. | session |
Failed
This event is received when the message sending has failed. You will receive the reason for failure on your callback URL
Key | Description | Example |
---|---|---|
code | The failure/exception code | 1002 |
reason | Message failure reason with respect to the error code. See error and status messages. | Number Does Not Exists On WhatsApp |
Sent
The sent
event is received when the message is sent to the end-user.
conversation
object description
Key | Description | Example |
---|---|---|
id | Unique ID for a conversation. | 532b57b5f6e63595ccd74c6010e5c5c7 |
expiresAt | Conversation expiration timestamp in seconds | 1518780636 |
type | The type of conversation. Possible values: - FEP (Free entry point) - UIC (User-initiated conversation) - BIC (Business-initiated conversation) | UIC |
pricing
object description
Key | Description | Example |
---|---|---|
policy | The pricing policy applied for this message. Possible values: - CBP (Conversation based pricing) - NBP (Notification based pricing) | CBP |
category | The pricing category. Possible values: - FEP - UIC - BIC | UIC |
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
The delete
event is received when a user deletes a message 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.
Key | Description | Example |
---|---|---|
wa_id | WhatsApp ID of the destination number | 5593587654321 |
phone | Dialable number/given destination number | 553587654321 |
Updated 12 months ago
In the next chapter of this guide, you'll learn about inbound events type: Billing events