文档首页/ 语音通话 VoiceCall/ API参考/ 语音通知API/ 语音通知呼叫状态通知API
更新时间：2022-09-16 GMT+08:00
查看PDF
分享

语音通知呼叫状态通知API

接口功能

语音通话平台通过此接口向客户推送语音通话业务用户呼叫时的状态信息，如呼入、呼出、振铃、应答、挂机等状态的信息。

请求方向

语音通话平台（客户端） → 客户服务器（服务端）

使用说明

  • 前提条件
    • SP在开发应用时，若需订阅呼叫状态通知，必须要提供呼叫状态接收URL（statusUrl），并且确保URL能够正常处理语音通话平台发送的通知信息。
    • 提供呼叫状态接收URL有以下两种方式：
      • 提前通过应用管理向语音通话平台提交呼叫状态接收URL。
      • SP应用调用场景API时，填写statusUrl。
  • 使用限制

    语音通话平台推送呼叫状态给开发者应用，仅支持POST方式。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

开发者应用接收呼叫状态URL

通信协议

HTTPS/HTTP

请求参数

SP调用语音通知API，语音通话平台发起呼叫，给用户播放自定义的语音文件或TTS合成语音文件，并可进行收号，获得应答信息并反馈给SP。

注：以下流程以语音通话平台呼叫A，给A播放语音文件并收号为例。流程和接口示例仅供参考，请以实际消息为准。

表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事件通知的类型。取值范围如下：

statusInfo

否

CallStatusInfo

呼叫状态事件的信息。

当eventType参数为callout、alerting、answer、collectInfo、disconnect时携带。

CallStatusInfo

表5 callout：呼出事件

参数名称

是否必选

参数类型

说明

timestamp

是

String(1-128)

该呼叫事件发生时语音通话平台的UNIX时间戳。

该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。

userData

否

String(1-256)

用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。

sessionId

是

String(1-256)

唯一指定一条通话链路的标识ID。

caller

否

String(1-32)

主叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：呼出事件的主叫号码为SP设置的来电显示号码（displayNbr）。

called

否

String(1-32)

被叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：呼出事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"callout","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:48:46","caller":"+86138****0022","called":"+86138****0021"}}
表6 alerting：振铃事件

参数名称

是否必选

参数类型

说明

timestamp

是

String(1-128)

该呼叫事件发生时语音通话平台的UNIX时间戳。

该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。

userData

否

String(1-256)

用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。

sessionId

是

String(1-256)

唯一指定一条通话链路的标识ID。

caller

否

String(1-32)

主叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：振铃事件的主叫号码为SP设置的来电显示号码（displayNbr）。

called

否

String(1-32)

被叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：振铃事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"alerting","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:48:47","caller":"+86138****0022","called":"+86138****0021"}}
表7 answer：应答事件

参数名称

是否必选

参数类型

说明

timestamp

是

String(1-128)

该呼叫事件发生时语音通话平台的UNIX时间戳。

该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。

userData

否

String(1-256)

用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。

sessionId

是

String(1-256)

唯一指定一条通话链路的标识ID。

caller

否

String(1-32)

主叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：应答事件的主叫号码为SP设置的来电显示号码（displayNbr）。

called

否

String(1-32)

被叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：应答事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"answer","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:12","caller":"+86138****0022","called":"+86138****0021"}}
表8 collectInfo：放音收号结果事件

参数名称

是否必选

参数类型

说明

timestamp

是

String(1-128)

该呼叫事件发生时语音通话平台的UNIX时间戳。

该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。

sessionId

是

String(1-256)

唯一指定一条通话链路的标识ID。

digitInfo

否

String(1-64)

语音通知场景中携带收号的结果。（即用户输入的数字）

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"collectInfo","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:12","digitInfo":"02"}}
表9 disconnect：挂机事件

参数名称

是否必选

参数类型

说明

timestamp

是

String(1-128)

该呼叫事件发生时语音通话平台的UNIX时间戳。

该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。

userData

否

String(1-256)

用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。

sessionId

是

String(1-256)

唯一指定一条通话链路的标识ID。

caller

否

String(1-32)

主叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：挂机事件的主叫号码为SP设置的来电显示号码（displayNbr）。

called

否

String(1-32)

被叫号码。

号码仅支持全局号码格式（包含国家码），比如+86138****7021。

注：挂机事件的被叫号码为A号码。

stateCode

否

Integer

通话挂机的原因值，仅当eventType为disconnect时携带。

取值范围及表示的含义请参考通话挂机原因值说明。

stateDesc

否

String(1-128)

通话挂机的原因值的描述，仅当eventType为disconnect时携带。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"disconnect","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:23","caller":"+86138****0022","called":"+86138****0021","stateCode":0,"stateDesc":"The user releases the call."}}

响应参数

接收到事件通知时，第三方服务器响应返回200则为成功，否则语音通话平台会认为推送失败。

响应示例 
HTTP/1.1 200 OK 
Content-Type: application/json;charset=UTF-8

代码样例

前往代码样例查看。

常见问题

父主题： 语音通知API

相关文档