A voice template defines the audio content that a user hears. Before you can send a voice notification or a voice verification code, you must create a voice template and have it approved.
Usage notes
Currently, you can create text-to-speech templates only in the Voice Service console. You cannot create templates by calling an API.
Your text-to-speech templates must comply with content and variable specifications. For more information, see Rules for voice templates.
Ensure that your resource plan or account balance is sufficient. For billing, see Pricing of Voice Service for Chinese mainland.
After a text-to-speech template is approved, you cannot modify its content. To make changes, create a new text-to-speech template.
End-to-end process
The following diagram shows the complete process, from preparation to sending voice messages using an API, including the estimated time for each step.
Step 1: Prepare your account and qualifications
Activate the service and complete enterprise real-name verification
Make sure that you have an Alibaba Cloud account and have completed enterprise real-name verification.
Visit the Voice Service product page to activate the service.
Ensure that your resource plan or account balance is sufficient. For more information, see Pricing of Voice Service for Chinese mainland.
Apply for business qualifications
Purpose: For compliance, all Voice Service users must submit business qualifications to verify their identity.
Action: Go to the Voice Service console > Business Qualification Management page, submit your business qualifications, and wait for approval. For detailed steps, see Business Qualification Management.
Apply for a script and submit it for approval. A script registers your business scenario with the carrier for compliance purposes, but its content is not used in the actual voice calls. Note that a script does not restrict you to sending a single type of notification — your actual voice content is determined by the voice template you create. When selecting a script category, ensure it matches the business scenario of your templates. For more information, see Add a script.
Step 2: Create a voice template
Log on to the Voice Service console. In the left-side navigation pane, choose Voice Messages.
Based on your business needs, choose Voice Notifications or Voice Verification Codes.
Voice Notifications supports text-to-speech templates and voice notification files.
Text-to-speech template: The template content is text that is automatically converted to speech during playback.
Voice notification file: A pre-recorded audio file (in WAV or MP3 format) that plays directly after the recipient answers the call.
Voice Verification Codes supports only text-to-speech templates.
On the Voice Notifications or Voice Verification Codes page, create a voice template.
Text-to-speech template
Click Add Template and fill in the template information as prompted on the page.
Parameter
Description
Calling Number (Calling Mode)
Text-to-speech templates for public mode and dedicated mode are not interchangeable. The calling mode of a text-to-speech template must match the calling mode of your business scenario. For more information about the differences, see Differences between public mode and dedicated mode.
Public mode call: If you do not purchase a separate voice number, Voice Service makes calls from a random number in its shared number pool. You must select this option to create a text-to-speech template for public mode.
Dedicated mode call: You use a real number purchased in the Voice Service console or bound to a service instance for outbound calls. Select this option to create a text-to-speech template for dedicated mode.
ImportantIf you select Public mode call, you need to select an Associated Qualification.
If no business qualifications are available, first complete Business Qualification Management. After your business qualifications are approved, apply for a script. After the script is approved, create the voice template again.
Template name
The template name identifies and distinguishes your templates. The name can be up to 30 characters long.
Template content
The template content must comply with the Rules for voice templates.
Language
Select the template language.
Chinese
English
Speech rate
Set the speech rate.
Voice type
Select the voice type.
Female
Male
NoteFor English templates, only Female is supported.
Timbre
Select a timbre for the voice. You can select a speech rate and timbre, and then click the Listen icon
to preview the audio output and find the best configuration.Description
The description provides context for the template review. Describe your business scenario in detail and provide information to verify your business, such as website links or app names. A well-written description can speed up the review process.
If your business has no publicly accessible online presence (for example, an internal management system with no public recharge page), include the following in your description:
Business scenario explanation: Describe the actual use case (for example, offline transfers or internal virtual credit management).
Sample text with real variable values: Provide the template content with actual variable values substituted (for example, "Your verification code is 123456, valid for 5 minutes").
Business content screenshot: Attach a screenshot of the internal system page. You can redact sensitive information.
A brief text description alone is generally not sufficient for approval. You must provide verifiable business information — such as a website URL, app name, mini-program name, or official account name.
Click OK. This creates the template and submits it for review.
Voice notification file
Click Import Voice File, select an outbound call number type, and import the voice file for review.
ImportantOutbound call templates for public mode and dedicated mode are not interchangeable. Select the calling mode that suits your business scenario. For more information about the differences, see Differences between public mode and dedicated mode.
The voice file must be in WAV or MP3 format and smaller than 5 MB. After submission, the review is typically completed within 2 hours. Reviews are processed from 9:00 to 23:00 (UTC+8) from Monday to Sunday, excluding public holidays.
After you submit the voice file, go to Voice Notification > Voice Notification File and click Listen for the corresponding file to preview the uploaded audio content.
Step 3: Review process
Voice templates are typically reviewed within 2 hours. The review team works from 9:00 to 23:00 (UTC+8) from Monday to Sunday, excluding public holidays.
Templates are reviewed by human specialists, not by an automated system.
All links, mini-programs, or other business information referenced in your template must belong to the enterprise verified on your current Alibaba Cloud account. Using third-party company information (especially sole proprietorships or entities ineligible for voice services) will cause the review to be rejected. Even if you change account entities, the template content must match the enterprise verified on the current account.
After a template is approved, you can obtain its template ID on the Voice Notifications or Voice Verification Codes page. The template ID is a required parameter when you call an API.
If the review status is Rejected, click Reason to view the reason for rejection.
You cannot modify templates with an Approved, Pending Approval, or Rejected status.
Step 4: API integration and sending
After your template is approved, you can call an API in your application to send voice messages.
Obtain the template ID or voice ID
Template ID: In the template list on the Voice Notifications or Voice Verification Codes page, find the approved template and copy its template ID (referred to as the
TtsCodeparameter in the API). This ID is required to call the API.Voice ID: In the voice file management list, find the approved voice file and copy its voice ID (referred to as the
VoiceCodeparameter in the API). This ID is required to call the API.
Select an API
APIs that support both public mode and dedicated mode templates:
SingleCallByTts: Sends a voice verification code or a text-to-speech voice notification to a specified number.
SingleCallByVoice: Sends a voice notification file to a specified number.
APIs that support only dedicated mode templates:
Create Call Task CreateCallTask: Creates text-to-speech, voice notification, or voice verification code tasks for multiple destination numbers using a service instance.
Execute Call Task ExecuteCallTask: Starts an existing call task.
NoteYou can also create and execute call tasks in the console. For more information, see Use Voice Notification/Voice Verification Code in the console.
Check variable consistency
When calling APIs such as SingleCallByTts, the number of variables passed in the API request must exactly match the number of variables defined in the template. A mismatch will cause the call to fail.
Troubleshooting steps:
Verify that the number of variables in your API call matches the number defined in the template.
Use OpenAPI Explorer to test-run the API and validate your parameters.
Refer to the official Voice Service SDK sample code for a reference implementation.
FAQ
Are voice templates for public mode and dedicated mode interchangeable?
Can voice templates be migrated across accounts, or exported and imported in bulk?
No. Voice templates do not support cross-account migration, bulk export, or bulk import. If you need to use the same template on a different Alibaba Cloud account, re-create the template in the Voice Service console of the target account and wait for approval.
Do I need to reapply for approval of a text-to-speech (TTS) template after changing my voice service number?
No. Changing your voice service number does not affect previously approved TTS templates. The approved templates remain valid and can continue to be used without reapproval.
Deleted templates cannot be recovered. Proceed with caution.