Status notifications

Last update: 6 hours ago by Irais Aguirre

Integration summary
Delivery: WhatsApp → Concepto Móvil → POST to your webhook URL (the one you share with our Operations team), with a JSON body.
Format: Meta's value object without metadata or messaging_product (see Webhook).
Identify the user: from/recipient_id or, if missing, the BSUID.
Types on this page: sent, delivered, read, failed and deleted statuses (status values)

Status of the messages you sent. They arrive in the statuses array. For the status of messages sent to a group, see Status of messages sent to a group.

Message statuses

Sent every time the status of a sent message changes: sent, delivered, read, failed, or deleted.

Structure

Fields for Message statuses:

Name	Description	Type	Requirements
id	Internal message ID (the id returned by the send API).	String	Required.
recipient_id	Phone number the message was sent to. Missing if the message was sent to the BSUID and the number isn't available.	String	Conditional
recipient_user_id	The recipient's BSUID. Always included, except in the failed status of a message sent to a phone number.	String	Conditional
recipient_parent_user_id	The recipient's parent BSUID. Only included if the business has linked portfolios.	String	Optional
type	Status type (e.g. "payment").	String	Optional
status	Message status. Possible values: sent: message sent delivered: message delivered read: message read failed: the message could not be sent deleted: the user deleted the message	String	Required.
timestamp	Date and time the status occurred.	String	Required
errors	Array of errors related to the message status (typically for `failed`).	Array of objects	Optional
conversation	Attributes of the current conversation.	Object	Optional. May be omitted from some notifications.
pricing	Billing attributes.	Object

Status notifications don't include the contacts object.

Conversation object

Name	Description	Type	Requirements
id	Conversation ID.	String	Required.
expiration_timestamp	Epoch date and time when the conversation window expires.	String	Optional.
origin	Describes the conversation category. authentication marketing utility service referral_conversion	Object	Required
pricing	Billing attributes may be nested inside `conversation`.	Object	Optional

Origin object

Name	Description	Type	Requirements
type	- authentication: The conversation was opened by a business sending a customer a template categorized as AUTHENTICATION. marketing: The conversation was opened by a business sending a customer a template categorized as MARKETING. utility: The conversation was opened by a business sending a customer a template categorized as UTILITY. service: The conversation was opened by a business replying to a customer within a customer service window. referral_conversion: The conversation came from a free entry point.	String	Required.

Pricing object

Name	Description	Type	Requirements
billable	Whether the message or conversation is billable. The value depends on the pricing_model. CBP: false if the conversation started from a free entry point; true for all other conversations. It is also true for conversations within your free tier limit. NBP: false for service conversations; true for authentication, marketing, and utility conversations.	Boolean	Required
type	Pricing type (e.g. "regular").	String	Optional
cost	Object with the cost of the message. Contains `amount` (Number) and `currency` (String).	Object	Optional
pricing_model	Pricing model in use. Supported values: CBP, NBP and PMP (per-message pricing).	String
category	The conversation's pricing category. Values: business_initiated marketing utility authentication service user_initiated referral_conversion	String

Cost object

Name	Description	Type	Requirements
amount	Amount charged.	Number	Required
currency	Cost currency.	String	Required

Errors object

Name	Description	Type	Requirements
code	Error code. For details, see Error codes.	Number	Required.
title	Error description.	String	Required
href	URL with more details about the error.	String	Optional
details	Additional error details.	String	Optional

Example

Complete Message statuses example:

Successful notification

{
    "statuses": [
        {
            "id": "NTI1NTIwNzc3MDU41qbPgNJ6hLs",
            "status": "delivered",
            "timestamp": "1693419173",
            "recipient_id": "5215520777058",
            "conversation":
            {
                "id": "05b0852529d1652f2ccf3cde096f2150",
                "origin":
                {
                    "type": "service"
                }
            },
            "pricing":
            {
                "billable": true,
                "pricing_model": "CBP",
                "category": "service"
            }
        }
    ]
}

Notification with error code

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

Platform-generated `failed` status

When Meta rejects a send synchronously, the platform generates a failed status with the following shape. In this case recipient_id contains the value of the to field sent in the request (it may be a BSUID), and recipient_user_id, conversation, and pricing are not included.

{
    "statuses": [
        {
            "id": "NTI1NTIwNzc3MDU41qbPgNJ6hLs",
            "recipient_id": "5215520777058",
            "status": "failed",
            "timestamp": "1693419173",
            "errors": [
                {
                    "code": 1005,
                    "title": "Parameter value is not valid",
                    "details": "Message failed. Invalid parameter."
                }
            ]
        }
    ]
}

Message sent to a BSUID

The message was sent to the user's BSUID and their phone number isn't available, so you only receive recipient_user_id.

{
    "statuses": [
        {
            "id": "NTczMTAyMzQ3NTA51wFDy8kOXTM",
            "status": "sent",
            "timestamp": "1504902988",
            "recipient_user_id": "US.13491208655302741918",
            "recipient_parent_user_id": "US.ENT.506847293015824",
            "conversation": {
                "id": "CONVERSATION_ID",
                "expiration_timestamp": "1504903988",
                "origin": {
                    "type": "marketing"
                }
            },
            "pricing": {
                "billable": true,
                "pricing_model": "PMP",
                "type": "regular",
                "category": "marketing"
            }
        }
    ]
}

WhatsApp — Previous

Interactive replies

Next — WhatsApp

User changed phone number