Receive message receipts for MT messages by specifying an HTTP URL - Chat App Message Service

Specify an HTTP URL to receive delivery receipts (ChatAppStatus) for Mobile Terminated (MT) messages.

Protocol specification

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.

Request format

The service sends status updates to your callback URL via HTTP POST requests. A single request can contain a JSON array with one or more status report objects.

Example request when 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"
    }
]

Example request when 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 description

Parameter	Type	Required	Description
MessageId	String	Yes	The unique identifier 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 when the message was sent, in milliseconds.
Status	String	Yes	The delivery status of the message. Valid values: Sent: The message was sent. Delivered: The message was delivered to the recipient's device. Read: The message was read by the recipient. Failed: Message delivery failed. Deleted: The message was deleted. Note The `Deleted` status is unavailable. WhatsApp does not push this status to Chat App Message Service.
StatusDescription	String	Yes	The description of the status.
ErrorCode	String	No	The error code for a delivery failure.
ErrorDescription	String	No	The description of the error code. For details, see Error codes.
ConversationType	String	No	The type of conversation. Valid values: service: A user-initiated conversation. utility: A transactional message. marketing: A marketing message. authentication: An authentication message.
ConversationId	String	No	The unique identifier of the conversation.
ConversationExpirationTime (deprecated)	Long	No	The time when the conversation expires. Note This field is deprecated and 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 the last message from the 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 video document 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 original phone number of the sender.
TemplateCode	String	No	The code of the message template. Note This field is available only when `MsgFrameType` is `template` .

Response format

To acknowledge the receipt of a callback, your endpoint must return an HTTP 200 status code in 3 seconds. The response body must be a JSON object in the following format. Otherwise, the system considers the notification a failure and retries the push.

Response example

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

Field description

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

Retry policy

If an initial push attempt fails, the service retries the request after 1 minute and again after 5 minutes. An attempt fails if your endpoint returns a non-200 HTTP status code or if the request times out. After three failed attempts, the service stops retrying.