Receive message status reports via HTTP URL - Chat App Message Service

You can specify an HTTP URL to receive message receipt status reports from the Chat App Message Service.

Protocol

Parameter	Description
Protocol	HTTP + JSON
Encoding	UTF-8

Prerequisites

You have registered an Alibaba Cloud account and created an AccessKey pair. For more information, see Create an AccessKey pair.
You have reviewed the overview and configuration of message receipts and understand their modes, types, and configuration process. Then, configure the message receipts accordingly.

Note

To configure delivery receipts for mobile-terminated (MT) messages, see Configure delivery receipts and mobile-originated messages.

Request

A single push request may contain multiple status reports.

Request example where MsgFrameType is template:

[
    {    
    "Status":"Failed",
    "ErrorDescription":"131026:Receiver is incapable of receiving this message(Message Undeliverable.)",
    "MsgFrameType":"template",
    "TaskId":"202307030171*******9",
    "From":"86131*******8",
    "Timestamp":1691043638000,
    "OriginPhoneNumber":"86130*******8",
    "TemplateCode":"820561547132813184",
    "Type":"TEMPLATE",
    "Language":"id",
    "TemplateName":"wa_otp_v_0_0_3",
    "To":"86138*******8",
    "ErrorCode":"131026",
    "MessageId":"2023078469463703*******3"
    },
    {    
    "Status":"Failed",
    "ErrorDescription":"131026:Receiver is incapable of receiving this message(Message Undeliverable.)",
    "MsgFrameType":"template",
    "TaskId":"202307030171*******9",
    "From":"86131*******8",
    "Timestamp":1691043638000,
    "OriginPhoneNumber":"86130*******8",
    "TemplateCode":"820561547132813184",
    "Type":"TEMPLATE",
    "Language":"id",
    "TemplateName":"wa_otp_v_0_0_3",
    "To":"86137*******8",
    "ErrorCode":"131026",
    "MessageId":"2023078469463703*******3"
    }
]

Request example where MsgFrameType is message:

[
    {    
    "Status":"Read",
    "MsgFrameType":"message",
    "Type":"INTERACTIVE",
    "TaskId":"2023068473353098*******8",
    "From":"86131*******8",
    "To":"86138*******8",
    "Timestamp":1691132091000,
    "OriginPhoneNumber":"86131*******8",
    "MessageId":"2023038470553398*******8",
    "ConversationId":"72222201111****",
    "ConversationType": "service"
    },
    {    
    "Status":"Read",
    "MsgFrameType":"message",
    "Type":"INTERACTIVE",
    "TaskId":"2023068473353098*******8",
    "From":"86131*******8",
    "To":"86138*******1",
    "Timestamp":1691132091000,
    "OriginPhoneNumber":"86131*******8",
    "MessageId":"2023038470553398*******8",
    "ConversationId":"72222201111****",
    "ConversationType": "service"
    }
]

Field descriptions

Parameter	Type	Required	Description
MessageId	String	Yes	The unique ID of the message.
From	String	Yes	The sender's phone number.
To	String	Yes	The recipient's phone number.
Timestamp	Long	Yes	The Unix timestamp in milliseconds.
Status	String	Yes	The delivery status of the message. Valid values: Sent: The message has been sent. Delivered: The message has been delivered to the recipient's device. Read: The message has been read by the recipient. Failed: Message delivery failed. Deleted: The message has been deleted by the recipient. Note The `Deleted` status is currently unavailable. WhatsApp does not push this status to the ChatApp messaging service. `unsubscribe`: The user has blocked the business account. `subscribe`: The user has unblocked the business account. Note The `unsubscribe` and `subscribe` statuses apply only to the Viber channel.
StatusDescription	String	Yes	The description of the status.
ErrorCode	String	No	The error code.
ErrorDescription	String	No	The description of the error code. For details, see API error codes.
ConversationType	String	No	The conversation type. Valid values: service: A user-initiated conversation. utility: A transactional message. marketing: A marketing message. authentication: An authentication message.
ConversationId	String	No	The conversation ID.
ConversationExpirationTime (deprecated)	Long	No	The expiration time of the conversation. Note This parameter has no effect under the new per-message billing model.
MsgFrameType	String	Yes	The message type. Valid values: message: A free-form message. You can send this type of message only within 24 hours of receiving a message from a user. template: A pre-approved message template from the console. You can send this type of message at any time.
Type	String	No	The media type of the message content. Valid values: image: Image video: Video document: Document audio: Audio none: Plain text
TaskId	String	No	The custom task ID. Note If `TaskId` is not specified, it defaults to the value of `MessageId`.
OriginPhoneNumber	String	No	The sender's original phone number.
TemplateCode	String	No	The code of the message template. Note This parameter is returned only when `MsgFrameType` is set to `template`.

Response

After receiving a callback, your endpoint must respond with an HTTP 200 status code within 3 seconds. The response body must match the format shown below. If the response is delayed, malformed, or returns a non-200 status code, the callback is considered a failure, and the service triggers a retry.

Response example

{
  "code" : 0,
  "msg" : "Success"
}

Parameters

Parameter	Type	Required	Description
code	Number	Yes	The response code.
msg	String	No	A descriptive message.

Retry policy

If an initial push to your endpoint fails, the service retries the push. The service attempts the first retry 1 minute after the initial failure. If that attempt also fails, the service attempts a final retry 5 minutes later. If the push still fails after three total attempts, the service makes no further retries for that report.