# 语音回呼呼叫状态通知API #### 接口功能 语音通话平台通过此接口向客户推送语音通话业务用户呼叫时的状态信息，如呼入、呼出、振铃、应答、挂机等状态的信息。 #### 请求方向 语音通话平台（客户端） → 客户服务器（服务端） #### 使用说明 - 前提条件 - SP在开发应用时，若需订阅呼叫状态通知，必须要提供呼叫状态接收URL（statusUrl），并且确保URL能够正常处理语音通话平台发送的通知信息。 - 提供呼叫状态接收URL有以下两种方式： - 提前通过[应用管理](https://console.huaweicloud.com/voicecall/#/appManagement)向语音通话平台提交呼叫状态接收URL。 - SP应用调用场景API时，填写statusUrl。 - 使用限制 语音通话平台推送呼叫状态给开发者应用，仅支持POST方式。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限管理](https://support.huaweicloud.com/productdesc-VoiceCall/rtc_03_0011.html)。 #### 接口类型 表1接口类型说明 | 请求方法 | POST | |---|---| | **访问URI** | 开发者应用接收呼叫状态URL | | **通信协议** | HTTPS/HTTP | #### 语音回呼场景请求参数 语音回呼，也叫双向回呼，用户使用语音回呼软件呼叫另一方，语音通话平台依次呼叫主被叫号码，建立通话，实现主被叫号码间的点对点通信。 注：以下流程以用户A请求呼叫用户B，语音通话平台依次呼叫主叫号码A和被叫号码B，B用户接听为例。流程和接口示例仅供参考，请以实际消息为准。 ![](https://support.huaweicloud.com/api-VoiceCall/figure/zh-cn_image_0284631780.png "点击放大") 表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+"\\n"+安全随机数+"\\n"+时间戳))生成。其中，url使用客户设置的话单推送URL，随机数需使用安全随机数。 - Nonce：客户发送请求时生成的一个随机数，长度为1\~128位，可包含数字和大小写字母。例如：66C92B11FF8A425FB8D4CCFE0ED9ED1F。 - Created：随机数生成时间。采用UTC+8(北京时间)格式，例如：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(枚举) | **参数解释：** 通知的事件类型。 **约束限制：** 不涉及。 **取值范围：** - [callout：呼出事件] - [alerting：振铃事件] - [answer：应答事件] - [disconnect：挂机事件] **默认取值：** 不涉及。 | | statusInfo | 否 | CallStatusInfo | 呼叫状态事件的信息。 当eventType参数为callout、alerting、answer、disconnect时携带。 | **CallStatusInfo** 表5callout：呼出事件 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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"}} ``` 表6alerting：振铃事件 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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"}} ``` 表7answer：应答事件 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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"}} ``` 表8disconnect：挂机事件 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | 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时携带。 取值范围及表示的含义请参考[通话挂机原因值说明](https://support.huaweicloud.com/api-VoiceCall/rtc_05_0022_1.html)。 | | 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 ``` #### 代码样例 前往[代码样例](https://support.huaweicloud.com/devg-VoiceCall/rtc_04_0014.html)查看。 #### 常见问题 - [如何配置和接收呼叫状态和话单通知？地址是否支持http？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00026.html) - [呼叫状态和话单通知什么时候推送？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00009.html) - [呼叫状态和话单通知多个用户如何推送？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00010.html) - [接收呼叫状态和话单通知后需要返回响应消息吗？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00011.html) - [接收呼叫状态和话单通知，参数区分大小写吗？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00012.html) - [语音通话的呼叫状态通知和话单通知支持重推吗？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_0000_11.html) - [语音通话的通话记录如何获取？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00037.html) - [为什么没有收到呼叫状态通知和话单通知？](https://support.huaweicloud.com/VoiceCall_faq/VoiceCall_faq_00003.html)