V2 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

Key	Description	Example
`id`	This 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`
`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`	Timestamp sent by Meta. This property is received for events `sent`, `delivered`, and `read`.	1585344475
`timestamp`	The time when Gupshup generated the event.	1580546677791

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

{
  "messages": [
    {
      "referral": {
        "source_url": "https://fb.me/3tkSI06bP",
        "source_id": "6570618339781",
        "source_type": "ad",
        "body": "WhatsApp Messenger: More than 2 billion people in over 180 countries use WhatsApp to stay in touch with friends and family, anytime and anywhere. WhatsApp is free and offers simple, secure, reliable messaging and calling, available on phones all over the world.",
        "headline": "Chat with us",
        "media_type": "image",
        "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/355945306_6362276590981_9061280892424810783_n.jpg?stp=c3.122.300.300a_dst-jpg_p306x306&_nc_cat=103&ccb=1-7&_nc_sid=567a6d&_nc_ohc=pYcuA_DcMeUAb4eCSRW&_nc_ad=z-m&_nc_cid=0&_nc_ht=scontent.xx&oh=00_AfAqx_EFyDb1elHBHbjofACWwoxSytEJt2Aeu5vEyWOdQA&oe=66147417",
        "ctwa_clid": "ARAHuTtGzmFlOO_WcXezfYBRzrxoH2Emo4kj-mXVvHoMQVU748gp6Sp-IKS2_scLmfnBJSWvvsZpVqjJfMQPM6TJy1_dNFC1ZUztlDk4i1RijetS"
      },
      "from": "918871601297",
      "id": "wamid.HBgMOTE4ODcxNjAxMjk3FQIAEhgUM0FEOUJDNjc1NDJGMUNEMUNFMDEA",
      "timestamp": "1712229906",
      "text": {
        "body": "Hello! Can I get more info on this?"
      },
      "type": "text"
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "Niiiishh"
      },
      "wa_id": "918871601297"
    }
  ]
}

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

Sync 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 Exist On WhatsApp
`id`	id is Gupshup Message ID	ee4a68a0-1203-4c85-8dc3-49d0b3226a35

Async Failed

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

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
`gsId`	gsId is Gupshup Message ID	72f61f22-5aa4-4615-a970-943edf6da01c

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) - Marketing - Authentication - Utility -Service	Marketing

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

Key	Description	Example
`wa_id`	WhatsApp ID of the destination number	5593587654321
`phone`	Dialable number/given destination number	553587654321

Referral (CTX)

Key	Description	Example
source_url	The Meta URL that leads to the ad or post clicked by the customer. Accessing this URL displays the ad viewed by the customer.	`"https://www.meta.com/ad/12345"`
source_type	Specifies the type of source for the ad; it can either be an `ad` or a `post`.	`"ad"`
source_id	The Meta ID for the ad or post.	`"1234567890"`
headline	The headline used in the ad or post.	`"Get 20% off on your first order!"`
body	The body text for the ad or post.	`"Shop now and save on your favorite items."`
media_type	Specifies the type of media present in the ad or post. Possible values are `image` or `video`.	`"image"`
image_url	The URL of the image used in the ad, applicable when `media_type` is `image`.	`"https://www.meta.com/ad/12345/image.jpg"`
video_url	The URL of the video used in the ad, applicable when `media_type` is `video`.	`"https://www.meta.com/ad/12345/video.mp4"`
thumbnail_url	The URL of the thumbnail for the video, applicable when `media_type` is `video`.	`"https://www.meta.com/ad/12345/thumbnail.jpg"`
ctwa_clid	The Click ID generated by Meta for ads that redirect to WhatsApp.	`"abc123xyz456"`

Supported Message Types

The referral object can be included in the following types of messages:

text, location, contact, image, video, document, voice, and sticker.

MM Lite Messaging Events (DLR)

The DLR event for MM Lite will have a similar payload to the existing non MM Lite DLR payload, except that the pricing category and conversation type will be "marketing_lite".

Below is an example of MM Lite event

{
    "app": "AbdDef",
    "timestamp": 1729588576346,
    "version": 2,
    "type": "message-event",
    "payload": {
        "id": "wamid.HBgMOTE5OTg3OTkzMjc0FQIAERgSMTBEQjFDNkQzMUVBRjExRDI1AA==",
        "type": "sent",
        "destination": "919987993274",
        "payload": {
            "ts": 1729588575
        },
        "conversation": {
            "id": "b463ee712d95412611865832987e7a26",
            "expiresAt": 1729599000,
            "type": "marketing_lite"
        },
        "pricing": {
            "policy": "CBP",
            "category": "marketing_lite"
        }
    }
}