文档首页> > API参考> 语音验证码API> 语音验证码场景API

语音验证码场景API

分享
更新时间: 2019/08/09 17:58

接口变更

修改日期

修改说明

2017/1/3

新增请求参数“returnIdlePort”,响应参数“idlePort”,支持空闲端口查询功能。

典型场景

使用语音验证码功能时,调用此API,请求RTC业务平台给特定用户播放语音验证码。

接口功能

语音验证码是SP将被叫号码和数字验证码发送给业务平台,由业务平台呼叫被叫,并在被叫接听后播放验证码。

业务体验描述:

SP想要给用户A通知一串数字验证码。

  1. SP向RTC业务平台发送播放语音验证码业务请求。
  2. RTC业务平台呼叫用户A的号码。
  3. 用户A接听。
  4. RTC业务平台向用户A播放验证码。

使用说明

  • 前提条件
    1. 通过“应用管理”页面添加应用获取对应的app_key和APP接入地址
    2. 已调用“大客户SP简单认证API”获取access_token。
    3. 通过“业务管理”页面添加业务申请CallEnabler业务号码(即绑定号码);如果需要指定主显号码,还需申请主显号码。
    4. 已通过放音文件管理页面上传播放语音验证码之前需要播放的放音文件;若播放语音验证码之后也需要放音,该放音文件也需要通过放音文件管理页面上传。
    5. 已提前准备好接收状态上报和话单上报的服务器地址。

  • 注意事项

  • 使用限制

    无。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

商用环境

/rest/httpsessions/callVerify/v1.0

测试环境

/sandbox/rest/httpsessions/callVerify/v1.0

通信协议

HTTPS

应用商用后,不能调用测试环境的URL。

请求参数

表2 请求URL参数说明

参数名称

是否必选

参数类型

默认值

说明

app_key

String(1-128)

语音验证码能力唯一标识,从“应用管理”页面获取请参考添加应用

access_token

String(1-128)

API访问令牌,填写为使用fastlogin鉴权接口(大客户SP简单认证API)时RTC业务平台返回的access_token字段的值。

表3 请求Headers参数说明

参数名称

是否必选

参数类型

默认值

说明

Content-Type

String

固定填application/json; charset=UTF-8。

表4 请求Body参数说明

参数名称

是否必选

参数类型

默认值

说明

bindNbr

String(4-31)

绑定号码,使用CallEnabler业务号码,需要提前申请该号码

  • 手机号码格式:国家码+手机号码。示例:+8613800000001。
  • 固话格式:国家码+区号+固话,其中区号需去掉首位的0。示例:国家码+86,区号0755,固话号码28000001,填写为+8675528000001。

如果不携带该参数,系统会从与app_key绑定的CallEnabler业务号码中随机选择一个作为bindNbr。

displayNbr

String(4-31)

主显号码,被叫终端上显示的主叫号码,需要提前申请该号码

  • 手机号码格式:国家码+手机号码。示例:+8613423222222。
  • 固话格式:国家码+区号+固话,其中区号需去掉首位的0。示例:国家码+86,区号0755,固话号码28000001,填写为+8675528000001。

calleeNbr

String(4-31)

被叫号码。

  • 手机号码格式:国家码+手机号码。示例:+8613423222222。
  • 固话格式:国家码+区号+固话,其中区号需去掉首位的0。示例:国家码+86,区号0755,固话号码28000001,填写为+8675528000001。

languageType

Integer

验证码播放的语言类型。

取值范围:

1:英文

2:中文

preTone

String(1-128)

播放语音验证码之前需要播放的放音文件名,放音文件需要提前通过放音文件管理页面上传并审核通过才能使用。

当前系统只支持Wave格式的音频文件,文件名如“pretone.wav”。

verifyCode

String(2-9)

验证码:只支持0~9的数字,最大8位。

如“12345678”。

posTone

String(1-128)

播放语音验证码之后需要播放的放音文件名。

如果携带该参数,放音文件需要提前通过放音文件管理页面上传并审核通过才能使用。

当前系统只支持Wave格式的音频文件,文件名如“postone.wav”。

如果不携带该参数,系统将在语音验证码播放完毕后结束通话。

times

Integer

3

播放次数:0~9。

0表示无限循环。

如果不携带该参数,默认播放3次。

statusUrl

String(1-256)

此字段用于设置SP接收状态上报的URL。

RTC平台将业务触发过程中通话的状态信息(包括呼出、振铃、摘机和挂机信息)推送至此服务器,SP根据通话状态信息确定用户状态。

此参数要求使用BASE64编码,如推送URL为https://www.huawei.com:9330/status,则参数值应该携带的是经过BASE64编码的aHR0cHM6Ly93d3cuaHVhd2VpLmNvbTo5MzMwL3N0YXR1cw==。

URL必须填写域名,且该域名对应多个服务器,避免单点故障无法接收通知。

URL只能由大小写字母(a-z、A-Z),数字(0-9),中划线(-),英文冒号(:),英文点号(.),以及英文斜杠(/)组成,不支持其它字符。

feeUrl

String(1-256)

此参数用于设置SP接收话单上报的URL。

RTC平台将业务产生的话单推送至此服务器。

此字段要求使用BASE64编码,如推送URL为https://www.huawei.com:9330/fee,则参数值应该携带的是经过BASE64编码的aHR0cHM6Ly93d3cuaHVhd2VpLmNvbTo5MzMwL2ZlZQ==。

URL必须填写域名且该域名对应多个服务器,避免单点故障无法接收话单。

URL只能由大小写字母(a-z、A-Z),数字(0-9),中划线(-),英文冒号(:),英文点号(.),以及英文斜杠(/)组成,不支持其它字符。

returnIdlePort

String(枚举)

false

指示是否需要返回空闲端口数量。

  • true:需要返回
  • false:不需要返回

如果不携带该参数,系统默认该参数为false。

userData

String(1-256)

用户附属信息,此标识由第三方服务器定义,会在后续的通知消息中携带此信息。不允许携带以下字符:“{”,“}”(即大括号)。

响应参数

表5 响应消息参数说明

参数名称

是否必选

参数类型

默认值

说明

resultcode

String(1-32)

请求返回的结果码。

resultdesc

String(1-128)

请求返回的结果描述。

sessionId

String(1-256)

请求返回的会话sessionId,如果请求失败,则sessionId为空。

idlePort

Integer

请求参数中returnIdlePort为true时响应消息携带该参数。

该参数表示平台呼叫端口空闲可用数量,取值范围0~65535。

结果码

表6 结果码说明

响应码

结果码

英文描述

中文描述

处理方法

200

0

Success.

成功。

无需处理。

500

1010001

Internal system error.

系统错误。

请联系管理员处理。

1020001

Parameter error.

参数错误。

请检查请求携带的参数格式是否都合法。

1020002

Internal error.

内部错误。

请联系管理员处理。

1020150

The app_key is invalid.

app_key无效。

请检查请求携带的app_key填写是否正确。

1020154

The number of app_key voice call ports exceeds the upper limit.

语音端口不足。

请稍等一分钟后再试,或联系管理员申请扩容语音端口。

1020165

The number of app_key voice call ports exceeds the upper limit.

超出app_key语音呼叫端口数限制。

请稍等一分钟后再试,或联系管理员为该app_key申请更多的端口配额。

1023002

Response timeout.

响应超时。

请尝试重新发送一次请求,若依然返回响应超时,请联系管理员处理。

403

1010002

Invalid request.

非法请求。

请检查请求携带的参数格式是否都合法。

1010003

Invalid app_key.

无效的app_key。

请检查请求携带的app_key填写是否正确。

1010004

Invalid access_token.

access_token无效。

请检查app_key和access_token的填写是否正确。

1010005

Expired access_token.

access_token已过期。

请调用“大客户SP简单认证API”重新获取access_token。为避免出现此错误,在access_token有效期还剩下1/4时,需要调用“刷新授权API”到RTC业务平台重新获取新的access_token。

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对应的应用状态是否正常。

1010022

Invalid verification code.

验证码不合法。

请检查verifyCode参数的填写是否合法。

1010023

Invalid display number.

主显号码不合法。

请检查displayNbr参数的填写是否合法,或确认该号码是否已申请。

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和业务号码未绑定,请检查app_key和bindNbr参数的填写是否正确。

1012006

The service number is not applied.

业务号码未申请。

请检查请求携带的bindNbr是否填写正确,若填写正确,请确认该号码是否已申请。

1013001

The number of calls exceeds the threshold configured for the SP account, SPID is {}, and the policy name is {}.

呼叫数超过SP的阈值,SPID是{},策略名是{}。

请和管理员确认开发者呼叫数量限制。

1013002

The number of calls exceeds the threshold configured for the application, app_key is {}, and the policy name is {}.

呼叫数超过APP的阈值,app_key是{},策略名是{}。

请和管理员确认应用呼叫数量限制。

1013003

The number of calls exceeds the threshold configured for number {}, and the policy name is {}.

呼叫数超过号码{}的阈值,策略名是{}。

请和管理员确认显示号码呼叫数量限制。

注:若是全局呼叫频次策略组,则不返回具体号码。

1013004

Number {} is included in the blacklist, and the policy name is {}.

用户{}在黑名单里面,策略名是{}。

请和管理员确认被叫黑名单限制。

1013011

Callee is not on the whitelist.

被叫用户不在白名单中。

请和管理员确认被叫号码白名单限制。

1020166

The app client ip is not in ip white list.

对端app IP不在白名单列表中。

联系管理员检查IP白名单是否配置正确。

接口示例

  • 请求示例
    POST /rest/httpsessions/callVerify/v1.0?app_key=z4Sdu8p7nml5Wd790aENW64oV5Fp&access_token=MTQ4MjkyMDg2Mjc3MjQ5MTA2MTg5MDIwODg1MDAxNzE5ODE3ODUxNjA4MDA1QGNhYXMuaHVhd2VpLmNvbQ== HTTP/1.1 
    
    Date:Wed, 28 Dec 2016 10:26:28 GMT 
    Host:service.example.com 
    Accept:*/* 
    Content-Type:application/json; charset=UTF-8 
    Content-Length:451 
    
    { 
    "bindNbr":"+8675528000001", 
    "displayNbr":"+8675528888888", 
    "calleeNbr":"+8618900000007", 
    "languageType":2, 
    "preTone":"welcome.wav", 
    "verifyCode":"12345678", 
    "times":3, 
    "userData":"cwgtest" 
    }
  • 响应示例
    HTTP/1.1 200 OK 
    Content-Type: application/json;charset=UTF-8 
    
    { 
    "resultcode":"0", 
    "resultdesc":"Success",
    "sessionId":"1200_366_0_20161228102743@callenabler.home1.com"
    }

代码样例

前往代码样例查看。

如果您喜欢这篇文档,您还可以:

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区