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.

Status Updates

For each message your business sends, you will receive a notification about the status of the message. In the table below, click the arrow in the left column for the WhatsApp App equivalent to each status, if available.

NameDescription

deleted

A message send by the user was deleted by the user. Upon receiving this notification, you should ensure that the message is deleted from your system if it was downloaded from the server.

WhatsApp App Equivalent

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

delivered

A message sent by your business was delivered to the user's device.

WhatsApp App Equivalent

Two checkmarks

failed

A message sent by your business failed to send. A reason for the failure will be included in the callback. Check the error message documentation for help debugging:

WhatsApp App Equivalent

Red error triangle

read

A message sent by your business was read by the user. read notifications are only available for users that have read receipts enabled. For users that do not have it enabled, you only receive the delivered notification.

WhatsApp App Equivalent

Two blue checkmarks

sent

A message sent by your business is in transit within our systems.


For On-Premises API users: 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.

WhatsApp App Equivalent

One checkmark

warning

A message your business sent contains an item in a catalog that is not available or does not exist.

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

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

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

The following webhook is 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": "ID",
     "recipient_id": "WHATSAPP_ID",
     "status": "sent",
     "timestamp": "TIMESTAMP",
     "type": "message",
     "message": {         
        "recipient_id":"WHATSAPP_ID"  // This is available on v2.41.1 and above      
     },
     "conversation": {
       "id": "CONVERSATION_ID",
       "expiration_timestamp": TIMESTAMP,
       "origin": {
         "type": "user_initiated"
       }
      },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
   }]
}

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

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",         
    "message": {
        "recipient_id":"WHATSAPP_ID" // This is available on v2.41.1 and above
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
   }]
}

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

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "sent",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID"   // This is available on v2.41.1 and above
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "expiration_timestamp": TIMESTAMP,
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
   }]
}

Status: Message Delivered

The following webhook is 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": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id":"WHATSAPP_ID" // This is available on v2.41.1 and above
      },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "user_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "user_initiated"
    }
  }]
}

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

{
  "statuses": [{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",
    "message": {
        "recipient_id": "WHATSAPP_ID" // This is available on v2.41.1 and above
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "business_initiated"
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": true,
      "category": "business_initiated"
    }
  }]
}

The following webhook is 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": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "delivered",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" // This is available on v2.41.1 and above
    },
    "conversation": {
      "id": "CONVERSATION_ID",
      "origin": {
         "type": "referral_conversion",
      }
    },
    "pricing": {
      "pricing_model": "CBP",
      "billable": false,
      "category": "referral_conversion"
    }
  }]
}

Status: Message Read

Standard callback for a message read:

{
  "statuses":[{
    "id": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "read",
    "timestamp": "TIMESTAMP",
    "type": "message",  
    "message": {
        "recipient_id": "WHATSAPP_ID" // This is available on v2.41.1 and above
    }
  }]
}

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": "ID",
    "recipient_id": "WHATSAPP_ID",
    "status": "failed",
    "timestamp": "TIMESTAMP"
  }]
}

Error code 480

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

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": "ID",
        "recipient_id": "WHATSAPP_ID",
        "status": "deleted",
        "timestamp": "TIMESTAMP",
        "type": "message",
        "message": {
           "recipient_id": "WHATSAPP_ID" // This is available on v2.41.1 and above
      }
    }]
}

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

See Overview, Messages for this information.

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.