X模式呼叫事件通知接口

接口功能

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

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

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

请求方向

隐私保护通话平台（服务端） → 客户服务器（客户端）

使用说明

前提条件

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

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

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

使用限制

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

• X模式支持单次通话进行的最长时间（收到callin事件后，返回对呼叫事件的处理操作时设置maxDuration参数），到期后系统自动挂断通话。
• 若要使用录音功能，需要完成以下两个步骤：

  1. 修改X模式应用，“是否开通录音”选择“是”。

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

• 若要使用短信功能，需要完成以下两个步骤：

  1. 修改X模式应用，“是否开通短信”选择“是”；

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

接口类型

请求参数

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

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

图1 X模式业务流程

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-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
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-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
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-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
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-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
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。
callRelDirection	否	Integer	主被叫通话结束后的挂机方向。 1：主叫主动挂机 2：被叫主动挂机 说明： 使用该参数的场景请联系华为云客服获取。

接口示例

POST /status HTTP/1.1

content-type: application/json;charset=UTF-8
authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey"
x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
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）+手机号码（11位数字的手机号码，如138****0001），填写为"+86138****0001"。 固话号码为国家码（如+86）+不带前置0的区号（如755）+本地固话号码（7或8位数字的固话号码，以实际号码为准，如28****01），填写为"+8675528****01"。 不携带该参数时，默认显示本次呼叫的X号码。 说明： 由于运营商管控，当前平台要求该参数必须设置为呼叫使用的X号码，否则呼叫会被运营商拦截。 若想使用应用下申请的其他X号码作为外显号码，请联系华为云客服。
  calleeNum	是	String(4-31)	真实被叫号码。 填写为全局号码格式。 手机号码格式为国家码（如+86）+手机号码（11位数字的手机号码，如138****0001），填写为"+86138****0001"。 固话号码为国家码（如+86）+不带前置0的区号（如755）+本地固话号码（7或8位数字的固话号码，以实际号码为准，如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"}}