注意事项
4 X 模式
4.2 X 模式呼叫事件通知接口
接口功能
隐私保护通话平台通过此接口向客户推送隐私保护通话用户呼叫时的状态信息，如呼 入、呼出、振铃、应答、挂机等状态的信息。
呼叫状态通知分为Notify模式和Block模式：
● Notify：通知模式，客户收到通知后返回HTTP状态码为200的空消息即可。
● Block：控制模式，客户需按照接口说明返回响应参数。
请求方向
隐私保护通话平台（服务端） → 客户服务器（客户端）
使用说明
前提条件
客户添加应用时需设置呼叫状态接收地址，并确保提供的地址能够正常处理隐私保护 通话平台发送的通知消息。
如果需要单独接收呼入事件（callin），需联系客服，提供呼入事件状态接收地址。
若需要使用X模式自定义放音，需要提前在放音文件管理页面上传并等待审核通过。
使用限制
业务平台推送呼叫状态给开发者应用，仅支持POST方式。
注意事项
● 若平台给客户推送呼叫事件通知（不包括callin事件以外的其他呼叫事件）后未收 到成功响应，视为推送失败，平台会重新推送呼叫事件通知，直至客户返回成功 响应。平台最多重推6次，分别于1分钟、4分钟、9分钟、106分钟、203分钟和 300分钟后重推。
● X模式支持单次通话进行的最长时间（收到callin事件后，返回对呼叫事件的处理 操作时设置maxDuration参数），到期后系统自动挂断通话。
● 若要使用录音功能，需要完成以下两个步骤：
a. 修改X模式应用，“是否开通录音”选择“是”。
b. 返回对呼叫事件的处理操作时设置“recordFlag”为“true”。
● 若要使用短信功能，需要完成以下两个步骤：
a. 修改X模式应用，“是否开通短信”选择“是”；
b. 订购用于X模式应用的号码时，“是否需要短信功能”选择“是”。
接口类型
表4-1 接口类型说明 请求方法 POST
访问URI 客户添加应用时填写的呼叫状态接收地址 通信协议 HTTPS/HTTP
请求参数
X模式中，任意用户呼叫隐私号码X，隐私保护通话平台接收到呼叫后，根据客户服务 器返回的绑定关系转接或挂断呼叫。
注：以下流程和接口示例以A用户呼叫X，企业服务器返回被叫号码B，B用户接听为 例，流程和接口示例仅供参考，请以实际消息为准。
图4-1 X 模式业务流程
表4-2 请求 Headers 参数说明 参数名称 是否
必选
参数类型 说明
Content-Type 是 String 固定填写为application/json;charset=UTF-8。
参数名称 是否 必选
参数类型 说明
Authoriza
tion 是 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时间戳转换为普通时间时使用的 格式不同，部分语言可参考表4-3。
表4-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-4 请求 Body 参数说明 参数名称 是否
必选
参数类型 说明
eventType 是 String(枚
举) 该参数标识通知的事件类型。
取值范围如下：
● callin：呼入事件
● callout：呼出事件
● alerting：振铃事件
● answer：应答事件
● disconnect：挂机事件 statusInfo 否 CallStatus
Info 呼叫状态事件的信息。
当eventType参数为callin、callout、alerting、
answer、disconnect时携带。
● callin：呼入事件
● callout：呼出事件
● alerting：振铃事件
● answer：应答事件
● disconnect：挂机事件
CallStatusInfo定义
表4-5 callin：呼入事件 参数名称 是否
必选
参数类型 说明
timestam
p 是 String(1-1
28) 该呼叫事件发生时隐私保护通话平台的UNIX时间 戳。
该参数取值为UTC时间（+8小时为北京时间）格 式，即为“yyyy-MM-dd HH:mm:ss”。
sessionId 是 String(1-2
56) 唯一指定一条通话链路的标识ID。
caller 否 String(1-3
2) 主叫号码。
号码为全局号码格式（包含国家码），如 +86138****0021。
说明呼入事件的主叫号码为A号码。
called 否 String(1-3
2) 被叫号码。
说明呼入事件的被叫号码为X号码。
参数名称 是否 必选
参数类型 说明
notifyMo
de 否 String(1-3
2) 通知模式，仅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":"201 9-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","displayCalleeNu m":"+86138****0022","recordFlag":true,"calleeNum":"+86138****7021","maxDuration":
0,"recordHintTone":"recordHintTone001.wav","waitVoice":"waitVoice001.wav"},"operation":"connect","userDa ta":"d77b5e3cbd234159af401d63f559f896"}
表4-6 callout：呼出事件 参数名称 是否
必选
参数类型 说明
timestam
p 是 String(1-1
28) 该呼叫事件发生时隐私保护通话平台的UNIX时间 戳。
该参数取值为UTC时间（+8小时为北京时间）格 式，即为“yyyy-MM-dd HH:mm:ss”。
sessionId 是 String(1-2
56) 唯一指定一条通话链路的标识ID。
caller 否 String(1-3
2) 主叫号码。
号码为全局号码格式（包含国家码），如 +86138****0021。
说明呼出事件的主叫号码为X号码。
参数名称 是否 必选
参数类型 说明
called 否 String(1-3
2) 被叫号码。
说明呼出事件的被叫号码为B号码。
subscripti
onId 否 String(1-6
4) 绑定ID。
userData 否 String(1-2
56) 用户附属信息。
当客户在该接口Block模式响应参数中携带了
“userData”时，对应呼叫后续的通知消息中都 会携带此参数。
接口示例
POST /status HTTP/1.1 content-length:xx
{"eventType":"callout","statusInfo":
{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"201 9-01-03
03:11:20","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f 896","subscriptionId":"********"}}
表4-7 alerting：振铃事件 参数名称 是否
必选
参数类型 说明
timestam
p 是 String(1-1
28) 该呼叫事件发生时隐私保护通话平台的UNIX时间 戳。
该参数取值为UTC时间（+8小时为北京时间）格 式，即为“yyyy-MM-dd HH:mm:ss”。
userData 否 String(1-2
56) 用户附属信息。
当客户在该接口Block模式响应参数中携带了
“userData”时，对应呼叫后续的通知消息中都 会携带此参数。
sessionId 是 String(1-2
56) 唯一指定一条通话链路的标识ID。
caller 否 String(1-3
2) 主叫号码。
号码为全局号码格式（包含国家码），如 +86138****0021。
说明振铃事件的主叫号码为X号码。
参数名称 是否 必选
参数类型 说明
called 否 String(1-3
2) 被叫号码。
说明振铃事件的被叫号码为B号码。
subscripti
onId 否 String(1-6
4) 绑定ID。
接口示例
POST /status HTTP/1.1 content-length:xx
{"eventType":"alerting","statusInfo":
{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"201 9-01-03
03:11:21","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f 896","subscriptionId":"********"}}
表4-8 answer：应答事件 参数名称 是否
必选
参数类型 说明
timestam
p 是 String(1-1
28) 该呼叫事件发生时隐私保护通话平台的UNIX时间 戳。
该参数取值为UTC时间（+8小时为北京时间）格 式，即为“yyyy-MM-dd HH:mm:ss”。
userData 否 String(1-2
56) 用户附属信息。
当客户在该接口Block模式响应参数中携带了
“userData”时，对应呼叫后续的通知消息中都 会携带此参数。
sessionId 是 String(1-2
56) 唯一指定一条通话链路的标识ID。
caller 否 String(1-3
2) 主叫号码。
号码为全局号码格式（包含国家码），如 +86138****0021。
说明应答事件的主叫号码为X号码。
called 否 String(1-3
2) 被叫号码。
说明应答事件的被叫号码为B号码。
subscripti
onId 否 String(1-6
4) 绑定ID。
接口示例
POST /status HTTP/1.1 content-length:xx
{"eventType":"answer","statusInfo":
{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"201 9-01-03
03:11:22","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f 896","subscriptionId":"********"}}
表4-9 disconnect：挂机事件 参数名称 是否
必选
参数类型 说明
timestam
p 是 String(1-1
28) 该呼叫事件发生时隐私保护通话平台的UNIX时间 戳。
该参数取值为UTC时间（+8小时为北京时间）格 式，即为“yyyy-MM-dd HH:mm:ss”。
userData 否 String(1-2
56) 用户附属信息。
当客户在该接口Block模式响应参数中携带了
“userData”时，对应呼叫后续的通知消息中都 会携带此参数。
sessionId 是 String(1-2
56) 唯一指定一条通话链路的标识ID。
caller 否 String(1-3
2) 主叫号码。
号码为全局号码格式（包含国家码），如 +86138****0021。
说明
此处返回号码非真实主被叫号码，真实主被叫号码请以 fee事件中的返回值为准。
called 否 String(1-3
2) 被叫号码。
说明
此处返回号码非真实主被叫号码，真实主被叫号码请以 fee事件中的返回值为准。
stateCode 否 Integer 通话挂机的原因值，仅当eventType为disconnect 时携带。
取值范围及表示的含义请参考通话挂机原因值说
明。
stateDesc 否 String(1-1
28) 通话挂机的原因值的描述，仅当eventType为 disconnect时携带。
subscripti
onId 否 String(1-6
4) 绑定ID。
参数名称 是否 必选
参数类型 说明
callRelDir
ection 否 Integer 主被叫通话结束后的挂机方向。
● 1：主叫主动挂机
● 2：被叫主动挂机 说明
使用该参数的场景请联系华为云客服获取。
接口示例
POST /status HTTP/1.1 content-length:xx
{"eventType":"disconnect","statusInfo":
{"sessionId":"1201_7767_4294967295_20190103031118@callenabler246.huaweicaas.com","timestamp":"201 9-01-03
03:11:42","caller":"+86138****0022","called":"+86138****7021","userData":"d77b5e3cbd234159af401d63f559f 896","stateCode":0,"stateDesc":"The user releases the call.","subscriptionId":"********"}}
响应参数
客户服务器接收到隐私保护通话平台的呼叫事件通知后，根据不同的模式返回不同响 应消息。
● Notify模式
返回无消息体的200响应。
消息样例
HTTP/1.1 200 OK
● Block模式
响应必须参照表4-10携带消息体，返回对呼叫事件的处理操作。
表4-10 响应消息参数说明 参数名称 是否
必选 参数类型 说明 operatio
n 否
String(1-32) 用于指示平台的呼叫操作。取值范围如下：
● connect：接续被叫通话。
● close：结束本次呼叫。
connectI
nfo 否 ApiConn
ectInfo 指示平台接续被叫通话的参数列表。
当operation取值为connect时携带。
closeInfo 否 ApiClose
Info 指示平台结束会话的参数列表。
当operation取值为close时携带。
表4-11 ApiConnectInfo 定义 参数名称 是否
必选
参数类型 说明
displayCa
lleeNum 否
String(4-31) 被叫端的来显号码，填写为真实主叫号码或呼 叫使用的X号码。
填写为全局号码格式。
● 手机号码格式为国家码（如+86）+手机号 码（11位数字的手机号码，如
138****0001），填写为
"+86138****0001"。
● 固话号码为国家码（如+86）+不带前置0的 区号（如755）+本地固话号码（7或8位数 字的固话号码，以实际号码为准，如 28****01），填写为"+8675528****01"。
不携带该参数时，默认显示本次呼叫的X号 码。
说明
● 由于运营商管控，当前平台要求该参数必须设置 为呼叫使用的X号码，否则呼叫会被运营商拦 截。
● 若想使用应用下申请的其他X号码作为外显号 码，请联系华为云客服。
calleeNu
m 是
String(4-31) 真实被叫号码。
填写为全局号码格式。
● 手机号码格式为国家码（如+86）+手机号 码（11位数字的手机号码，如
138****0001），填写为
"+86138****0001"。
● 固话号码为国家码（如+86）+不带前置0的
● 固话号码为国家码（如+86）+不带前置0的