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

语音回呼呼叫状态通知API

接口功能

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

请求方向

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

使用说明

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

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

接口类型

表1 接口类型说明

请求方法

POST

访问URI

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

通信协议

HTTPS/HTTP

语音回呼场景请求参数

语音回呼，也叫双向回呼，用户使用语音回呼软件呼叫另一方，语音通话平台依次呼叫主被叫号码，建立通话，实现主被叫号码间的点对点通信。

注：以下流程以用户A请求呼叫用户B，语音通话平台依次呼叫主叫号码A和被叫号码B，B用户接听为例。流程和接口示例仅供参考，请以实际消息为准。

表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、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。

注：

语音回呼业务：

  • 语音通话平台呼叫A时的呼出事件主叫号码为SP设置的主叫端来电显示号码（displayNbr）。
  • 语音通话平台呼叫B时的呼出事件主叫号码为SP设置的被叫端来电显示号码（displayCalleeNbr）。

called

否

String(1-32)

被叫号码。

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

注：语音回呼场景

  • 语音通话平台呼叫A时的呼出事件被叫号码为A。
  • 语音通话平台呼叫B时的呼出事件被叫号码为B。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"callout","statusInfo":{"sessionId":"1201_612_4294967295_20190124030424@callenabler245.huaweicaas.com","timestamp":"2019-01-24 03:04:24","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。

注：

语音回呼业务：

  • 语音通话平台呼叫A时的振铃事件主叫号码为SP设置的主叫端来电显示号码（displayNbr）。
  • 语音通话平台呼叫B时的振铃事件主叫号码为SP设置的被叫端来电显示号码（displayCalleeNbr）。

called

否

String(1-32)

被叫号码。

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

注：语音回呼场景

  • 语音通话平台呼叫A时的振铃事件被叫号码为A。
  • 语音通话平台呼叫B时的振铃事件被叫号码为B。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"alerting","statusInfo":{"sessionId":"1201_612_4294967295_20190124030424@callenabler245.huaweicaas.com","timestamp":"2019-01-24 03:04:26","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。

注：

语音回呼业务：

  • 语音通话平台呼叫A时的应答事件主叫号码为SP设置的主叫端来电显示号码（displayNbr）。
  • 语音通话平台呼叫B时的应答事件主叫号码为SP设置的被叫端来电显示号码（displayCalleeNbr）。

called

否

String(1-32)

被叫号码。

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

注：语音回呼场景

  • 语音通话平台呼叫A时的应答事件被叫号码为A。
  • 语音通话平台呼叫B时的应答事件被叫号码为B。

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"answer","statusInfo":{"sessionId":"1201_612_4294967295_20190124030424@callenabler245.huaweicaas.com","timestamp":"2019-01-24 03:04:31","caller":"+86138****0022","called":"+86138****0021"}}
表8 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。

注：

语音回呼业务：

若A先挂机，则挂机事件主叫号码为SP设置的主叫端来电显示号码（displayNbr）；若B先挂机，则挂机事件主叫号码为SP设置的被叫端来电显示号码（displayCalleeNbr）。

called

否

String(1-32)

被叫号码。

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

注：

语音回呼场景，若A先挂机，则挂机事件被叫号码为A号码；若B先挂机，则挂机事件被叫号码为B号码。

partyType

否

String(枚举)

当通知类型“eventType”为“disconnect”且客户调用“语音回呼场景API”时将“partyTypeRequiredInDisconnect”参数设置为“true”时才会携带。

取值范围如下：

  • caller：主叫
  • callee：被叫
  • platform：平台

stateCode

否

Integer

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

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

stateDesc

否

String(1-128)

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

接口示例

POST /status HTTP/1.1

Content-Length: xx 

{"eventType":"disconnect","statusInfo":{"sessionId":"1201_612_4294967295_20190124030424@callenabler245.huaweicaas.com","timestamp":"2019-01-24 03:04:49","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

相关文档