International/Hong Kong, Macao, and Taiwan SMS - Status reports and configuration-Short Message Service(SMS)-阿里云帮助中心

After you send SMS messages with an API, you can receive status reports by configuring either the Message Service (MNS) consumer mode or the HTTP batch push mode. These reports help you track delivery success rates and support other business requirements.

Important

Network exceptions or response timeouts may cause issues such as duplicate status reports or prevent you from receiving them.
Due to system caching, status reports are not pushed immediately after you enable the feature. Wait at least 3 minutes for the setting to take effect.
Status reports do not guarantee idempotence. You must handle idempotence in your application to ensure data correctness and consistency when processing reports.

Status report modes

Short Message Service provides two modes for receiving status reports: Message Service (MNS) consumer mode and HTTP batch push mode. You can choose the mode that best suits your business needs.

Message Service (MNS) consumer mode

The Message Service (MNS) consumer mode lets you receive status reports from a message queue in a specific region. All business messages from Alibaba Cloud Communication support outbound delivery through Message Service (MNS). When you subscribe to a specific message type (MessageType) in the Short Message Service console, the system automatically creates a dedicated message queue with a unique queue name (QueueName). You can then use this QueueName and MessageType with the SDK to pull SMS status reports from the queue.
HTTP batch push mode

The HTTP batch push mode pushes messages to a specified URL using an HTTP POST request. After you configure a callback URL (callback_url) in the Short Message Service console, the system sends an HTTP POST request containing the SMS status report to your URL as soon as the report is generated. Your application then receives the report directly.

Status report types

After you select a receiving mode, you must also choose the message type for the reports you want to receive. The following message type is available.

Parameter	Description	MNS consumer	HTTP batch push
SmsReport (SMS status report for outbound messages)	Outbound messages are SMS messages that you send to your users, such as notifications and business alerts. By subscribing to `SmsReport`, you can track the delivery status of each message and determine if it reached the recipient's device.	SmsReport - Message Service (MNS) consumer mode	SmsReport - HTTP batch push mode

Configure status report mode

To receive status reports, you must first enable the feature in the Short Message Service console. Follow these steps to configure SMS status reports for outbound messages.

Log on to the Short Message Service console.
In the left-side navigation pane, choose System Settings > General Settings.
On the General Settings page, click the API tab.
In the Alibaba Cloud Communication Message Receipt section, enable your preferred mode.
MNS consumer mode

Turn on the Message Service (MNS) consumer mode toggle.

After you enable this mode, the queue name appears on the page. The format is Alicom-Queue-{Account ID}-SmsReport. To receive messages from the queue, download the Message Service SDK and implement the consumer code. For more information, see the API documentation.
HTTP batch push mode
1. Turn on the HTTP batch push mode toggle.
2. Enter your callback URL. Example: http://push.example.com/contextpath/receive.do.
3. Click Save.
Your endpoint must respond with the following JSON body: {"code": 0, "msg": "success"}.

MNS consumer mode parameters

Parameter	Type	Required	Example	Description
MessageType	String	Yes	SmsReport	The message type. Set this to `SmsReport`.
QueueName	String	Yes	Alicom-Queue-*****-SmsReport	The name of the message queue. To find the queue name, log on to the Short Message Service console and navigate to System Settings > General Settings > API.