# 创建语音通知（V2.0.0）（createVoiceNotification） #### 场景描述 使用语音通知功能时，调用此API，将请求语音通话平台给指定用户播放语音通知。 创建语音通知（V2）接口对比原创建语音通知接口，其请求参数中的语音文件设置方式不同，现支持设置文本转语音的模板和设置模板变量，并且文本转语音支持用户设置语音播放的音色、语速、音量。 #### 接口方法 POST #### 接口URI https://域名/apiaccess/rest/voiceNotification/v2/createVoiceNotification，例如域名是service.besclouds.com #### 请求说明 表1请求头参数 | 序号 | 名称 | 参数类型 | 是否必选 | 说明 | |:---|:---|:---|:---|:---| | 1 | X-APP-Key | string | True | appKey字段，用户标识，请联系运营人员获取appKey | | 2 | Authorization | string | True | 鉴权字段，内容格式为: Bearer +tokenByAKSK接口的返回值中AccessToken（Bearer后有空格）。 生成方式参见[C1 系统配置类接口鉴权方式](https://support.huaweicloud.com/api-ccfs-cec/cec_07_0100.html#ZH-CN_TOPIC_0000002481113506)。 | 表2请求体参数 | 序号 | 名称 | 参数类型 | 是否必选 | 说明 | |:---|:---|:---|:---|:---| | 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语音名称。 - 若您是通过上传IVR语音文件接口/rest/cc-management/v1/importVoiceFile/upload上传，IVR语音名称即为请求体参数的"voiceFileName"。 - 若您是通过客户服务云界面上传的语音文件，IVR语音名称即为IVR语音界面使用场景为语音通知的"名称"。上传操作步骤请参见配置语音文件。 | | 1.4.3 | templateId | string | False | TTS模板id。 - 通过客户服务云界面上传的文本转语音模板，TTS模板id即为IVR语音界面使用场景为语音通知并且类型为文本的"语音标识"。上传操作步骤请参见配置语音文件。 - 若您是通过上传语音通知的文字转语音模板文件接口/rest/cc-management/v1/createVoiceTemplate上传，TTS模板id即为响应参数的"templateId"。 | | 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。 数字越小优先级越高。 | ![](https://support.huaweicloud.com/api-ccfs-cec/public_sys-resources/note_3.0-zh-cn.png) 涉及文本放音时，使用系统管理员登录客户服务云，在"配置中心 \> 流程配置 \> 智能IVR \> 系统管理 \> TTS/ASR管理"页面指定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." } ```