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

Protocol

Item	Description
Protocol	HTTP + JSON
Encoding	UTF-8

Prerequisites

You have an Alibaba Cloud account and an AccessKey pair. For more information, see Create an AccessKey.
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

For the procedure of configuring MO messages, see Message receipts and configuration.

Request format

A single push may contain multiple status reports.

Request example 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"
    }
]

Request example 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	Unique message identifier.
From	String	Yes	Sender's phone number.
To	String	Yes	Recipient's phone number.
FromUserId	String	No	BSUID
FromParentUserId	String	No	Parent BSUID (if any)
FromUserName	String	No	User account (if any)
Timestamp	Long	Yes	Unix timestamp when the message was sent, in milliseconds.
Status	String	Yes	Message delivery status. Valid values: Sent: Message sent. Delivered: Message delivered to the recipient's device. Read: Message read by the recipient. Failed: Message delivery failed. Deleted: Message deleted. Note Unavailable. WhatsApp does not push the `Deleted` status to Chat App Message Service. unsubscribe: The user has blocked the business account. subscribe: The user has unblocked the business account. Note Applies to Viber channels only.
StatusDescription	String	Yes	Status description.
ErrorCode	String	No	Error code for delivery failure.
ErrorDescription	String	No	The description of the error code. For details, see API error codes.
ConversationType	String	No	Conversation type. Valid values: service: User-initiated conversation. utility: Transactional message. marketing: Marketing message. authentication: Authentication message.
ConversationId	String	No	Unique conversation identifier.
ConversationExpirationTime (deprecated)	Long	No	Conversation expiration time. Note Deprecated. Has no effect under the per-message billing model.
MsgFrameType	String	Yes	Message type. Valid values: message: Free-form message. Can only be sent within 24 hours of the user's last message. template: Pre-approved message template from the console. Can be sent at any time.
Type	String	No	Media type of the message content. Valid values: image video document audio none: Plain text
TaskId	String	No	Custom task ID. Note Defaults to `MessageId` if `TaskId` is not specified.
OriginPhoneNumber	String	No	Original sender phone number.
TemplateCode	String	No	Message template code. Note Available only when `MsgFrameType` is `template` .

Response format

After you receive a status report, your endpoint must meet the following requirements:

Respond within 3 seconds.
Return HTTP status code 200.
Return the response body in the following format.

If the response does not meet these requirements, the push fails and the service retries. For details, see Retry policy.

Response example

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

Field description

Name	Type	Required	Description
code	Number	Yes	The response code.
msg	String	No	The description.

Retry policy

If your endpoint does not respond within 3 seconds, does not return HTTP status code 200, or does not return the response body in the required format, the push fails. The service pushes the status report again after 1 minute and then after 5 minutes. In total, the service makes up to three push attempts: the initial push and two retries. If all three attempts fail, the service stops retrying.