We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

We are making changes to the WhatsApp Business Platform pricing model. See Pricing Updates on the WhatsApp Business Platform.

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 you send, a notification about the status of the message will be sent to your webhook callback. In the table below, click the arrow in the left column for the WhatsApp app equivalent to each status, if available.

Name	Description
`deleted`	A message sent by the customer was deleted by the customer. 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 you was delivered to the customer's device.
WhatsApp App Equivalent	Two checkmarks
`failed`	A message sent by you failed to send. A reason for the failure will be included in the callback. Check the error message documentation for help debugging: On-Premises API Errors Cloud API Error Codes and Troubleshooting
WhatsApp App Equivalent	Red error triangle
`read`	A message sent by you was read by the customer. `read` notifications are only available for customers that have read receipts enabled. For customers that do not have it enabled, you only receive the `delivered` notification.
WhatsApp App Equivalent	Two blue checkmarks
`sent`	A message sent by you 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 you 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 conversation category. 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"   
     },
     "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 user-initiated conversation for a media message (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": {   
       "media_id": "98d14c8e-0310-4061-8f99-2d148274c286",
       "recipient_id":"WHATSAPP_ID"  
     },
     "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" 
    },
    "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"   
    },
    "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" 
      },
    "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" 
    },
    "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" 
    },
    "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" 
    }
  }]
}

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

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

I’m getting a message read webhook alert including pricing information. Is that expected?

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:

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

Permalink