典型场景
使用语音验证码功能时，调用此API，请求语音通话平台给特定用户播放语音验证码。
接口功能
语音验证码是SP将被叫号码和数字验证码发送给业务平台，由业务平台呼叫被叫，并 在被叫接听后播放验证码。
业务体验描述：
SP想要给用户A通知一串数字验证码。
1. SP向语音通话平台发送播放语音验证码业务请求。
2. 语音通话平台呼叫用户A的号码。
3. 用户A接听。
4. 语音通话平台向用户A播放验证码。
使用说明
● 前提条件
a. 已通过“应用管理”页面获取对应的APP_Key，APP_Secret和APP接入地址。
b. 已通过“号码订购”页面申请固话号码。
c. 已通过放音文件管理页面上传播放语音验证码之前需要播放的放音文件；若 播放语音验证码之后也需要放音，该放音文件也需要通过放音文件管理页面 上传。
d. 已提前准备好接收状态上报和话单上报的服务器地址。
● 注意事项 无
● 使用限制 无。
接口类型
表4-1 接口类型说明 请求方法 POST
访问URI /rest/httpsessions/callVerify/v1.0 通信协议 HTTPS
请求参数
表4-2 请求 Headers 参数说明 参数名称 是否
必选
参数类型 说明
Content-Type 是 String 固定填写为application/json;charset=UTF-8。
Authoriza
tion 是 String 固定填写为WSSE
realm="SDP",profile="UsernameToken",type="
Appkey"。
X-WSSE 是 String 取值为UsernameToken Username="APP_Key的 值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
● PasswordDigest：根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成。其中，Password为 APP_Secret的值。Nonce、Created、
Password直接进行字符串拼接即可，无需包含 +号和空格。
● Nonce：客户发送请求时生成的一个随机数，
长度为1~128位，可包含数字和大小写字母。
例如：66C92B11FF8A425FB8D4CCFE0ED9ED1F。
● Created：随机数生成时间。采用标准UTC格 式，例如：2018-02-12T15:30:20Z。不同编程 语言中将UTC时间戳转换为普通时间时使用的 格式不同，部分语言可参考表4-3。
表4-3 不同编程语言的时间格式
编程语言 时间格式
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()转换后的时间格式去除毫秒后即 为本接口要求的时间格式。
表4-4 请求 Body 参数说明 参数名
称
是否必 选
参数类型 默认 值
说明
display
Nbr 是 String(4-3
1) 无 固话号码，被叫终端上显示的主叫号码，
需要提前在订购号码页面申请该号码。
号码格式（固话）：国家码+区号+固话，
与号码管理页面的“号显号码”保持一 致。
若该号码为“暂停”状态，语音通话平台 会从该应用下随机选取一个其他可用的固 话号码进行外呼。
calleeN
br 是 String(4-3
1) 无 被叫号码。
● 手机号码格式：+{国家码}{手机号 码}。示例：+86134****2222。
● 固话格式：+{国家码}{区号}{固话号 码}，其中区号需去掉首位的0。示 例：国家码86，区号0755，固话号码 28****01，填写为+8675528****01。
langua
geType 是 Integer 无 验证码播放的语言类型。
取值范围：
1：英文 2：中文 preTon
e 是 String(1-1
28) 无 播放语音验证码之前需要播放的放音文件
名，放音文件需要提前通过放音文件管理 页面上传并审核通过才能使用。
当前系统只支持Wave格式的音频文件，
文件名如“pretone.wav”。
verifyC
ode 是 String(2-9
) 无 验证码：只支持0～9的数字，最大8位。
如“12345678”。
参数名 称
是否必 选
参数类型 默认 值
说明
posTon
e 否 String(1-1
28) 无 播放语音验证码之后需要播放的放音文件
名。
如果携带该参数，放音文件需要提前通过 放音文件管理页面上传并审核通过才能使 用。
当前系统只支持Wave格式的音频文件，
文件名如“postone.wav”。
如果不携带该参数，系统将在语音验证码 播放完毕后结束通话。
times 否 Integer 3 播放次数：0～9。
0表示无限循环。
如果不携带该参数，默认播放3次。
statusU
rl 否 String(1-1
28) 无 此参数请采用BASE64编码进行加密。
此字段用于设置SP接收状态上报的URL。
语音通话平台将业务触发过程中通话的状 态信息（包括呼出、振铃、摘机和挂机信 息）推送至此服务器，SP根据通话状态信 息确定用户状态。
URL可填写为http://IP:Port或域名，推荐 使用域名，支持http和https。且该域名对 应多个服务器，避免单点故障无法接收通 知。
URL只能由大小写字母（a-z、A-Z），数 字（0-9），中划线（-），英文冒号
（:），英文点号（.），以及英文斜杠
（/）组成，不支持其它字符。
feeUrl 否 String(1-1
28) 无 此参数请采用BASE64编码进行加密。
此参数用于设置SP接收话单上报的URL。
语音通话平台将业务产生的话单推送至此 服务器。
URL可填写为http://IP:Port或域名，推荐 使用域名，支持http和https。且该域名对 应多个服务器，避免单点故障无法接收话 单。
URL只能由大小写字母（a-z、A-Z），数 字（0-9），中划线（-），英文冒号
（:），英文点号（.），以及英文斜杠
（/）组成，不支持其它字符。
参数名 称
是否必 选
参数类型 默认 值
说明
returnI
dlePort 否 String(枚
举) false 指示是否需要返回空闲端口数量。
● true：需要返回
● false：不需要返回
如果不携带该参数，系统默认该参数为 false。
userDa
ta 否 String(1-2
56) 无 用户附属信息，此标识由第三方服务器定
义，会在后续的通知消息中携带此信息。
不允许携带以下字符：“{”，“}”（即 大括号）。
不允许包含中文字符，如果包含中文字符 请采用Base64编码。
响应参数
表4-5 响应消息参数说明
参数名称 是否必选 参数类型 默认值 说明 resultcode 是
String(1-32) 无 请求返回的结果码。
resultdesc 是
String(1-128) 无 请求返回的结果描述。
sessionId 是
String(1-256) 无 请求返回的会话sessionId，如果请 求失败，则sessionId为空。
idlePort 否 Integer 无 请求参数中returnIdlePort为true 时响应消息携带该参数。
该参数表示平台呼叫端口空闲可用 数量，取值范围0~65535。
结果码
请根据以下结果码进行调测，如果有疑问，可联系管理员进行确认。
表4-6 结果码说明 响应
码
结果码 英文描述 中文描述 处理方法
200 0 Success. 成功。 无需处理。
响应 码
结果码 英文描述 中文描述 处理方法
400 102300
6 Authorization not contained in the HTTP header.
鉴权失败，请检 查鉴权请求正确 性。
请检查消息头中是否携带 了Authorization，
PasswordDigest字段填写 是否正确，携带的 app_key填写是否正确，
且生成随机数的时间与发 送请求时的本地时间不能 相差太大。
102300
7 realm not contained in Authorization.
Authorization字 段中未找到realm 属性。
请检查Authorization字段 中的是否携带了realm属 性。
102300
8 profile not contained in Authorization.
Authorization字 段中未找到 profile属性。
请检查Authorization字段 中的是否携带了profile属 性。
102300
9 The value of realm in Authorization must be SDP.
Authorization中 realm属性值应该 为“SDP”。
请检查Authorization字段 中的realm属性值是否为
“SDP”。
102301
0 The value of profile in Authorization must be
UsernameToken.
Authorization中 profile属性值应 该为“UsernameTok en”。
请检查Authorization字段 中的profile属性值是否为
“UsernameToken”。
102301
1 The value of type in Authorization must be app_key.
Authorization中 type属性值应该 为“Appkey”。
请检查Authorization字段 中的type属性值是否为
“Appkey”。
102301
2 type not contained in Authorization.
Authorization字 段中未找到type 属性。
请检查Authorization字段 中是否携带了type属性。
102301
3 WSSE not contained in Authorization.
Authorization中
没有携带WSSE。 请检查Authorization字段 中是否携带了WSSE。
102302
6 X-WSSE not contained in the HTTP header.
HTTP头未找到X-WSSE字段。 请检查HTTP消息头中是 否携带了X-WSSE字段。
102302
7 Username not contained in X-WSSE.
X-WSSE字段中未 找到Username属 性。
请检查X-WSSE字段中的 是否携带了Username属 性。
响应 码
结果码 英文描述 中文描述 处理方法
102302
8 Nonce not contained in X-WSSE.
X-WSSE字段中未 找到Nonce属 性。
请检查X-WSSE字段中的 是否携带了Nonce属性。
102302
9 Created not contained in X-WSSE.
X-WSSE字段中未 找到Created属 性。
请检查X-WSSE字段中的 是否携带了Created属 性。
102303
0 PasswordDigest not contained in X-WSSE.
X-WSSE字段中未 找到PasswordDigest 属性。
请检查X-WSSE字段中的 是否携带了
PasswordDigest属性。
102303
1 The format of Created is incorrect.
Created属性格式 错误。
请检查X-WSSE字段中的 Created属性格式是否正 确。
102303
2 UsernameToken not contained in X-WSSE.
X-WSSE字段中未 找到UsernameToken 属性。
请检查X-WSSE字段中的 是否携带了
UsernameToken属性。
401 101001
0 Invalid digest. PasswordDigest
校验失败。 请检查PasswordDigest字 段填写是否正确。
101001
3 Time out limit. 时间超出限制。 请确认X-WSSE鉴权时，
生成随机数的时间与发送 请求时的本地时间不能相 差太大（具体差值请与管 理员确认）
403 101000
2 Invalid request. 非法请求。 检查请求携带的参数格式 是否都合法。
101000
3 Invalid app_key. 无效的app_key。 检查请求携带的app_key 是否填写正确，app_key 从应用管理页面获取，若 填写正确，请在应用管理 页面检查请求携带的 app_key所属应用状态是 否正常。
101000
6 Invalid Rest API. 无效的Rest
API。 检查请求方法填写是否正
确。
101000
8 The status of the app_key is unavailable.
app_key被暂停使 用。
请在应用管理页面检查请 求携带的app_key所属应 用状态是否正常。
101000
9 No more APIs
can be invoked. API达到调用上 限。
请稍等一分钟后再试，并 联系管理员申请更高的应 用使用配额。
响应 码
结果码 英文描述 中文描述 处理方法
101001
0 The flow control upper limit is reached on the platform.
平台达到系统流 控上限。
请稍等一分钟后再试。
101001
1 The app is not allowed to access a commercial address.
APP没有访问商 用地址的权限。
请在应用管理页面检查请 求携带的app_key所属应 用状态是否正常。
101002
1 Application
unavailable. 应用不可用。 请在应用管理页面检查请 求携带的app_key所属应 用状态是否正常。
101002
3 Invalid display
number. 号显号码不合
法。 检查displayNbr和 displayCalleeNbr参数的 填写是否合法，与号码管
101002
4 Invalid caller
number. 主叫号码不合 法。
检查callerNbr参数的填写 是否合法。
101004
0 The app_key is not allowed to invoke the API.
app_key没有调用
本API的权限。 请联系管理员确认该 app_key对应的应用是否 具语音验证码能力。
101200
1 Resource of number is not to be applied.
资源未申请。 app_key和业务号码未绑 定。
101200
6 The service number is not applied.
业务号码未申 请。
请确认是否申请业务号 码。
101201
2 Application does not open
recording function.
应用未开启录音 功能。
请在应用管理页面确认请 求携带的app_key是否开 启了录音功能。
101202
2 The recordFlag parameter must be true in the voice call transparent transmission mode.
语音回呼透传模 式下recordFlag 必须为true。
透传模式下请将
recordFlag设置为true。
响应 码
结果码 英文描述 中文描述 处理方法
101300
1 Calls exceed the
SP limit. 请求次数超过SP 配置上限。
请和管理员确认开发者呼 叫数量限制。
101300
2 Calls exceed the
APP limit. 请求次数超过应 用配置上限。
请和管理员确认应用呼叫 数量限制。
101300
3 Calls exceed the display number limit.
SP的主显号码受 限。
请和管理员确认显示号码 呼叫数量限制。
101300
4 Callee in
blacklist. 被叫用户是黑名 单。
被叫号码在运营商黑名单 库。
101301
0 Caller in
blacklist. 主叫用户是黑名
blacklist. 主叫用户是黑名