Message Status Notifications

The WhatsApp Business API client sends notifications to inform you of the status of the messages between you and users. When a message is sent successfully, you receive a notification when the message is sent, delivered, and read —See Notification Types. 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.

Notification Types

NameDescription

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. The sent status notification is disabled 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
A reason for the failure will be included in the callback. Also see the Error Messages documentation for further descriptions of the failure.

deleted

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 that a message has been delivered if it has been read. The reason for this behavior is internal optimization.

Status Notification Fields

Your status notifications are sent via the statuses object. Inside statuses, you may find the two following objects nested: conversation and pricing.

Examples

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.

Status: Message Sent

Standard callback for a message sent:

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

Sent message callback example with conversation and pricing information applied. Billable is set to true, indicating the conversations were not initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
    "statuses": [
        {
            "conversation": {
                "id": "5fc5524522b4c9bc0e2018ad810a095a"
            },
            "id": "gBGGEgFVUXl_AgkUBIUqicVXyZY",
            "pricing": {
                "billable": true,
                "pricing_model": "CBP"
            },
            "recipient_id": "12015551797",
            "status": "sent",
            "timestamp": "1609879800"
        }
    ]
}

Sent message callback example with conversation-based pricing applied. Billable is set to false, indicating the conversations were initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 19075550014,
    "status": "sent",
    "timestamp": 1603408535,
    "conversation": {
      "id": “532b57b5f6e63595ccd74c6010e5c5c7”
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false
      }
    }]
}

Status: Message Delivered

Standard callback for a message delivered:

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

Delivered message callback example with conversation-based pricing applied. Billable is set to true, indicating the conversations were not initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
    "statuses": [
        {
            "conversation": {
                "id": "b67b498c788be212a30515d377620739"
            },
            "id": "gBGGEgFVUXl_AgmQ1p4lCm7vdfo",
            "pricing": {
                "billable": true,
                "pricing_model": "CBP"
            },
            "recipient_id": "12015551797",
            "status": "delivered",
            "timestamp": "1610413994"
        }
    ]
}

Delivered message callback example with conversation-based pricing applied. Billable is set to false, indicating the conversations were initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 19075550014,
    "status": "delivered",
    "timestamp": 1603408535,
    "conversation": { 
      "id": "532b57b5f6e63595ccd74c6010e5c5c7"
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false
    }
]}

Status: Message Read

Standard callback for a message read:

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

Delivered message callback example with conversation-based pricing applied. Billable is set to true, indicating the conversations were not initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
    "statuses": [
        {
            "conversation": {
                "id": "e118e912f7b8212088f2ccad1d8f70bf"
            },
            "id": "gBGGFlB5YjhvAgnhuF1qIUvCo7A",
            "pricing": {
                "billable": true,
                "pricing_model": "CBP"
            },
            "recipient_id": "16315555555",
            "status": "read",
            "timestamp": "1610561171"
        }
    ]
}

Delivered message callback example with conversation-based pricing applied. Billable is set to false, indicating the conversations were initiated from Ads that click to WhatsApp or Facebook Page call-to-action.

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 19075550014,
    "status": "read",
    "timestamp": 1603408535,
    "conversation": { 
      "id": "532b57b5f6e63595ccd74c6010e5c5c7"
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false
    }
]}

Status: Message Failed

Error code 470

{
  "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"
  }]
}

Error code 480

{
  "statuses": [{
      "errors": [{
          "code": 480,
          "title": "Failed to send message since we detect an identity change of the contact"
      }],
      "id": "gBGGFjFVU2AfAgldhhKwWDGSrTs",
      "recipient_id": "16315553601",
      "status": "failed",
      "timestamp": "1602535356"
   }]
}

Conversations Exception

For conversation-based pricing users, the conversation subsection is not included in the callback, if a message has failed. No billing or conversation activation is involved in this case.

Status: Message Deleted

Standard callback for a deleted message:

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

Conversations Exception

For conversation-based pricing users, the conversation subsection is not included in the callback, if a message has been deleted. No billing or conversation activation is involved in this case.

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

Message deleted by the user

The message is replaced in WhatsApp mobile with a note reading "This message was deleted."