更新时间:2022-05-07 GMT+08:00
分享

语音验证码话单通知API

接口功能

用户通话结束后,语音通话平台通过此接口向SP推送通话的话单信息。短时间内有多个通话结束时语音通话平台会将话单合并推送,每条消息最多携带50个话单。

请求方向

语音通话平台(客户端) → 客户服务器(服务端)

使用说明

  • 前提条件
    • SP在开发应用时,若需订阅话单通知,必须要提供话单接收URL(feeUrl),并且确保URL能够正常处理语音通话平台发送的通知信息。
    • 提供话单接收URL有以下两种方式:
      • 提前通过应用管理向语音通话平台提交话单接收URL。
      • SP应用调用场景API时,填写feeUrl参数。
  • 注意事项
    • 若平台给SP推送话单后未收到成功响应,视为推送失败,会重新推送话单,直至客户返回成功响应。平台最多重推6次,每次时间间隔1小时
    • 单个用户(一路呼叫)的话单通知是根据呼叫状态顺序推送的,一通通话会推送一条话单。但同一个应用下,如果多个用户(多路呼叫)的通话结束时间(callEndTime)相同,话单会合并在一起发送,最多不超过50条。
  • 使用限制

    语音通话平台推送话单信息给开发者应用,仅支持POST方式。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

开发者应用接收话单通知的URL

通信协议

HTTPS/HTTP

表2 请求Headers参数说明

参数名称

是否必选

参数类型

说明

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="随机数生成时间"。
  • PasswordDigest:根据PasswordDigest = Base64(HMAC(appSecret, url+安全随机数+时间戳))生成。其中,url使用客户设置的话单推送URL,随机数需使用安全随机数。
  • Nonce:客户发送请求时生成的一个随机数,长度为1~128位,可包含数字和大小写字母。例如:66C92B11FF8A425FB8D4CCFE0ED9ED1F。
  • Created:随机数生成时间。采用标准UTC格式,例如:2018-02-12T15:30:20Z。不同编程语言中将UTC时间戳转换为普通时间时使用的格式不同,部分语言可参考表3
表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 请求Body参数说明

参数名称

是否必选

参数类型

说明

eventType

String(枚举)

该参数标识API事件通知的类型。取值范围如下:

fee:话单事件

feeLst

FeeInfo[1-50]

呼叫话单事件的信息,参数取值为列表,最大50条。

当eventType参数为fee时携带。

FeeInfo

表5 fee:话单事件

参数名称

是否必须

参数类型

默认值

描述

direction

Integer (0-1)

通话的呼叫方向,以语音通话平台为基准。

0表示呼出(外呼)

spId

String(1-32)

客户的云服务账号。

appKey

String(1-32)

应用的app_key。

icid

String(1-64)

呼叫记录的唯一标识。

bindNum

String(1-32)

发起此次呼叫的固话号码。

号码仅支持全局号码格式(包含国家码),比如+8675528****02

sessionId

String(1-256)

通话链路的唯一标识。

callerNum

String(1-32)

主叫号码,号码为全局号码格式(包含国家码),比如+86138****0021。

注:callerNum为SP设置的来电显示号码(displayNbr)。

calleeNum

String(1-128)

被叫号码,号码为全局号码格式(包含国家码),比如+86138****0021。

注:calleeNum为A号码。

callEndTime

String(1-128)

呼叫结束时间。

该参数为UTC时间(+8小时为北京时间),时间格式为“yyyy-MM-dd HH:mm:ss”。

fwdUnaswRsn

Integer

转接呼叫操作失败的Q850原因值。详细说明参见附录1-Q850原因值说明

failTime

String(1-128)

呼入、呼出的失败时间。

该参数为UTC时间(+8小时为北京时间),时间格式为“yyyy-MM-dd HH:mm:ss”。

ulFailReason

Integer

通话失败的拆线点。详细说明参见附录2-呼叫拆线点说明

sipStatusCode

Integer

呼入、呼出的失败SIP状态码。

callOutStartTime

String(1-128)

Initcall的呼出开始时间

该参数为UTC时间(+8小时为北京时间),时间格式为“yyyy-MM-dd HH:mm:ss”。

callOutAlertingTime

String(1-128)

Initcall的呼出振铃时间

该参数为UTC时间(+8小时为北京时间),时间格式为“yyyy-MM-dd HH:mm:ss”。

callOutAnswerTime

String(1-128)

Initcall的呼出应答时间

该参数为UTC时间(+8小时为北京时间),时间格式为“yyyy-MM-dd HH:mm:ss”。

callOutUnaswRsn

Integer

NA

Initcall的呼出失败的Q850原因值。

详细说明参见附录1-Q850原因值说明

recordFlag

Integer (0-1)

该字段用于录音标识,参数值范围如:

  • 0:表示未录音
  • 1:表示有录音

ttsPlayTimes

integer

应用TTS功能时,使用TTS的总次数。

ttsTransDuration

integer

应用TTS功能时,TTS Server进行TTS转换的总时长。单位为秒。

serviceType

String(1-32)

携带呼叫的业务类型信息,取值范围:

001:语音播放

hostName

String(1-128)

该参数用于标识话单生成的服务器设备对应的主机名。

userData

String(0-256)

用户附属信息,此参数的值与“语音验证码场景API”中的"userData"参数值一致。

响应示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"fee","feeLst":[{"direction":0,"spId":"CaaS_Test_01","appKey":"7VN6w60Pl3e1E5C8310517x32698","icid":"CAE-20190124105808-12009374","bindNum":"+8675528****02","sessionId":"1200_164_4294967295_20190124025808@callenabler245.huaweicaas.com","callerNum":"+86138****0021","calleeNum":"+86138****7021","callEndTime":"2019-01-24 02:58:36","fwdUnaswRsn":0,"ulFailReason":0,"sipStatusCode":0,"callOutStartTime":"2019-01-24 02:58:08","callOutAlertingTime":"2019-01-24 02:58:13","callOutAnswerTime":"2019-01-24 02:58:24","callOutUnaswRsn":0,"recordFlag":0,"ttsPlayTimes":0,"ttsTransDuration":0,"serviceType":"001","hostName":"callenabler245.huaweicaas.com"}]}

响应参数

接收到话单通知时,第三方服务器返回200响应,同时若携带表6中的响应参数,系统则会根据resultcode参数值判断是否推送成功。
表6 响应消息参数说明

参数名称

是否必选

参数类型

说明

resultcode

String(0-32)

请求返回的结果码。

  • 0为成功
  • 其他均为失败

resultdesc

String(0-128)

请求返回的结果描述。

响应示例
HTTP/1.1 200 OK 

Content-Type: application/json;charset=UTF-8

{"resultcode":"0","resultdesc":"Success"}

代码样例

前往代码样例查看。

分享:

    相关文档

    相关产品

close