Receiving Message Statuses

Last updated: 25 April 2022

This article describes a callback method for sending information about changes in message processing and delivery status.

info

A callback is a request for information about message status changes that we send to your server. The request parameters are passed in the request body.

Connection URL

warning

Only the HTTPS protocol is supported.

To retrieve message callback statuses, during registration, you should specify your system’s API endpoint that will process incoming POST requests from API edna.

Example of the body of an incoming POST request

{
    "requestId": "test-00135",
    "messageId": 8681748,
    "cascadeId": 11,
    "cascadeStageUUID": "001-test001",
    "subject": "test_subject",
    "subjectId": 2,
    "status": "DELIVERED",
    "statusAt": "2025-01-30T11:07:55Z",
    "error": null,
    "comment": null,
    "paymentData": {
        "@type": "WhatsAppConversationPaymentData",
        "conversationId": "test0001",
        "conversationType": "marketing",
        "chargeable": true,
        "type": "WHATSAPP_CONVERSATION"
    }
}

Request Format

Parameter	Data type	Character	Description
requestId	string	Required	The ID of the request based on which the message is generated and sent.
cascadeId	long	Required	The cascade ID.
cascadeStageUUID	string	Required	null or data.
subject	string	Required	The signature name.
subjectId	long	Required	The signature ID. You can find out through the channel list method. Receiving List of Channels
status	string	Required	The message status.
`statusAt'	string	Required	The time of the last update of the message status. Specified in the ISO 8601 format. For example: `2023-10-31T11:07:56Z'. ISO 8601 - Convention
error	string	Optional	null or data. Error in message delivery.
comment	string	Optional	The text comment. Specified when sending the message. The parameter value is also displayed in the detailed report. It can be used for routing chatbots.
paymentData	object	Required	The set of parameters for the WhatsApp channel that transmit information about the dialog.
conversationId	string	Required	The dialog ID. Transmitted for the WhatsApp channel.
conversationType	string	Required	The dialog category. Transmitted for the WhatsApp channel.
chargeable	boolean	Optional	The dialog type: paid or free. It is transmitted for the WhatsApp channel for the DELIVERED and READ statuses.
messageId	integer	Required	The internal ID of the message.

Response Format

In response to a request from your server, the status of its execution with the code 200 should be returned.

If the code 200 does not arrive in response to the callback request, edna Pulse performs 10 more request attempts with an interval of 2 seconds between attempts (where X is the attempt number) until the code 200 arrives in response.

info

That is, every 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048 seconds.

Delivery statuses

Status	Description
SENT	The message has been sent to the recipient.
DELIVERED	The message has been delivered to the recipient.
READ	The message has been read by the recipient.
UNDELIVERED	The message was sent, but not delivered to the recipient.
CANCELLED	Sending the message has been canceled.
EXPIRED	The message did not receive the DELIVERED status because: - the time specified when configuring the cascade has expired; - the time for message delivery (TTL), determined by the default channel, has expired Message Delivery Time (TTL)
FAILED	Error processing the message.

info

When integrating, keep in mind that the list of statuses can be expanded.

Notification example

{
    "requestId": "test-00136",
    "messageId": 8681749,
    "cascadeId": 11,
    "cascadeStageUUID": "001-test001",
    "subject": "test_subject",
    "subjectId": 2,
    "status": "READ",
    "statusAt": "2025-01-30T11:07:57Z",
    "error": null,
    "comment": null
    }
} 

Errors when Receiving Message Statuses

Error	Description
not-WhatsApp-user	The specified recipient is not registered in WhatsApp.
no-template-match	The message does not match a valid template.
session-not-started	The message is not sent within the 24-hour dialog and does not match a valid template.
daily-rate-limit	WhatsApp's daily limit for sending template messages has been exceeded. Only for WhatsApp channel.
too-long-message	The message length exceeds the allowed limit.
chat-window-closed	Error opening the dialog box on the WhatsApp side.
media-request-failed	File upload error.
error-subject-unknown	The specified signature is not allowed to the client. All signatures must be activated beforehand.
error-address-format	Incorrect subscriber number format.
duplicated	Attempt to send a duplicate message within 5 minutes.
message-undeliverable	The message could not be delivered to the recipient. Possible reasons: -The recipient's phone number is not in WhatsApp. - The recipient has not accepted the new versions of the WhatsApp user agreement and privacy policy. - The recipient uses an old version of WhatsApp. Use WhatsApp version 2.21.15.15 (Android) or 2.21.170.4 (iOS) and higher. - Sending authorization messages to recipients with the code +91 (India) is not available. developers.facebook.com
spam-rate-limit-hit	The message could not be delivered to the recipient because many previous messages were blocked or marked as spam.
marketing-template-undeliverable	The message could not be delivered to the recipient. The delivery limit for marketing messages has been reached for the recipient. Try to send a message later. developers.facebook.com