Creating a Voice Notification (V2.0.0) (createVoiceNotification)
Scenario
When the voice notification function is used, this API is invoked to request the voice call platform to play a voice notification to a specified user.
Compared with the original API for creating voice notification, the voice file setting method in the request parameters of the API for creating voice notification (V2) is different. In this version, the text-to-speech (TTS) template and template variables can be set. In addition, users can set the timbre, speed, and volume of the voice when using the TTS function.
Method
POST
URI
https://Domain name/apiaccess/rest/voiceNotification/v2/createVoiceNotification. For example, the domain name is service.besclouds.com.
Request Description
No. |
Parameter |
Type |
Mandatory or Not |
Description |
---|---|---|---|---|
1 |
X-APP-Key |
String |
Yes |
App key field, which is the user ID. Contact the operation personnel to obtain the app key. |
2 |
Authorization |
String |
Yes |
Authentication field. The format is Bearer {Value of AccessToken returned by the tokenByAkSk interface}. (A space is required after Bearer.) For details about the generation mode, see C1 System Configuration Interface Authentication. |
No. |
Parameter |
Type |
Mandatory or Not |
Description |
---|---|---|---|---|
1 |
requestBody |
Object |
Yes |
- |
1.1 |
callerPresent |
String |
No |
Calling number displayed on the user side. If this parameter is not carried, the access code of the tenant space is used by default. If this parameter is carried, the access code must be carried. If a non-access code number needs to be transferred, contact O&M personnel to enable the calling number anonymization feature. After this feature is enabled, the number verification rule is as follows: access code or a number of 11 to 14 digits. |
1.2 |
called |
String |
Yes |
Called number. |
1.3 |
callBackUrl |
String |
No |
URL for a customer to receive status reports. Use Base64 to encrypt this parameter using the UTF-8 standard character set. The AICC pushes the call status information during business triggering to the server, and the client server determines the user status based on the call status information. The URL can be set to https://IP address:Port number or a domain name. The domain name is recommended. HTTP and HTTPS are supported. The domain name can correspond to multiple servers to ensure that notifications can be received when a single point of failure occurs. HTTP involves security risks and is not recommended. The URL can contain only letters, digits , and the following special characters: -:./_#?& The IP address and port number, or domain name of the URL must have been added to the mobile agent callback URL trustlist by the system administrator. |
1.4 |
playList |
Array [Object] |
Yes |
Playback information list. A maximum of five playback information records are supported. |
1.4.1 |
voiceId |
String |
No |
Voice ID. You can invoke the /rest/voiceNotification/v1/queryVoiceNotificationRecording API to query the value of voice_id whose recording file type is voice. If you upload a voice file on the AICC, the voice ID is the value of Voice Id whose Usage Scenario is Voice notification and Type is Voice on the IVR Voice page. For details about the upload procedure, see Configuring a Voice File. |
1.4.2 |
voiceFileName |
String |
No |
IVR voice name.
|
1.4.3 |
templateId |
String |
No |
TTS template ID.
|
1.4.4 |
templateParams |
Array |
No |
List of variable values in the TTS template. This parameter is used to fill in the variables specified by templateId in sequence. The parameter value must be encoded in UTF-8 format and cannot contain the following characters: ${} The number and length of variables in the list must be the same as those defined in the template specified by templateId. For example, if the template specified by templateId has two variables whose lengths are 5 and 6 respectively, you need to set two variable values whose lengths are less than or equal to 5 and 6 respectively. If the template content is You have ${NUM_2} parcels delivered to ${TXT_32}, this parameter can be set to "3","main gate of People's Park". |
1.5 |
playTimes |
Integer |
No |
Number of times that the playback information list is repeatedly played. The value ranges from 1 to 5. The default value is 1. |
1.6 |
priority |
String |
No |
Playback priority of a voice notification. The value is an integer ranging from 1 to 9. The default value is 9. A smaller value indicates a higher priority. |
If TTS is involved, sign in to the AICC as a system administrator, choose
, and specify the TTS vendor. The configuration takes effect one minute later.Response Description
- Status code: 200
Table 3 Response body parameters No.
Parameter
Type
Mandatory or Not
Description
1
schema
Object
Yes
-
1.1
retCode
String
Yes
Return code. For details, see Table 4.
1.2
retMsg
String
No
Return result description.
1.3
result
Object
No
This parameter is mandatory when retCode is set to 0.
1.3.1
callSerialNo
String
Yes
Call SN.
Table 4 Return codes No.
Return Code
Description
1.1.1
0
Success.
1.1.2
1
A task is in progress. Try again later.
1.1.3
3
Creation failed. No call SN is generated.
1.1.4
4
The format of softphone does not match the rule.
1.1.5
5
The value of called is not transferred, or the format does not match the rule.
1.1.6
6
The VDN is not enabled.
1.1.7
7
callerPresent fails to pass the verification.
1.1.8
9
The value of callBackUrl does not meet the requirements.
1.1.9
10
The value of playTimes must be greater than or equal to 1 and less than or equal to 5.
1.1.10
11
The playList array is empty or the array size is greater than 5.
1.1.11
12
Both voiceId and templateId are empty.
1.1.12
13
The length of a single variable exceeds 32 bytes.
1.1.13
14
The format of the parameter value in templateParams is incorrect. The parameter value contains at least one of the following characters: ${}.
1.1.14
15
The templateParams array is empty or the array size is greater than 10.
1.1.15
16
The tenant is in trial commercial use state, and the called number is not in the trustlist.
1.1.16
17
The voice or TTS file data does not exist.
1.1.17
18
The recording or TTS text files are not used in voice notification scenarios.
1.1.18
19
The recording or TTS text file is not submitted.
1.1.19
20
The recording or TTS text file is submitted but not approved.
1.1.20
21
The recording or TTS text file is rejected.
1.1.21
22
The file type corresponding to templateId is not text.
1.1.22
23
The file type corresponding to voiceId is not voice.
1.1.23
24
The recording file or TTS file data does not exist in the database.
1.1.24
25
The size of the templateParams array is different from the number of variables defined in the template corresponding to templateId.
1.1.25
26
The date format of the parameter value in templateParams is incorrect.
1.1.26
27
The time format of the parameter value in templateParams is incorrect.
1.1.27
28
The format of the voice notification template is incorrect.
1.1.28
29
The length of the parameter value in templateParams cannot be greater than that of the variable defined in the template specified by templateId. For example, if the variable defined in the template is ${NUM_6} (6 indicates that the maximum length is 6) and the corresponding input parameter value is 1234567, the verification fails.
1.1.29
30
The byte length of the parameter value in templateParams cannot be greater than that of the variable defined in the template specified by templateId. For example, the variable defined in the template is ${TXT_14} (14 indicates that the maximum byte length is 14).
1.1.30
31
The value of the variable ${NUM_Number} in templateParams can be only a digit.
1.1.31
32
The value length of the variable ${NUM_Number} in templateParams is greater than 9.
1.1.32
33
The value of voiceFileName does not exist.
1.1.33
34
The file type corresponding to the input parameter voiceFIleName is not voice.
1.1.34
35
The values of elements in the templateParams array cannot be empty.
1.1.35
36
The value of priority is in an incorrect format.
- Status code: 400
Incorrect request. Check the request path and parameters.
- Status code: 401
Unauthorized operation. 1. Check whether you have purchased related services. 2. Contact customer service to check the status of your account.
- Status code: 403
Authentication fails.
- Status code: 404
The requested content is not found. Check the request path.
- Status code: 500
Business failure. Check the values of parameters in the request.
Error Codes
None
Example
Request header:
{ "Content-Type": application/json "x-app-key": ***** "Authorization": Bearer **** }
Request parameters:
{ "callerPresent": null, "called": "88880000", "playList": [ { "voiceId": "1201763136043459597" }, { "templateId": "1226170940666061826", "templateParams": [ "3", "Main Gate of People's Park" ] } ] }
Response parameters:
{ "result": { "callSerialNo": "11827********7090" }, "retCode": "0", "retMsg": "Created successfully." }
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot