Receipt message modes, types, and configuration-Voice Service(VS)-阿里云帮助中心

This document describes the receipt message feature of Alibaba Cloud Voice Service and its configuration. After making outbound calls with Voice Service APIs, you can receive receipt messages through either the Simple Message Queue (formerly MNS) consumer mode or the HTTP batch push mode.

Note

Network exceptions or response timeouts may result in duplicate receipt messages.
The response timeout for the HTTP batch push mode is 700 ms.
Receipt messages do not guarantee idempotence. If your downstream logic requires idempotence, you must implement an idempotency strategy based on your business scenario.

1. Receipt message modes

You can receive receipt messages in either Simple Message Queue (formerly MNS) consumer mode or HTTP batch push mode. Choose the mode that best suits your needs.

1.1 Simple Message Queue (formerly MNS) consumer mode

Overview

In Simple Message Queue (formerly MNS) consumer mode, you receive receipt messages through the Simple Message Queue (formerly MNS) queue model. All business messages from Alibaba Cloud Communications support delivery through Simple Message Queue (formerly MNS).

How it works

When you subscribe to a specific MessageType in the Voice Service console for delivery via Simple Message Queue (formerly MNS), the system automatically creates a dedicated message queue for that type and generates a queue name (QueueName).
You can use the queue name (QueueName) and MessageType, along with your Alibaba Cloud AccessKey information, to obtain a temporary token and pull messages from the queue.

Use cases

You need a reliable message reception mechanism.
You need message persistence.
You need to pull messages on demand.
Your application handles a high volume of traffic and requires a queue to buffer messages.

Note

To pull messages from Simple Message Queue (formerly MNS) by using an SDK, see the Simple Message Queue (formerly MNS) consumer demo.

1.2 HTTP batch push mode

Overview

The HTTP batch push mode pushes messages to a specified web URL using HTTP POST requests. After you configure a callback URL in the Voice Service console, the system automatically pushes business messages to this URL as they are generated. Your application can then receive them directly.

How it works

Configure an HTTP callback URL in the Voice Service console.
When the system generates a business message, it automatically pushes the message to the specified URL using an HTTP POST request.
Your server receives and processes the receipt message.

Use cases

You need to receive messages in real time.
Your server can receive HTTP requests.
Your application handles a moderate volume of traffic and can process pushed messages promptly.
You want a simplified message-receiving process.

Note

The response timeout for the HTTP batch push mode is 700 ms.
Network exceptions or response timeouts may result in duplicate receipt messages.
Before configuring the HTTP batch push mode, ensure you understand the HTTP request handling requirements and the push mechanism. For more information, see HTTP batch push mode.

1.3 Mode comparison

Feature	Simple Message Queue (formerly MNS)	HTTP batch push
Message delivery method	pull	push
Message persistence	Supported. Messages are stored in a queue.	Not supported. You must store messages yourself.
Reliability	High. Messages are not lost.	Medium. Depends on network stability.
Real-time delivery	On-demand pull. You can control the polling frequency.	Real-time push
Use cases	High traffic volumes that require buffering	Low to medium traffic volumes that require real-time processing
Configuration complexity	Medium. Requires queue configuration.	Simple. Only requires URL configuration.
Response timeout	No limit	700 ms

2. Receipt message types

Voice Service provides the following receipt message types (MessageType). You can subscribe to the types you need based on your business requirements.

2.1 Message type list

MessageType	Name	Description
VoiceReport	Call record message	Provides call record information after a call ends, including the call type, start and end times, duration, and hang-up reason.
VoiceCallReport	In-call status message	Provides information about call status events during a call, such as call started, ringing, answered, hung up, and the time each event occurred.
VoiceRecordReport	Call recording message	Provides the call recording information after a call ends.

2.2 Data structures for receipt messages

For details on the data structures for each Voice Service feature, see the following topics:

3. Configure receipt message mode

To receive receipt messages, you must first enable message reception in the console. The following steps show how to configure call record messages as an example.

Log on to the Voice Service console.
In the left-side navigation pane, choose General Settings > > Subscribe to Receipt Messages.
Find the message type that you want to subscribe to and enable your desired mode.

Simple Message Queue (formerly MNS)

Enable Simple Message Queue (formerly MNS) consumer mode. For notes and sample code on receiving receipt messages, see the Simple Message Queue (formerly MNS) consumer demo.

This setting is located in the Call Record Message Reception area. In addition to MNS Queue Consumer Mode, this area also supports the HTTP batch push mode (you do not need to pass the callback_url parameter in every API request; the system will send a POST request to the configured URL).

HTTP batch push

Before configuring the HTTP batch push mode, ensure you understand the HTTP request handling requirements and the push mechanism. For more information, see HTTP batch push mode.

Enable the HTTP batch push mode.

After enabling the mode, enter your endpoint URL in the Receiving URL field. When you save the URL, your server must return the JSON response {"code": 0, "msg": "Success"}. After the URL is saved successfully, you no longer need to pass the callback_url parameter in each request because the system sends POST requests to this URL.
Enter the receiving URL and click Save.

Example URL: http://push.example.com/contextpath/receive.do
Click OK.

After the configuration is complete, you can click Test to verify whether your URL can receive a test receipt message.

4. FAQ

I configured HTTP batch push mode, but I'm not receiving receipt messages after a successful call. What should I do?

Troubleshoot in the following order:

Verify that you subscribed to the correct message type: To receive call record receipt messages for Voice Notification and other voice services, subscribe to Call Record Message Reception (message type: VoiceReport). If you subscribed to Cloud Communications Call Record Message Reception, note that this option does not support Voice Service receipt messages. Change your subscription to Call Record Message Reception.
Verify that the subscription configuration has taken effect: Make sure the receipt message reception switch is enabled and the receiving URL is saved successfully. When saving the URL, your server must return the JSON response {"code": 0, "msg": "Success"}. You can click Test to verify whether the URL can receive a test receipt message.
Verify that your server responds within the timeout: The response timeout for the HTTP batch push mode is 700 ms. If your server cannot respond within this time, message pushes may fail.

Multiple callback URLs

A single Alibaba Cloud account supports the configuration of only one webhook address for each type of receipt message. To use multiple IP addresses to receive receipt messages, you must use multiple Alibaba Cloud accounts and configure a different IP address for each account. For more information about how to configure receipt messages, see Introduction to receipt messages and configuration process.

Error setting VoiceReport callback URL

This error can occur if the test content is not parsed correctly. The Alibaba Cloud server sends the test content {"json":"test-content"} in JSON format, not JSON array format. When you set the webhook address for testing, you must validate it locally in JSON format. After the test is complete, validate the actual receipt messages in JSON array format.

Duplicate message pushes

Yes, receipt messages do not guarantee idempotence. The system may push duplicate messages under the following conditions:

Network exceptions
Response timeouts (the response timeout for the HTTP batch push mode is 700 ms)
Server-side processing errors

Recommendation: If your downstream logic requires idempotence, you must implement an idempotency strategy based on your business scenario. For example:

Use the message ID as a unique identifier.
Record the IDs of processed messages in a database.
Use a distributed lock to prevent duplicate processing.

Preventing message loss

We recommend the following strategies:

Use the Simple Message Queue (formerly MNS) consumer mode: Messages are stored in a queue and are not lost.
Use the HTTP batch push mode:
- Ensure that your server is stable.
- Implement message persistence.
- Respond to HTTP requests within 700 ms.
- Implement a retry mechanism.

HTTP batch push response timeout

The response timeout for the HTTP batch push mode is 700 ms. If your server fails to respond within this time, the message push may fail or be retried, which can result in duplicate messages.

Recommendations:

Optimize your server-side logic to improve response speed.
Use an asynchronous processing mechanism. Respond to the request immediately, then process the business logic asynchronously.
Consider using the Simple Message Queue (formerly MNS) consumer mode for higher reliability.