Message Status Notifications

Message status notifications provided information about the state of your messages.

This document covers:

For more general Webhook information, see:

Message Status Notification

The WhatsApp Business API client will send notifications to inform you of the status of the messages between you and users. When a message is sent successfully, you will receive a notification when the message is 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:

  • sent — Message sent by your business was received by the server. To receive notifications for sent messages, set the sent_status setting to true in the application settings. Sent status notification is off by default.
  • delivered — Message sent by your business was delivered to the user's device.
  • read — Message sent by your business was read by the user. Read notifications will only be available for those users that have read receipts enabled. For users that do not have it enabled, you will only receive the delivered notification.
  • failed — Message sent by your business failed to send. Reason for failure will be included in the callback; also see Error Messages doc for further description of the failure.
  • deleted — Beginning with v2.21.3, message the user sent to your business was deleted by the user.

Upon receiving a "status": "deleted" notification, you should, in good faith, ensure that the message is deleted from your system if it was downloaded from the server.

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

In the following examples, the recipient_id may instead be a group_id field. It depends on whether the message is sent to an individual or to a group.

Example: Message Sent

{
  "statuses":[{
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "recipient_id": "16315555555",
    "status": "sent",
    "timestamp": "1518694700"
  }]
}

Example: Message Delivered

{
  "statuses":[{
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "recipient_id": "16315555555",
    "status": "delivered",
    "timestamp": "1518694708"
  }]
}

Example: Message Read

{
  "statuses":[{
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "recipient_id": "16315555555",
    "status": "read",
    "timestamp": "1518694722"
  }]
}

Example: Message Failed

{
  "statuses": [{
    "errors": [{
      "code": 470,
      "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." 
    }],
    "id": "gBGGEgZHMlEfAgkM1RBkhDRr7t8",
    "recipient_id": "12064001000",
    "status": "failed",
    "timestamp": "1533332775"
  }]
}

Example: Message Deleted

{
  "statuses": [{
        "id": "ABGGFmkiWVVPAgo66iFiii_-TG0-",
        "recipient_id": "16692259554",
        "status": "deleted",
        "timestamp": "1532413514"
    }]
}
      

Message Status Notification Parameters

When you send a message to a user and have your Webhook configured, you will receive status updates letting you know when the message is sent, delivered, and when it was read by the user. These are the fields that comprise the status messages.

NameDescriptionType

statuses

Statuses Object

Array of any type of status message

The statuses object

The statuses object will keep you apprised of the status of messages between you and users or groups.

NameDescriptionType

id

Message ID

String

recipient_id

WhatsApp ID of recipient

String

status

Status of message: read, delivered, sent, failed, or deleted. See the All Possible Message Statuses table for more information.

String

timestamp

Timestamp of the status message

String

All Possible Message Statuses

This table lists all possible options for the status of a message.

StatusDescriptionWhatsApp Mobile Equivalent

sent

Message received by WhatsApp server

One checkmark

delivered

Message delivered to recipient

Two checkmarks

read

Message read by recipient

Two blue checkmarks

failed

Message failed to send

Red error triangle

deleted

Beginning with v2.21.3, message deleted by the user

Message is replaced in WhatsApp mobile with a note 'This message was deleted'