响应参数 客户服务器接收到 隐私保护通话 平台的呼叫事件通知后，根据不同的模式返回不同响应消息。 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"}}

请求参数 X模式中，任意用户呼叫隐私号码X，隐私保护通话平台接收到呼叫后，根据客户服务器返回的绑定关系转接或挂断呼叫。 注：以下流程和接口示例以A用户呼叫X，企业服务器返回被叫号码B，B用户接听为例，流程和接口示例仅供参考，请以实际消息为准。 图1 X模式业务流程 表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-SHA256 (Password，Nonce + Created))生成。其中，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时携带。 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-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":"********"}}

使用说明 前提条件 客户添加应用时需设置呼叫状态接收地址，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。 如果需要单独接收呼入事件（callin），需联系客服，提供呼入事件状态接收地址。 若需要使用X模式自定义放音，需要提前在放音文件管理页面上传并等待审核通过。 使用限制 业务平台推送呼叫状态给开发者应用，仅支持POST方式。 注意事项 若平台给客户推送呼叫事件通知（不包括callin事件以外的其他呼叫事件）后未收到成功响应，视为推送失败，平台会重新推送呼叫事件通知，直至客户返回成功响应。平台最多重推6次，分别于1分钟、4分钟、9分钟、106分钟、203分钟和300分钟后重推。 若没有收到平台推送请参考收不到呼叫事件和话单通知如何处理？ X模式支持单次通话进行的最长时间（收到callin事件后，返回对呼叫事件的处理操作时设置maxDuration参数），到期后系统自动挂断通话。 若要使用录音功能，需要完成以下两个步骤： 修改X模式应用，“是否开通录音”选择“是”。 返回对呼叫事件的处理操作时设置“recordFlag”为“true”。 若要使用短信功能，需要完成以下两个步骤： 修改X模式应用，“是否开通短信”选择“是”； 订购用于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(枚举) 该参数标识通知的事件类型。 取值范围如下： numStatus：X号码状态变化 numInfo 否 numInfo [1-100] X号码状态变化事件的信息，参数取值为列表，最大100条。 当eventType参数为numStatus时携带。 表5 numInfo定义 参数名称 是否必须 参数类型 说明 number 是 String 状态变化的X号码。 status 是 String 号码状态。 5：正常 9：暂停 10：不可用 11：冻结绑定 说明： 各号码状态对业务的影响如下： 正常：无影响。 暂停&不可用：绑定、呼叫和短信都不可用。 冻结绑定：号码不可新增绑定关系，但已存在的绑定关系的呼叫和短信业务不受影响。 cause 否 String 号码不可用原因。仅status为不可用时携带。 1：号码已删除 2：欠费 3：停机 5：X号码被运营商限呼 6：X号码限呼恢复 7：X号码开通了无条件前转业务 8：X号码开通了无应答前转业务 9：X号码开通了被叫忙前转业务 接口示例 POST /Xnumber/status HTTP/1.1 Content-Length: 94 content-type: application/json;charset=UTF-8 authorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey" x-wsse: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z" {"eventType":"numStatus","numInfo":[{"number":"+86156****0000","status":"9"}]}

使用说明 前提条件 客户添加应用时需设置呼叫状态接收地址并启用推送X号码状态功能，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。 注：若需单独接收X号码状态通知，需填写X号码状态接收地址。若呼叫状态接收地址和X号码状态接收地址都填写了，隐私保护通话平台会向呼叫状态接收地址推送呼叫事件通知，向X号码状态接收地址推送X号码状态通知。 使用限制 业务平台推送呼叫状态给开发者应用，仅支持POST方式。

API请求地址 API请求地址由“APP接入地址”和“访问URI”组成，数据来源如下： 参数 来源 示例 APP接入地址 登录管理控制台，从隐私保护通话“应用管理”页面获取。 https://rtcpns.cn-north-1.myhuaweicloud.com 访问URI 从各API接口页面中的“接口类型说明”中获取。 获取录音文件下载地址接口 ：/rest/provision/voice/record/v1.0 综上，API请求地址示例如下： 获取录音文件下载地址接口 https://rtcpns.cn-north-1.myhuaweicloud.com/rest/provision/voice/record/v1.0