语音通知API
典型场景
使用语音通知功能时，调用此API，请求语音通话平台给指定用户播放语音通知。
接口功能
语音通知是SP将被叫号码和语音通知文件名（语音文件需要提前通过放音文件管理页面上传）或语音通知文本（通过语音模板管理页面提交）发送给业务平台，由业务平台呼叫被叫，被叫接听后业务平台向被叫播放语音，并进行收号。SP可以要求业务平台播放多段语音，每段语音的内容都可以是下列两种语音中的一种：
- 语音文件中录制的语音。
- 文本（需要先通过模板定义）通过TTS服务转换成的语音。
业务体验描述：
SP想要给用户A通知一段或多段语音。
- SP向语音通话平台发送播放语音通知业务请求。
- 语音通话平台呼叫用户A的号码。
- 用户A接听。
- 语音通话平台向用户A播放语音。
使用说明
接口类型
|
请求方法 |
POST |
|
|---|---|---|
|
访问URI |
/rest/httpsessions/callnotify/v2.0 |
|
|
通信协议 |
HTTPS |
|
请求参数
|
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
version |
是 |
String(枚举) |
无 |
版本，取值为v2.0。 |
|
参数名称 |
是否必选 |
参数类型 |
说明 |
|---|---|---|---|
|
Content-Type |
是 |
String |
固定填写为application/json;charset=UTF-8。 |
|
Authorization |
是 |
String |
固定填写为AKSK realm="SDP",profile="UsernameToken",type="Appkey"。 |
|
X-AKSK |
是 |
String |
取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
|
|
编程语言 |
时间格式 |
|---|---|
|
Java |
yyyy-MM-dd'T'HH:mm:ss'Z' |
|
PHP |
Y-m-d\TH:i:s\Z |
|
Python |
%Y-%m-%dT%H:%M:%SZ |
|
C# |
yyyy-MM-ddTHH:mm:ssZ |
|
Node.js |
toISOString().replace(/.[0-9]+\Z/, 'Z') 注：Node.js中，使用toISOString()转换后的时间格式去除毫秒后即为本接口要求的时间格式。 |
|
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
displayNbr |
是 |
String(4-31) |
无 |
固话号码，被叫终端上显示的主叫号码，需要提前在订购号码页面申请该号码。 号码格式（固话）：国家码+区号+固话，与号码管理页面的“固话号码”保持一致。 若该号码为“暂停”状态，语音通话平台会从该应用下随机选取一个其他可用的固话号码进行外呼。 |
|
calleeNbr |
是 |
String(4-31) |
无 |
被叫号码。
|
|
playInfoList |
是 |
PlayContentInfo[1-5] |
无 |
播放信息列表，最大支持5个，每个播放信息携带的参数都可以不相同。 |
|
statusUrl |
否 |
String(1-128) |
无 |
此参数请采用BASE64编码进行加密。 此字段用于设置SP接收状态上报的URL。 语音通话平台将业务触发过程中通话的状态信息（包括呼出、振铃、摘机和挂机信息）推送至此服务器，SP根据通话状态信息确定用户状态。 URL可填写为https://IP:Port或域名，推荐使用域名。且该域名对应多个服务器，避免单点故障无法接收通知。 URL只能由大小写字母（a-z、A-Z），数字（0-9），中划线（-），英文冒号（:），英文点号（.），以及英文斜杠（/）组成，不支持其它字符。 |
|
feeUrl |
否 |
String(1-128) |
无 |
此参数请采用BASE64编码进行加密。 此参数用于设置SP接收话单上报的URL。 语音通话平台将业务产生的话单推送至此服务器。 URL可填写为https://IP:Port或域名，推荐使用域名。且该域名对应多个服务器，避免单点故障无法接收话单。 URL只能由大小写字母（a-z、A-Z），数字（0-9），中划线（-），英文冒号（:），英文点号（.），以及英文斜杠（/）组成，不支持其它字符。 |
|
returnIdlePort |
否 |
String(枚举) |
false |
指示是否需要返回平台的空闲端口数量。
如果不携带该参数，系统默认该参数为false。 |
|
userData |
否 |
String(1-256) |
无 |
用户附属信息，此标识由第三方服务器定义，会在后续的通知消息中携带此信息。 不允许携带以下字符：“{”，“}”（即大括号）。 不允许包含中文字符，如果包含中文字符请采用Base64编码。 |
|
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
notifyVoice |
否 |
String(1-128) |
无 |
通知语音的放音文件名。需要先通过放音文件管理页面上传放音文件并通过审核才能使用。 当前系统只支持Wave格式的音频文件，文件如“notifyvoice.wav”。 该参数和templateId是二选一的关系，即两个参数必须携带其中一个。 |
|
templateId |
否 |
String(1-32) |
无 |
语音通知模板ID，用于唯一标识语音通知模板。语音通知模板为TTS文本的模板，需要先通过语音模板管理页面提交模板并通过审核才能使用，并获取对应的模板ID。 该参数和notifyVoice是二选一的关系。需要与templateParas参数配合使用。 |
|
templateParas |
否 |
String(1-32)[1-10] |
无 |
语音通知模板的变量值列表，用于依次填充templateId参数指定的模板内容中的变量。 该参数需填写为JSONArray格式。具体可参考变量规则。 参数内容必须是“UTF-8”编码，不能包含以下3个字符：“$”，“{”，“}”。 当接口中携带“templateId”参数时，必须携带此参数，若未携带此参数系统将返回“非法请求”错误。 列表中变量值的个数及长度必须和templateId对应模板内容中定义的变量个数及长度保持一致；例如templateId对应的模板内容有2个变量且变量长度分别为5和6，则此处需要设置2个变量值且内容长度分别小于等于5和6。 如模板内容为“您有${NUM_2}件快递请到${TXT_32}领取”时，该参数可填写为["3","人民公园正门"]。 |
|
collectInd |
否 |
Integer(0-32) |
0 |
是否进行收号。若进行收号，请在语音通知内容播放完毕后的5秒之内进行按键操作，系统会将用户输入的号码通过语音通知呼叫状态通知API发送给SP。 取值范围： 0：不收号 1~32：收号，并且取值表示收号位长，最大支持32位。 若不携带该参数，则默认不收号。 |
|
replayAfterCollection |
否 |
String(枚举) |
false |
当collectInd字段设置为非0时此参数有效。 此字段用于设置是否在收号后重新播放notifyVoice、ttsContent或templateId指定的放音。
默认值：false。 |
|
collectContentTriggerReplaying |
否 |
String(1-32) |
无 |
当replayAfterCollection字段设置为true时此参数有效。 此字段用于设置触发重新放音的收号内容。只有实际收号内容与该参数值一致时，才重新放音。例如：该参数设置为1，当用户根据收号语音提示按1，两者一致，则重复放音。 |
响应参数
|
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
|
resultcode |
是 |
String(1-32) |
无 |
请求返回的结果码。 |
|
resultdesc |
是 |
String(1-128) |
无 |
请求返回的结果描述。 |
|
sessionId |
是 |
String(1-256) |
无 |
请求返回的会话sessionId，如果请求失败，则sessionId为空。 |
|
idlePort |
否 |
Integer |
无 |
请求参数中returnIdlePort为true时响应消息携带该参数。 该参数表示平台呼叫端口空闲可用数量，取值范围0~65535。 |
结果码
请根据以下结果码进行调测，如果有疑问，可联系管理员进行确认。
|
响应码 |
结果码 |
英文描述 |
中文描述 |
处理方法 |
|---|---|---|---|---|
|
200 |
0 |
Success. |
成功。 |
无需处理。 |
|
400 |
1023006 |
|
鉴权失败，请检查鉴权请求正确性。 |
|
|
1023007 |
realm not contained in Authorization. |
Authorization字段中未找到realm属性。 |
请检查Authorization字段中的是否携带了realm属性。 |
|
|
1023008 |
profile not contained in Authorization. |
Authorization字段中未找到profile属性。 |
请检查Authorization字段中的是否携带了profile属性。 |
|
|
1023009 |
The value of realm in Authorization must be SDP. |
Authorization中realm属性值应该为“SDP”。 |
请检查Authorization字段中的realm属性值是否为“SDP”。 |
|
|
1023010 |
The value of profile in Authorization must be UsernameToken. |
Authorization中profile属性值应该为“UsernameToken”。 |
请检查Authorization字段中的profile属性值是否为“UsernameToken”。 |
|
|
1023011 |
The value of type in Authorization must be app_key. |
Authorization中type属性值应该为“Appkey”。 |
请检查Authorization字段中的type属性值是否为“Appkey”。 |
|
|
1023012 |
type not contained in Authorization. |
Authorization字段中未找到type属性。 |
请检查Authorization字段中是否携带了type属性。 |
|
|
1023033 |
HTTP header not found X-AKSK field. |
HTTP头未找到X-AKSK字段。 |
请检查HTTP消息头中是否携带了X-AKSK字段。 |
|
|
1023034 |
UserName not contained in X-AKSK. |
X-AKSK字段中未找到UserName属性。 |
请检查X-AKSK字段中的是否携带了Username属性。 |
|
|
1023035 |
Nonce not contained in X-AKSK. |
X-AKSK字段中未找到Nonce属性。 |
请检查X-AKSK字段中的是否携带了Nonce属性。 |
|
|
1023036 |
Created not contained in X-AKSK. |
X-AKSK字段中未找到Created属性。 |
请检查X-AKSK字段中的是否携带了Created属性。 |
|
|
1023037 |
PasswordDigest not contained in X-AKSK. |
X-AKSK字段中未找到PasswordDigest属性。 |
请检查X-AKSK字段中的是否携带了PasswordDigest属性。 |
|
|
1023038 |
UsernameToken not contained in X-AKSK. |
X-AKSK中没有携带UsernameToken。 |
请检查X-AKSK字段中的是否携带了UsernameToken属性。 |
|
|
401 |
1010010 |
Invalid digest. |
PasswordDigest校验失败。 |
请检查PasswordDigest字段填写是否正确。 |
|
1010013 |
Time out limit. |
时间超出限制。 |
请确认X-AKSK鉴权时，生成随机数的时间与发送请求时的本地时间不能相差太大（具体差值请与管理员确认） |
|
|
403 |
1010002 |
Invalid request. |
非法请求。 |
检查请求携带的参数格式是否都合法。 |
|
1010003 |
Invalid app_key. |
无效的app_key。 |
检查请求携带的app_key是否填写正确，app_key从应用管理页面获取，若填写正确，请在应用管理页面检查请求携带的app_key所属应用状态是否正常。 |
|
|
1010006 |
Invalid Rest API. |
无效的Rest API。 |
检查请求方法填写是否正确。 |
|
|
1010008 |
The status of the app_key is unavailable. |
app_key被暂停使用。 |
请在应用管理页面检查请求携带的app_key所属应用状态是否正常。 |
|
|
1010009 |
No more APIs can be invoked. |
API达到调用上限。 |
请稍等一分钟后再试，并联系管理员申请更高的应用使用配额。 |
|
|
1010010 |
The flow control upper limit is reached on the platform. |
平台达到系统流控上限。 |
请稍等一分钟后再试。 |
|
|
1010011 |
The app is not allowed to access a commercial address. |
APP没有访问商用地址的权限。 |
请在应用管理页面检查请求携带的app_key所属应用状态是否正常。 |
|
|
1010021 |
Application unavailable. |
应用不可用。 |
请在应用管理页面检查请求携带的app_key所属应用状态是否正常。 |
|
|
1010023 |
Invalid display number. |
号码填写不合法。 |
检查displayNbr和displayCalleeNbr参数的填写是否合法，与号码管理页面的“固话号码”保持一致。若合法，请确认该号码是否已申请并下发。申请号码在号码订购页面申请，号码下发后可在号码管理页面查看。 |
|
|
1010024 |
Invalid caller number. |
主叫号码不合法。 |
检查callerNbr参数的填写是否合法。 |
|
|
1010040 |
The app_key is not allowed to invoke the API. |
app_key没有调用本API的权限。 |
请联系管理员确认该app_key对应的应用是否具有语音通知能力。 |
|
|
1012001 |
Resource of number is not to be applied. |
资源未申请。 |
app_key和业务号码未绑定。 |
|
|
1012005 |
%s of templateParas does not meet template requirements. |
参数templateParas中的%s不符合模板定义的要求。 |
请检查templateParas携带的变量值格式与长度是否符合templateId对应的模板内容中变量的定义。 |
|
|
1012006 |
The service number is not applied. |
业务号码未申请。 |
请确认是否申请业务号码。 |
|
|
1012012 |
Application does not open recording function. |
应用未开启录音功能。 |
请在应用管理页面确认请求携带的app_key是否开启了录音功能。 |
|
|
1013001 |
Calls exceed the SP limit. |
请求次数超过SP配置上限。 |
请和管理员确认开发者呼叫数量限制。 |
|
|
1013002 |
Calls exceed the APP limit. |
请求次数超过应用配置上限。 |
请和管理员确认应用呼叫数量限制。 |
|
|
1013003 |
Calls exceed the display number limit. |
SP的主显号码受限。 |
请和管理员确认显示号码呼叫数量限制。 |
|
|
1013004 |
Callee in blacklist. |
被叫用户是黑名单。 |
被叫号码在运营商黑名单库。 |
|
|
1013010 |
Caller in blacklist. |
主叫用户是黑名单。 |
主叫号码在运营商黑名单库。 |
|
|
1013011 |
Callee is not on the whitelist. |
被叫用户不在白名单中。 |
请和管理员确认被叫号码白名单限制。 |
|
|
1013100 |
Common error code . |
未知错误。 |
请和管理员确认安全管控限制。 |
|
|
1013101 |
Abnormal call restricted . |
呼叫行为异常。 |
请和管理员确认安全管控限制。 |
|
|
1013111 |
International callin is forbidden. |
国际呼入限制。 |
请检查请求的号码格式是否为国际号码格式。 |
|
|
1013112 |
International callout is forbidden. |
国际呼出限制。 |
请检查请求的号码格式是否为国际号码格式。 |
|
|
1013113 |
Abnormal call duration restricted. |
通话时间异常。 |
请检查请求的号码是否通话时间异常。 |
|
|
1013115 |
Abnormal call completion rate restricted. |
呼叫接通率异常。 |
请检查请求的号码是否呼叫接通率异常。 |
|
|
1013116 |
Caller call frequency restricted. |
主叫呼叫频次限制。 |
请检查主叫号码是否有呼叫频次限制。 |
|
|
1013117 |
Callee call frequency restricted. |
被叫呼叫频次限制。 |
请检查被叫号码是否有呼叫频次限制。 |
|
|
1013118 |
Service number call frequency restricted. |
业务号码呼叫频次限制。 |
请检查业务号码是否有呼叫频次限制。 |
|
|
1013119 |
Service number suspend. |
业务号码被暂停。 |
请和管理员确认号码状态。 |
|
|
1013120 |
Ip address is null. |
IPv4地址未携带。 |
请客户接口携带请求发送方IPv4地址。 |
|
|
1013121 |
Call black time forbidden. |
呼叫时段限制。 |
呼叫时段为休息时段，请工作时段再呼叫。 |
|
|
1013122 |
Sub enterprise is suspended. |
子企业已被暂停。 |
查看是否因投诉被下线，可查看订购号码时填写的邮箱是否有业务下线通知邮件。 |
|
|
1020165 |
The number of app_key voice call ports exceeds the upper limit. |
超出语音呼叫端口数限制。 |
请稍等一分钟后再试。建议联系管理员为该应用申请更多的端口配额。 |
|
|
1020166 |
The app client ip is not in ip white list. |
请求发送方app IP不在白名单列表中。 |
运营商IP地域管控，此地区无法呼通。 |
|
|
1020168 |
The call is rejected because the login IP of the peer app is blacklisted . |
请求发送方app登录IP是黑名单。 |
运营商IP地域管控，此地区无法呼通。 |
|
|
1020171 |
The call is rejected because the login IP of the peer app is blacklisted area. |
请求发送方app登录IP在受限地域。 |
运营商IP地域管控，此地区无法呼通。 |
|
|
1020176 |
Authentication failed, try again later |
鉴权失败，稍后重试。 |
IP因鉴权失败次数过多导致被拉黑，请30分钟后重试，或联系管理员放通该IP。 |
|
|
500 |
1010001 |
Internal system error. |
系统错误。 |
请联系管理员处理。 |
|
1020001 |
Parameter error. |
参数错误。 |
检查请求携带的参数格式是否都合法。 |
|
|
1020002 |
Internal error. |
内部错误。 |
请联系管理员处理。 |
|
|
1020150 |
The app_key is invalid. |
app_key无效。 |
检查请求携带的app_key是否填写正确，app_key从应用管理页面获取，若填写正确，请在应用管理页面检查请求携带的app_key所属应用状态是否正常。 |
|
|
1020151 |
The bindNum is invalid. |
业务号码无效。 |
业务号码无效，请联系管理员处理。 |
|
|
1020154 |
Insufficient voice ports. |
语音端口不足。 |
请稍等一分钟后再试，并联系管理员申请扩容语音端口。 |
|
|
1023001 |
Internal error. |
内部错误。 |
请联系管理员处理。 |
|
|
1023002 |
Response timeout. |
响应超时。 |
重新发送一次请求。 |
接口示例
- 请求示例
示例1 POST /rest/httpsessions/callnotify/v2.0 HTTP/1.1 content-type: application/json;charset=UTF-8 authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey" x-aksk: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="****",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z" content-length:xx { "displayNbr":"+86186****5611", "calleeNbr":"+8675581****01", "playInfoList":[{"notifyVoice":"welcome.wav"},{"notifyVoice":"welcome.wav","collectInd":4}], "statusUrl":"****", "feeUrl":"****", "userData":"testUserData" } 示例2 语音通话平台上设置的模板ID=test_template，模板内容为“您有${NUM_2}件快递请到${TXT_32}领取”。 下面的API将播放文本“您有3件快递请到人民公园正门领取”。 POST /rest/httpsessions/callnotify/v2.0?app_key=z4Sdu8p7nml5Wd790aENW64oV5Fp HTTP/1.1 content-type: application/json;charset=UTF-8 authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey" x-aksk: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="****",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z" content-length:xx { "displayNbr":"+86186****5611", "calleeNbr":"+8675581****01", "playInfoList":[{"templateId":"test_template", "templateParas":["3","人民公园正门"],"collectInd":5}], "statusUrl":"****", "feeUrl":"****", "userData":"testUserData" }
- 响应示例
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "resultcode":"0", "resultdesc":"Success", "sessionId":"1200_366_0_20161228102743@callenabler.home1.com" }
代码样例
前往代码样例查看。
