文档首页/ 云客服/ API参考/ 语音通知/ 创建语音通知（V2.0.0）（createVoiceNotification）
更新时间：2025-03-07 GMT+08:00
查看PDF
分享

创建语音通知（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 系统配置类接口鉴权方式。
表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。

数字越小优先级越高。

涉及文本放音时，使用系统管理员登录客户服务云，在“配置中心 > 流程配置 > 智能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."
}

父主题： 语音通知