创建语音通知（V2.0.0）（createVoiceNotification）
场景描述
使用语音通知功能时，调用此API，将请求语音通话平台给指定用户播放语音通知。
创建语音通知（V2）接口对比原创建语音通知接口，其请求参数中的语音文件设置方式不同，现支持设置文本转语音的模板和设置模板变量，并且文本转语音支持用户设置语音播放的音色、语速、音量。
接口方法
POST
接口URI
https://域名/apiaccess/rest/voiceNotification/v2/createVoiceNotification，例如域名是service.besclouds.com
请求说明
序号 |
名称 |
参数类型 |
是否必选 |
说明 |
|---|---|---|---|---|
1 |
X-APP-Key |
string |
True |
appKey字段，用户标识，请联系运营人员获取appKey |
2 |
Authorization |
string |
True |
鉴权字段，内容格式为: Bearer +tokenByAKSK接口的返回值中AccessToken（Bearer后有空格）。 生成方式参见C1 系统配置类接口鉴权方式。 |
序号 |
名称 |
参数类型 |
是否必选 |
说明 |
|---|---|---|---|---|
1 |
requestBody |
object |
True |
- |
1.1 |
callerPresent |
string |
False |
用户侧主叫显示号码，用户看到的主叫号码，不携带的情况下默认采用租间的接入码，携带的情况下该号码必须传接入码。如果需要传非接入码号码，请联系运维人员开通主叫透显特性，该特性开通后号码校验规则为：接入码或者11-14位的数字。 |
1.2 |
called |
string |
True |
被叫号码 |
1.3 |
callBackUrl |
string |
False |
此参数请采用BASE64编码以UTF_8标准字符集进行加密。 此字段用于设置客户接收状态上报的URL。 AICC将业务触发过程中通话的状态信息推送至此服务器，客户服务器根据通话状态信息确定用户状态。 URL可填写为https://IP:Port或域名，推荐使用域名，支持http和https。该域名可以对应多个服务器，避免单点故障无法接收通知。 http有安全风险，不推荐使用。 URL只能由大小写字母（a-z、A-Z），数字（0-9）， - : . / _ # ? &组成，不支持其它字符。 URL的域名或IP端口已通过系统管理员加入手机客服回调的地址白名单中。 |
1.4 |
playList |
array[object] |
True |
播放信息列表，最大为5个。 |
1.4.1 |
voiceId |
string |
False |
录音id。 录音id可以通过/rest/voiceNotification/v1/queryVoiceNotificationRecording接口查询录音文件类型为音频的voice_id。 若您是通过客户服务云界面上传的语音文件，录音id即为IVR语音界面使用场景为语音通知并且类型为语音的“语音标识”。上传操作步骤请参见配置语音文件。 |
1.4.2 |
voiceFileName |
string |
False |
IVR语音名称。
|
1.4.3 |
templateId |
string |
False |
TTS模板id。
|
1.4.4 |
templateParams |
array |
False |
TTS模板的变量值列表，用于依次填充templateId指定的的变量。 参数内容必须是“UTF-8”编码，不能包含以下3个字符：“$”，“{”，“}”。 列表中变量值的个数及长度必须和templateId内容中定义的变量个数及长度保持一致；例如templateId有2个变量且变量长度分别为5和6，则此处需要设置2个变量值且内容长度分别小于等于5和6。 如模板内容为“您有${NUM_2}件快递请到${TXT_32}领取”时，该参数可填写为["3"，"人民公园正门"]。 |
1.5 |
playTimes |
integer |
False |
针对播放信息列表重复播放的次数，取值范围1~5，默认为1。 |
1.6 |
priority |
string |
False |
播放语音通知优先级参数。 取值范围1-9整数，默认值为9。 数字越小优先级越高。 |
涉及文本放音时，使用系统管理员登录客户服务云，在页面指定TTS厂家，配置后一分钟生效。
响应说明
- 响应状态码: 200
表3 响应体参数 序号
名称
参数类型
是否必选
说明
1
schema
object
True
-
1.1
retCode
string
True
返回码，具体返回码说明请参考表4。
1.2
retMsg
string
False
返回描述
1.3
result
object
False
retCode为0时，必返回
1.3.1
callSerialNo
string
True
呼叫流水号
表4 返回码说明 序号
返回码
说明
1.1.1
0
成功。
1.1.2
1
有未完成的任务，请稍后重试。
1.1.3
3
创建失败，未生成呼叫流水号。
1.1.4
4
softPhone格式与规则不匹配。
1.1.5
5
called未传递，或者格式与规则不匹配。
1.1.6
6
vdn未启用。
1.1.7
7
callerPresent校验失败。
1.1.8
9
callBackUrl不符合条件。
1.1.9
10
playTimes必须大于等于1且小于等于5。
1.1.10
11
playList数组为空或者数组大小大于5。
1.1.11
12
voiceId和templateId同时为空。
1.1.12
13
单个变量长度超出32字节。
1.1.13
14
templateParams中参数值的格式不正确，包含"$”，“{”，“}"3个字符其中一个。
1.1.14
15
templateParams数组为空或者数组大小大于10。
1.1.15
16
租户为试商用状态，被叫号码不在白名单中。
1.1.16
17
语音或者TTS文件数据不存在。
1.1.17
18
录音或者TTS文本文件不属于语音通知使用场景。
1.1.18
19
录音或者TTS文本文件未提交。
1.1.19
20
录音或者TTS文本文件提交未审核。
1.1.20
21
录音或者TTS文本文件审核不通过。
1.1.21
22
templateId对应的文件类型不是文本类型。
1.1.22
23
voiceId对应的文件类型不是语音类型。
1.1.23
24
录音文件或者TTS文件数据在数据库中不存在。
1.1.24
25
templateParams数组大小和templateId对应模板中定义的变量个数不相等。
1.1.25
26
templateParams中参数值的日期格式不正确。
1.1.26
27
templateParams中参数值的时间格式不正确。
1.1.27
28
语音通知模板格式不正确。
1.1.28
29
templateParams中参数值的长度大于templateId对应模板中定义的变量的长度，比如模板定义的变量是${NUM_6}(数字6表示最大长度为6)，而对应入参值为1234567，那么会被校验住。
1.1.29
30
templateParams中参数值的字节长度不能大于templateId对应模板中定义的变量的长度，例如模板定义的变量是${TXT_14}(数字14表示最大字节数为14)。
1.1.30
31
templateParams中对应可变变量${NUM_数字}的参数值类型只能为数字。
1.1.31
32
templateParams中对应可变变量${NUM_数字}的参数值的长度大于9。
1.1.32
33
voiceFileName不存在。
1.1.33
34
入参voiceFIleName对应的文件类型不是语音类型。
1.1.34
35
templateParams数组中元素的值不能为空。
1.1.35
36
priority字段值格式不符合要求。
- 响应状态码: 400
错误的请求：请检查请求路径及参数
- 响应状态码: 401
未授权：1. 请确认是否购买了相关服务。 2. 请联系客服人员检查您账号的当前状态
- 响应状态码: 403
鉴权失败
- 响应状态码: 404
请求的内容未找到：请检查请求的路径
- 响应状态码: 500
业务失败：请依次确认您请求中各参数的取值
错误码
无。
报文样例
请求头:
{
"Content-Type": application/json
"x-app-key": *****
"Authorization": Bearer ****
}
请求参数:
{
"callerPresent": null,
"called": "88880000",
"playList": [
{
"voiceId": "1201763136043459597"
},
{
"templateId": "1226170940666061826",
"templateParams": [
"3",
"人民公园正门"
]
}
]
}
响应参数:
{
"result": {
"callSerialNo": "11827********7090"
},
"retCode": "0",
"retMsg": "Created successfully."
}
