On-Premises API

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.

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.

NameDescription

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:

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

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