Help Center/ Cognitive Engagement Center/ API Reference/ Voice Notification Interface Reference/ Creating a Voice Notification (V2.0.0) (createVoiceNotification)
Updated on 2023-09-27 GMT+08:00

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

Table 1 Request header parameters

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.

Table 2 Request body parameters

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.

  • If you upload an IVR voice file through the /rest/cc-management/v1/importVoiceFile/upload API, the IVR voice name is the value of voiceFileName in the request body.
  • If you upload a voice file on the AICC, the IVR voice name is the value of Name whose Usage Scenario is Voice notification on the IVR Voice page. For details about the upload procedure, see Configuring a Voice File.

1.4.3

templateId

String

No

TTS template ID.

  • If you upload a TTS template on the AICC, the template 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.
  • If you use the /rest/cc-management/v1/createVoiceTemplate API to upload the TTS template file, the template ID is the value of templateId in the response parameters.

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 Configuration Center > Flow Configuration > Intelligent IVR > System Management > TTS/ASR Management, 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."
}