云之讯自定义配置应用回调地址指南.docx

云之讯自定义配置应用回调地址指南

云之讯作为国内领先的全通讯能力服务平台，拥有端到端的通讯能力，企业可以凭此快速建立与用户的连接。同时，为了增加云之讯平台的灵活性，也为了第三方服务器（AS）能够灵活的控制发送给UCPaaS的业务请求，云之讯平台为开发者提供可供自定义配置的应用回调地址（Callback API）服务。如果勾选并配置相关回调地址，UCPaaS会主动根据回调地址信息发送HTTP请求给AS，比如将呼叫的状态信息通知给AS，即UCPaaS的回调机制。
需要说明的是多数情况下回调服务并非所有开发者项目的必须，开发者可依据业务开展的情况酌情考虑。默认情况下建议开发者充分利用云之讯平台的回调地址，为企业的业务服务提供更丰富的体验，并降低更多可控的风险。

1、回调地址接口类型
云之讯按照不同产品的业务场景的区分为开发者提供产品回调（Callback API）接口，开发者可针对应用使用的特定产品单独配置回调地址，亦可将所有产品配置统一的回调地址：
（1）呼叫鉴权请求接口
（2）呼叫接通通知接口
（3）呼叫结束(挂机) 接口
（4）语音通知状态通知接口
（5）语音验证码状态通知接口
（6）短信通知状态接口
（7）所有产品回调接口
回调地址配置使用路径为【开发者控制台>产品（例如语音通知）>接入的应用>修改】，【开发者控制台>应用管理>点击需要修改的应用>编辑】，另外云之讯平台现在已经升级，建议开发者将所有的回调功能集成于所有产品回调地址内，这样的配置在未来也将成为默认推荐使用的配置项。以下为以通话为案例展示一个【通话】语音业务的请求过程：

通过通话类的回调机制，AS可以实时控制用户的最大通话时长、通过主叫号码或被叫号码进行限制拨打等功能；同时，AS还可以实现精确计费功能，避免由于客户端恶意拨打，浪费开发者费用。通过短信或语音通知类的回调机制，AS能够及时掌握业务情况的执行结果。

2、回调机制——呼叫鉴权请求
云之讯UCPaaS在收到呼叫请求时回调给AS，携带呼叫的类型、主被叫号码信息。一般情况下，AS可以根据主被叫号码信息进行以下控制：
（1）是否允许呼叫继续
（2）控制呼叫的最大通话时长
（3）是否进行录音操作
（4）控制被叫显示的号码
需要注意的是，如果应用配置中配置了“呼叫鉴权”回调地址，则UCPaaS会触发“呼叫鉴权请求”，UCPaaS会等待收到回调响应后，才继续后续呼叫；因此应用中必须配置正确的回调地址，并且能够及时返回回调响应消息，否则可能导致呼叫失败。

3、回调机制——呼叫建立通知
云之讯UCPaaS在呼叫建立后（即被叫接通电话）回调给AS，携带呼叫类型、主被叫号码信息：一般情况下，AS根据此回调对该呼叫启动计费。关于呼叫挂机计费，UCPaaS在呼叫拆除后（即主叫或被叫挂断电话）回调给AS，携带主被叫信息，通话的开始、结束时间，通话录音地址，挂机原因。一般情况下，AS可以做以下操作：
（1）对该呼叫停止计费
（2）根据通话起始、结束时间对该呼叫计费
（3）根据录音地址，获取该呼叫的录音文件

4、状态通知接口
UCPaaS的短信验证码、语音验证码、语音通知业务，通过状态通知接口将执行的结果信息异步回调给AS，以便AS能够掌握发送结果。