Voice Service sends voice notifications and reads verification codes aloud to specified phone numbers through automated calls. This topic describes how to use API operations to send voice notifications or voice verification codes, including the prerequisites, workflow, and methods for querying call details.
Usage notes
Use text-to-speech (TTS) templates and voice notification files only after they are approved.
For the same combination of qualification information and number purpose, the following throttling limits apply per called number: 1 call per minute, 5 calls per hour, and 20 calls per 24 hours. The 24-hour period starts from the first successful call. Calls that exceed these limits are rejected. If your business scenario requires high-frequency or round-the-clock calling, we recommend using the dedicated mode and applying for a throttling whitelist. For more information, see Throttling rules.
Preparations
Voice Service API and SDK calls are available only for enterprise users. Individual users do not have trial access. Before you make API calls, complete enterprise identity verification and pass the enterprise qualification review as described in the following steps.
Register an Alibaba Cloud account and complete enterprise identity verification. Then, activate Voice Service.
Apply for enterprise qualifications. After you submit your application, Alibaba Cloud reviews and approves it. For more information, see Enterprise Qualification Management.
Apply for a call script template. After you submit your application, Alibaba Cloud reviews and approves it. A call script declares your business scenario. The script content is not used in actual voice calls. For more information, see Add a call script template.
If you use the shared mode for calls (recommended), you do not need to purchase numbers. Alibaba Cloud provides a shared number pool. If you use the dedicated mode, you must apply for real numbers.
Before you call an API operation, review the API overview to understand the operation and find the required request parameters. If an error occurs after you send a request, look up the error message in the API error codes document.
Workflow
The process of sending voice notifications or voice verification codes through API operations consists of three steps:
Step 1: Prepare the call content. Create TTS templates and upload voice notification files.
Step 2: Initiate a voice call. Call the appropriate API operation to send a voice notification or a voice verification code.
Step 3: Query call details. Use the returned call ID or task ID to check the call result.
Step 1: Prepare the call content
Uploading a voice file through an API defaults to dedicated mode. To use shared mode for API-initiated voice calls, apply for call content in the Voice Service console. For more information, see Create a voice template.
Call content includes TTS templates and voice files. You must prepare the call content and wait for it to be approved before you can initiate voice calls. You can apply for content and query the review status in the console.
TTS templates: You cannot create TTS templates by calling an API operation. You must create them in the Voice Service console. For more information, see Create a voice template.
Voice files: You can upload voice files by using an API, an SDK, or the console. For more information about how to upload files by using an API or an SDK, see Upload a voice file using an API.
After you upload a voice file, you can call the QueryVoiceFileAuditInfo operation to query the review status. If the file fails the review, check the failure reason and upload the file again.
Step 2: Initiate a voice call
Based on your business requirements, call the appropriate API operation to send a voice notification or a voice verification code. Review the parameter descriptions for each operation before you make the call.
The following API operations are available:
API operations for shared and dedicated modes | API operations for dedicated mode only |
|
|
After a successful API call, the response includes a CallId. The called number receives an incoming call that plays the specified voice content.
Step 3: Query call details
After you initiate a voice call, use the call ID or task ID returned in Step 2 to query the call details.
The following API operations and methods are available:
API operations for shared and dedicated modes | API operations for dedicated mode only |
|
|
Implement business logic based on call status
After you query the call details by calling the QueryCallDetailByCallId operation, use the returned connection status field to trigger corresponding business logic:
Not connected (the called party did not answer or the call failed): Initiate a callback based on your business requirements.
Connected: Proceed with the subsequent steps in your normal business workflow.
We recommend that you incorporate the connection status check and callback logic into an automated process to reduce manual intervention and improve the reach rate.
FAQ
What do I do if SmartCall returns the "Smart outbound call with full variables is not enabled" error?
If you receive the error "Smart outbound call with full variables is not enabled" when you call the SmartCall API operation, check the following:
Cause: The
VoiceCodeparameter of theSmartCalloperation supports only voice file IDs from the voice file details page in the console. Variable parameters cannot be passed directly in this field.Solution: Remove variable parameters from the
VoiceCodefield and enter only the voice file ID that is displayed on the voice file details page in the console.
What do I do if the Data field is missing from the response or the query result is abnormal?
When you call the SingleCallByTts or voice verification code API operation, check whether the product to which the ProdId (template ID) belongs matches the API operation you are calling:
If the template was created under the voice notification product, you must use voice notification API operations (such as
SingleCallByTts) for calls and queries.If the template was created under the voice verification code product, you must use voice verification code API operations for calls and queries.
Using a template ID from a different product line causes the Data field to be empty or the query to fail. Verify the product to which the template belongs, and then use the corresponding API operations.
What is the maximum ring duration for a SingleCallByTts call?
The ring duration is determined by the network policy of the called party's carrier. The Alibaba Cloud API and SDK do not provide a parameter for customizing the hang-up time. The default ring timeout of carriers in mainland China is typically 45 to 60 seconds.
How do I troubleshoot API errors and obtain sample code?
Common causes of API errors:
The
TtsCodetemplate ID is incorrect. For example, the template belongs to a different API operation, or the template has not been approved.The
QueryDatetimestamp format is incorrect. Use the UTC format with precision to the second.The button parameter variable names do not match the template definition. For example, when you copy the parameters of button 1 to button 2, the corresponding variable names are not updated.
We recommend that you use the OpenAPI Developer Portal to debug API operations online. After you verify that the parameters are configured correctly, download the auto-generated SDK sample project, which supports mainstream languages such as Java, Python, and C#. This helps you avoid parameter errors that may be introduced by manual coding.
References
Online API debugging: Visit the OpenAPI Developer Portal to debug API operations online, view complete request parameters, and generate SDK sample code in your preferred programming language.
Error code query: If an error is returned when you call an API operation, refer to the API error codes document to troubleshoot the issue.
FAQ: