# 语音通知话单通知API #### 接口功能 用户通话结束后，语音通话平台通过此接口向SP推送通话的话单信息。短时间内有多个通话结束时语音通话平台会将话单合并推送，每条消息最多携带50个话单。 #### 请求方向 语音通话平台（客户端） → 客户服务器（服务端） #### 使用说明 - 前提条件 - SP在开发应用时，若需订阅话单通知，必须要提供话单接收URL（feeUrl），并且确保URL能够正常处理语音通话平台发送的通知信息。 - 提供话单接收URL有以下两种方式： - 提前通过[应用管理](https://console.huaweicloud.com/voicecall/#/appManagement)向语音通话平台提交话单接收URL。 - SP应用调用场景API时，填写feeUrl参数。 - 注意事项 - 若平台给SP推送话单后未收到成功响应，视为推送失败，会**重新推送话单** ，直至客户返回成功响应。平台最多重推6次，**每次时间间隔1小时**。 - 单个用户（一路呼叫）的话单通知是根据呼叫状态顺序推送的，一通通话会推送一条话单。但同一个应用下，如果多个用户（多路呼叫）的**通话结束时间（callEndTime）相同** ，话单会**合并** 在一起发送，最多不超过**50**条。 - 使用限制 语音通话平台推送话单信息给开发者应用，仅支持POST方式。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限管理](https://support.huaweicloud.com/productdesc-VoiceCall/rtc_03_0011.html)。 #### 接口类型 表1接口类型说明 | 请求方法 | POST | |---|---| | **访问URI** | 开发者应用接收话单通知的URL | | **通信协议** | HTTPS/HTTP | 表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(枚举) | **参数解释：** 通知的事件类型。 **约束限制：** 不涉及。 **取值范围：** [fee：话单事件] **默认取值：** 不涉及。 | | feeLst | 否 | FeeInfo\[1-50\] | 呼叫话单事件的信息，参数取值为列表，最大50条。 当eventType参数为fee时携带。 | **FeeInfo** 表5fee：话单事件 | 参数名称 | 是否必须 | 参数类型 | 描述 | |:---|:---|:---|:---| | direction | 是 | Integer (0-1) | 通话的呼叫方向，以语音通话平台为基准。 - 0：外呼 - 1：回呼 | | spId | 是 | String(1-32) | 客户的云服务账号。 | | appKey | 是 | String(1-32) | **参数解释：** 语音通话应用的appKey。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | icid | 否 | String(1-64) | 呼叫记录的唯一标识。 | | bindNum | 是 | String(1-32) | 发起此次呼叫的固话号码。 号码仅支持全局号码格式（包含国家码），比如+8675528\*\*\*\*02。 | | sessionId | 是 | String(1-256) | 通话链路的唯一标识。 | | callerNum | 是 | String(1-32) | 主叫号码，号码为全局号码格式（包含国家码），比如+86138\*\*\*\*0021。 注：callerNum为SP设置的来电显示号码（displayNbr）。 | | calleeNum | 是 | String(1-128) | 被叫号码，号码为全局号码格式（包含国家码），比如+86138\*\*\*\*0021。 注：calleeNum为A号码。 | | callEndTime | 否 | String(1-128) | 呼叫结束时间。 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | fwdUnaswRsn | 否 | Integer | 转接呼叫操作失败的Q850原因值。详细说明参见[附录1-Q850原因值说明](https://support.huaweicloud.com/api-VoiceCall/rtc_05_0018.html)。 | | failTime | 否 | String(1-128) | 呼入、呼出的失败时间。 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | ulFailReason | 否 | Integer | 通话失败的拆线点。详细说明参见[附录2-呼叫拆线点说明](https://support.huaweicloud.com/api-VoiceCall/rtc_05_0019.html)。 | | sipStatusCode | 否 | Integer | 呼入、呼出的失败SIP状态码。 | | callOutStartTime | 否 | String(1-128) | Initcall的呼出开始时间 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | callOutAlertingTime | 否 | String(1-128) | Initcall的呼出振铃时间 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | callOutAnswerTime | 否 | String(1-128) | Initcall的呼出应答时间 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | callOutUnaswRsn | 否 | Integer | Initcall的呼出失败的Q850原因值。 详细说明参见[附录1-Q850原因值说明](https://support.huaweicloud.com/api-VoiceCall/rtc_05_0018.html)。 | | dynIVRStartTime | 否 | String(1-128) | 自定义动态IVR开始时间。 该参数为UTC时间（+8小时为北京时间），时间格式为"yyyy-MM-dd HH:mm:ss"。 | | dynIVRPath | 否 | String(1-256) | 自定义动态IVR按键路径。 用户每次的按键之间使用"-"链接，形式如下： 0-2-3． | | recordFlag | 否 | Integer (0-1) | 该字段用于录音标识，参数值范围如： - 0：表示未录音 - 1：表示有录音 | | ttsPlayTimes | 否 | integer | 应用TTS功能时，使用TTS的总次数。 | | ttsTransDuration | 否 | integer | 应用TTS功能时，TTS Server进行TTS转换的总时长。单位为秒。 | | serviceType | 否 | String(1-32) | **参数解释：** 呼叫的业务类型。 **约束限制：** 不涉及。 **取值范围：** 001：语音通知。 **默认取值：** 不涉及。 | | hostName | 否 | String(1-128) | 该参数用于标识话单生成的服务器设备对应的主机名。 | | userData | 否 | String(0-256) | 用户附属信息，此参数的值与"语音通知API"中的"userData"参数值一致。 | 响应示例 ``` POST /status HTTP/1.1 Content-Length: xx {"eventType":"fee","feeLst":[{"direction":0,"spId":"CaaS_Test_01","appKey":"x0GexpPpyRKhbA7ZC7kXBN8uX8vl","icid":"CAE-20190124104846-12028700","bindNum":"+8675528****02","sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","callerNum":"+86138****0022","calleeNum":"+86138****0021","callEndTime":"2019-01-24 02:49:23","fwdUnaswRsn":0,"ulFailReason":0,"sipStatusCode":0,"callOutStartTime":"2019-01-24 02:48:46","callOutAlertingTime":"2019-01-24 02:48:51","callOutAnswerTime":"2019-01-24 02:49:12","callOutUnaswRsn":0,"recordFlag":0,"ttsPlayTimes":1,"ttsTransDuration":1,"serviceType":"001","hostName":"callenabler245.huaweicaas.com"}]} ``` #### 响应参数 接收到话单通知时，第三方服务器返回200响应，同时若携带[表6]中的响应参数，系统则会根据resultcode参数值判断是否推送成功。 表6响应消息参数说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | resultcode | 否 | String(0-32) | 请求返回的结果码。 - 0为成功 - 其他均为失败 | | resultdesc | 否 | String(0-128) | 请求返回的结果描述。 | 响应示例 ``` HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"resultcode":"0","resultdesc":"Success"} ``` #### 代码样例 前往[代码样例](https://support.huaweicloud.com/devg-VoiceCall/rtc_04_0018.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)