Status and Pricing Notifications

The WhatsApp Business API client sends notifications about the status of the message between you and your users. These notifications are sent via the statuses object.

Starting February 1st 2022, WhatsApp will switch from a notification-based pricing model to a conversation-based pricing model. On that date, the statuses object will start including information about conversation and pricing.

Status Updates

For each message, you receive a notification when the message is sent, delivered, read, and/or deleted. If the message fails to send or isn’t delivered, you get a failed status notification.

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.

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.

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.

Pricing Updates

Starting February 1, 2022, the statuses object in your outbound notifications will include two new nested objects: conversation and pricing. The conversation and pricing object components will vary depending on where the conversation initiated. Conversations can be user-initiated, business-initiated, or they can start from a free entry point.

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",
    "type": "message"
  }]
}

Starting February 1, 2022 , the example above will include two new objects: conversation and pricing.

The following webhook will be received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):

{
   "statuses": [{
     "id": "3A0C810BBE72C289F9CD",
     "recipient_id": 16315551234,
     "status": "sent",
     "timestamp": 1518694236,
     "type": "message",
     "conversation": {
       "id": "conversation-ID",
       "expiration_timestamp": 1518780636,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

The following webhook will be received when a business sends a message as part of a business-initiated conversation:

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 16315551234,
    "status": "sent",
    "timestamp": 1518694236,
    "type": "message",
    "conversation": {
      "id": "532b57b5f6e63595ccd74c6010e5c5c7",
      "expiration_timestamp": 1518780636,
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
   }]
}

The following webhook will be received when a business sends a message in reply to a user-initiated conversation originating from free entry points:

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 16315551234,
    "status": "sent",
    "timestamp": 1518694236,
    "type": "message",
    "conversation": {
      "id": "532b57b5f6e63595ccd74c6010e5c5c7",
      "expiration_timestamp": 1518780636,
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
   }]
}

Status: Message Delivered

Standard callback for a message delivered:

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

Starting February 1, 2022 , the example above will include two new objects: conversation and pricing.

The following webhook will be received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point):

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 16315551234,
    "status": "delivered",
    "timestamp": 1518694236,
    "type": "message",
    "conversation": {
      "id": "532b57b5f6e63595ccd74c6010e5c5c7",
      "origin": {
         "type": "user_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
  }]
}

The following webhook will be received when a business’ message is delivered and that message is part of a business-initiated conversation:

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 16315551234,
    "status": "delivered",
    "timestamp": 1518694236,
    "type": "message",
    "conversation": {
      "id": "532b57b5f6e63595ccd74c6010e5c5c7",
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
  }]
}

The following webhook will be received when a business’ message is delivered and that message is part of a user-initiated conversation originating from a free entry point:

{
  "statuses": [{
    "id": "3A0C810BBE72C289F9CD",
    "recipient_id": 16315551234,
    "status": "delivered",
    "timestamp": 1518694236,
    "type": "message",
    "conversation": {
      "id": "532b57b5f6e63595ccd74c6010e5c5c7",
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
  }]
}

Status: Message Read

Standard callback for a message read:

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

The example above will not change when Conversation-Based Pricing launches. See our FAQs for more information on edge cases.

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

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",
        "type": "message"
    }]
}
      

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

FAQs

Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:

ScenarioWhen it Happens
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information).This is the most common scenario.
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. Common when a customer has turned off the feature that lets people know they have read a message.
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. Only triggered when the user is already reading the thread with the business when the message comes in.

No, you will continue to be able to use the webhooks provided for the Mexico test until February 1, 2022. Starting February 1, 2022 the new schema for conversation webhooks will go live.