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


What’s Next

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

Did this page help you?