文档首页 > > API参考> X模式>

X模式呼叫事件通知接口

X模式呼叫事件通知接口

分享
更新时间:2021/04/16 GMT+08:00

接口功能

隐私保护通话平台通过此接口向客户推送隐私保护通话用户呼叫时的状态信息,如呼入、呼出、振铃、应答、挂机等状态的信息。

呼叫状态通知分为Notify模式和Block模式:

  • Notify:通知模式,客户收到通知后返回HTTP状态码为200的空消息即可。
  • Block:控制模式,客户需按照接口说明返回响应参数。

请求方向

隐私保护通话平台(服务端) → 客户服务器(客户端)

使用说明

前提条件

客户添加应用时需设置呼叫状态接收地址,并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。

如果需要单独接收呼入事件(callin),需联系客服,提供呼入事件状态接收地址。

若需要使用X模式自定义放音,需要提前在放音文件管理页面上传并等待审核通过。

使用限制

业务平台推送呼叫状态给开发者应用,仅支持POST方式。

注意事项

  • 若平台给客户推送呼叫事件通知(不包括callin事件以外的其他呼叫事件)后未收到成功响应,视为推送失败,平台会重新推送呼叫事件通知,直至客户返回成功响应。平台最多重推6次,分别于1分钟、4分钟、9分钟、106分钟、203分钟和300分钟后重推。
  • X模式支持单次通话进行的最长时间(收到callin事件后,返回对呼叫事件的处理操作时设置maxDuration参数),到期后系统自动挂断通话。
  • 若要使用录音功能,需要完成以下两个步骤:
    1. 修改X模式应用,“是否开通录音”选择“是”。

    2. 返回对呼叫事件的处理操作时设置“recordFlag”为“true”。

  • 若要使用短信功能,需要完成以下两个步骤:
    1. 修改X模式应用,“是否开通短信”选择“是”;

    2. 订购用于X模式应用的号码时,“是否需要短信功能”选择“是”

接口类型

表1 接口类型说明

请求方法

POST

访问URI

客户添加应用时填写的呼叫状态接收地址

通信协议

HTTPS/HTTP

请求参数

X模式中,任意用户呼叫隐私号码X,隐私保护通话平台接收到呼叫后,根据客户服务器返回的绑定关系转接或挂断呼叫。

注:以下流程和接口示例以A用户呼叫X,企业服务器返回被叫号码B,B用户接听为例,流程和接口示例仅供参考,请以实际消息为准。

图1 X模式业务流程
表2 请求Headers参数说明

参数名称

是否必选

参数类型

说明

Content-Type

String

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

Authorization

String

固定填写为WSSE realm="SDP",profile="UsernameToken",type="Appkey"。

X-WSSE

String

取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
  • PasswordDigest:根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成。其中,Password为APP_Secret的值。Nonce、Created、Password直接进行字符串拼接即可,无需包含+号和空格。
  • 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(枚举)

该参数标识通知的事件类型。

取值范围如下:

  • callin:呼入事件
  • callout:呼出事件
  • alerting:振铃事件
  • answer:应答事件
  • disconnect:挂机事件

statusInfo

CallStatusInfo

呼叫状态事件的信息。

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

CallStatusInfo定义
表5 callin:呼入事件

参数名称

是否必选

参数类型

说明

timestamp

String(1-128)

该呼叫事件发生时隐私保护通话平台的UNIX时间戳。

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

sessionId

String(1-256)

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

caller

String(1-32)

主叫号码。

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

注:呼入事件的主叫号码为A号码。

called

String(1-32)

被叫号码。

注:呼入事件的被叫号码为X号码。

notifyMode

String(1-32)

通知模式,仅X模式场景携带。

取值范围如下:

  • Notify:通知模式,客户收到通知后返回HTTP状态码为200的空消息即可。
  • Block:控制模式,客户需按照接口说明返回响应参数。

不携带该参数时,通知模式为Notify。

接口示例

POST /status HTTP/1.1




content-length:xx
 

{"eventType":"callin","statusInfo":{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"2019-01-03 03:11:18","caller":"+86138****0021","called":"+86138****0022","notifyMode":"Block"}}

注:客户若收到Block模式的事件通知,需按照接口说明返回响应参数,指示对呼叫事件的处理操作(接口说明见Block模式)。此处以客户服务器回复接续被叫号码B为例。

HTTP/1.1 200 

Content-Length: xx 

{"connectInfo":{"lastMinVoice":"lastMinVoice001.wav","userData":"d77b5e3cbd234159af401d63f559f896","displayCalleeNum":"+86138****0022","recordFlag":true,"calleeNum":"+86138****7021","maxDuration":0,"recordHintTone":"recordHintTone001.wav","waitVoice":"waitVoice001.wav"},"operation":"connect","userData":"d77b5e3cbd234159af401d63f559f896"}
表6 callout:呼出事件

参数名称

是否必选

参数类型

说明

timestamp

String(1-128)

该呼叫事件发生时隐私保护通话平台的UNIX时间戳。

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

sessionId

String(1-256)

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

caller

String(1-32)

主叫号码。

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

注:呼出事件的主叫号码为X号码。

called

String(1-32)

被叫号码。

注:呼出事件的被叫号码为B号码。

subscriptionId

String(1-64)

绑定ID。

userData

String(1-256)

用户附属信息。

当客户在该接口Block模式响应参数中携带了"userData"时,对应呼叫后续的通知消息中都会携带此参数。

接口示例

POST /status HTTP/1.1




content-length:xx
 

{"eventType":"callout","statusInfo":{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"2019-01-03 03:11:20","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f896","subscriptionId":"********"}}
表7 alerting:振铃事件

参数名称

是否必选

参数类型

说明

timestamp

String(1-128)

该呼叫事件发生时隐私保护通话平台的UNIX时间戳。

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

userData

String(1-256)

用户附属信息。

当客户在该接口Block模式响应参数中携带了"userData"时,对应呼叫后续的通知消息中都会携带此参数。

sessionId

String(1-256)

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

caller

String(1-32)

主叫号码。

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

注:振铃事件的主叫号码为X号码。

called

String(1-32)

被叫号码。

注:振铃事件的被叫号码为B号码。

subscriptionId

String(1-64)

绑定ID。

接口示例

POST /status HTTP/1.1




content-length:xx
 

{"eventType":"alerting","statusInfo":{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"2019-01-03 03:11:21","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f896","subscriptionId":"********"}}
表8 answer:应答事件

参数名称

是否必选

参数类型

说明

timestamp

String(1-128)

该呼叫事件发生时隐私保护通话平台的UNIX时间戳。

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

userData

String(1-256)

用户附属信息。

当客户在该接口Block模式响应参数中携带了"userData"时,对应呼叫后续的通知消息中都会携带此参数。

sessionId

String(1-256)

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

caller

String(1-32)

主叫号码。

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

注:应答事件的主叫号码为X号码。

called

String(1-32)

被叫号码。

注:应答事件的被叫号码为B号码。

subscriptionId

String(1-64)

绑定ID。

接口示例

POST /status HTTP/1.1




content-length:xx
 

{"eventType":"answer","statusInfo":{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"2019-01-03 03:11:22","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f896","subscriptionId":"********"}}
表9 disconnect:挂机事件

参数名称

是否必选

参数类型

说明

timestamp

String(1-128)

该呼叫事件发生时隐私保护通话平台的UNIX时间戳。

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

userData

String(1-256)

用户附属信息。

当客户在该接口Block模式响应参数中携带了"userData"时,对应呼叫后续的通知消息中都会携带此参数。

sessionId

String(1-256)

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

caller

String(1-32)

主叫号码。

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

注:此处返回号码非真实主被叫号码,真实主被叫号码请以fee事件中的返回值为准。

called

String(1-32)

被叫号码。

注:此处返回号码非真实主被叫号码,真实主被叫号码请以fee事件中的返回值为准。

stateCode

Integer

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

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

stateDesc

String(1-128)

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

subscriptionId

String(1-64)

绑定ID。

接口示例

POST /status HTTP/1.1




content-length:xx
 
{"eventType":"disconnect","statusInfo":{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"2019-01-03 03:11:42","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f896","stateCode":0,"stateDesc":"The user releases the call.","subscriptionId":"********"}}

响应参数

客户服务器接收到隐私保护通话平台的呼叫事件通知后,根据不同的模式返回不同响应消息。

  • Notify模式

    返回无消息体的200响应。

    消息样例

    HTTP/1.1 200 OK 
  • Block模式
    响应必须参照表10携带消息体,返回对呼叫事件的处理操作。
    表10 响应消息参数说明

    参数名称

    是否必选

    参数类型

    说明

    operation

    String(1-32)

    用于指示平台的呼叫操作。取值范围如下:

    • connect:接续被叫通话。
    • close:结束本次呼叫。

    connectInfo

    ApiConnectInfo

    指示平台接续被叫通话的参数列表。

    当operation取值为connect时携带。

    closeInfo

    ApiCloseInfo

    指示平台结束会话的参数列表。

    当operation取值为close时携带。

    表11 ApiConnectInfo定义

    参数名称

    是否必选

    参数类型

    说明

    displayCalleeNum

    String(4-31)

    被叫端的来显号码,填写为真实主叫号码或客户应用下申请任意X号码

    填写为全局号码格式。

    • 手机号码格式为国家码(如+86)+手机号码(如138****0001),填写为"+86138****0001"。
    • 固话号码为国家码(如+86)+不带前置0的区号(如755)+本地固话号码(如28****01),填写为"+8675528****01"。

    不携带该参数时,默认显示本次呼叫的X号码。

    注:由于运营商管控,当前平台要求该参数必须设置为X号码,否则呼叫会被运营商拦截。

    calleeNum

    String(4-31)

    真实被叫号码。

    填写为全局号码格式。

    • 手机号码格式为国家码(如+86)+手机号码(如138****0001),填写为"+86138****0001"。
    • 固话号码为国家码(如+86)+不带前置0的区号(如755)+本地固话号码(如28****01),填写为"+8675528****01"。

    maxDuration

    Integer

    设置允许本次通话进行的最长时间,单位:分钟,通话时间从接通被叫的时刻开始计算。

    取值范围:0~1440

    • 0:系统不主动结束通话,由主被叫双方结束通话。
    • 1~1440:当通话时长达到此配置值,系统主动结束通话。

    不携带时,参数值默认为0。

    waitVoice

    String(0-128)

    设置个性化通话前等待音,即主叫听到的回铃音。填写为放音文件名,可在放音文件管理页面查看。

    不携带该参数时主叫会听到真实被叫的回铃音。

    recordFlag

    String(枚举)

    是否需要针对本次通话录音。

    • false:表示不录音
    • true:表示录音。

    该参数仅当客户添加应用时申请开通了录音功能才有效。

    如果不携带该参数,系统默认不录音。

    recordHintTone

    String(0-128)

    此参数仅在recordFlag为true时有效。

    此字段用于设置录音提示音,填写为放音文件名,可在放音文件管理页面查看。

    不携带该参数表示录音前不播放提示音。

    注:因隐私协议及运营商管控,录音的呼叫必须携带该参数,否则呼叫会被运营商拦截。

    lastMinVoice

    String(0-128)

    设置通话剩余最后一分钟时的提示音,填写为放音文件名,可在放音文件管理页面查看。

    当maxDuration字段设置为非0时此参数有效。

    不携带该参数表示通话剩余最后一分钟时不放音。

    calleeHintVoice

    String(0-128)

    该参数用于设置被叫提示音,即通话接通后优先向被叫用户播放提示音。填写为放音文件名,可在放音文件管理页面查看。

    不携带该参数表示不优先向被叫用户播放提示音。

    userData

    String(0-256)

    用户自定义数据,会在该次通话的后续状态报告和话单中原样返回。

    • 不允许携带以下字符:“{”,“}”(即大括号)。
    • 不允许包含中文字符,如果包含中文字符请采用Base64编码。

    注:当X模式callin事件响应中的userData包含中文时,平台会终止呼叫接续。

    表12 ApiCloseInfo定义

    参数名称

    是否必选

    参数类型

    说明

    closeHintTone

    String(1-128)

    设置挂机提示音,即主叫被挂机前听到的提示音。

    填写为放音文件名,可在放音文件管理页面查看。

    不携带该参数时系统挂机前不放音。

    userData

    String(1-256)

    用户自定义数据,会在该次通话的后续状态报告和话单中原样返回。

    • 不允许携带以下字符:“{”,“}”(即大括号)。
    • 不允许包含中文字符,如果包含中文字符请采用Base64编码。

    注:当X模式callin事件响应中的userData包含中文时,平台会终止呼叫接续。

消息样例

  • 接续被叫通话
    HTTP/1.1 200 OK
    
    Content-Type: application/JSON;charset=UTF-8
    Content-Length: xx
    
    {"operation":"connect",
    "connectInfo":{"calleeNum":"+86156****6201","maxDuration":0,"waitVoice":"waitVoice.wav","recordFlag":"true","recordHintTone":"recordHintTone.wav","userData":"testuserdate"}}
  • 结束本次呼叫
    HTTP/1.1 200 OK
    
    Content-Type: application/JSON;charset=UTF-8
    Content-Length: xx
    
    {"operation":"close",
    "closeInfo":{"closeHintTone":"closeHintTone.wav","userData":"testuserdate"}}
分享:

    相关文档

    相关产品