1.專線語音回調通知AS接口介紹

玖云平臺針對專線語音業務提供了四種不同的回調接口通知，分別為A路及B路呼叫發起通知、呼叫建立通知、呼叫掛機計費通知。用戶可通過這些通知實時獲取通話狀態，并在呼叫結束后獲取本次通話的話單詳情。

回調通知接口為用戶開發的服務器接口，玖云平臺在通話的不同階段通過POST方式請求用戶的AS服務器，向用戶發起通知。

回調通知接口示例代碼（即Demo）下載

2.回調通知AS接口接入及使用流程

接入流程

(1).創建應用并配置用戶的AS服務器地址即回調地址
(2).用戶AS服務器端開發相應接口
(3).開始使用

使用流程

(1).用戶發起專線語音呼叫請求，并請求成功
(2).平臺發起A路呼叫
(3).平臺請求用戶配置的回調地址，通知A路呼叫發起
(4).A路接聽，平臺發起B路呼叫
(5).平臺請求用戶配置的回調地址，通知B路呼叫發起
(6).B路接聽，呼叫正常建立
(7).平臺請求用戶配置的回調地址，通知呼叫建立
(8).A路或B路掛機，通話結束
(9).平臺請求用戶配置的回調地址，通知呼叫結束，并返回詳細話單 REST接口請求成功后，呼叫過程中出現任意異常，平臺都會請求用戶配置的回調地址，通知呼叫結束，并返回詳細話單
(10).REST接口請求成功后，呼叫過程中出現任意異常，平臺都會請求用戶配置的回調地址，通知呼叫結束，并返回詳細話單

3.回調通知AS接口詳述

呼叫發起通知接口

此接口用于呼叫發起的時候，平臺通知用戶AS服務器。平臺呼叫A路及B路是會分別發出通知。

請求地址

用戶創建應用時自行配置URL地址。通過POST方式請求通知用戶，只提供XML格式。

請求包頭

屬性	類型	約束	說明
Content-Type	String	必選	類型application/xml
Content-Length	String	必選	消息體的長度

請求包體

屬性	類型	約束	描述	取值
action	String	必選	請求類型	CallInvite
type	int	必選	呼叫類型	1:專線語音
appId	String	必選	應用ID	應用ID
caller	String	必選	主叫號碼	type取值為1時，主叫號碼為電話號碼
called	String	必選	被叫號碼	type取值為1時，被叫號碼為電話號碼
userFlag	int	必選	A，B路標識	0標識A路（主叫），1標識B路（被叫）
subType	int	必選	外呼顯號標示	0:不顯號 1:一方顯號 2:雙方均顯號（取值為2僅雙向回撥時存在）
callId	String	必選	呼叫的唯一標示	32位字符串
dateCreated	String	必選	請求時間	回調用戶的時間
userData	String	可選	用戶數據	用戶自定義數據，最長可支持128字節。如用戶在回撥REST請求接口中傳入，則回調會將數據原樣回調給客戶，否則為空

參數說明：

(1)action：回調通知的類型
(2)subType：顯號標識
(3)callId：與REST請求返回的callId一致
(4)userFlag：區別是主叫產生的回調，還是被叫產生的回調
(5)userData：用戶回調REST接口中傳入的數據

用戶AS響應包頭

屬性	類型	約束	描述	舉例
Status-Code	String	必選	應答狀態碼，全部為200	HTTP/1.1 200 OK
Date	String	可選	服務器時間	Wed Nov 9 16:08:57 2011
Content-Length	String	必選	消息體的長度	140

用戶AS響應包體

屬性	類型	約束	描述	取值
StatusCode	String	必選	響應結果	用戶返回錯誤碼 0000表示成功，目前平臺不對此字段進行解析
statusMsg	String	可選	響應結果描述	用戶自定義描述，目前平臺不對此字段進行解析

回調請求示例

XML請求示例

    <?xml version='1.0'?>
    <req>
        <action>CallInvite</action>
        <type>1</type>
        <appId>feff3cbd52c041a1bd5b0492bee56423</appId>
        <caller>13912345678</caller>
        <called>13812345678</called>
        <userFlag>0</userFlag>
        <subType>0</subType>
        <callId>420d9ec4557f4eeabfb003983d5b2049</callId>
        <dateCreated>20160324175622</dateCreated>
        <userData>abcdef</userData>
    </req>
                        

用戶響應示例

XML響應示例

    <?xml version='1.0' encoding='utf-8'?>
    <Response>
       <statusCode>0000</statuscode>
       <statusMsg>Success</statusMsg>
    </Response>
                        

呼叫建立通知接口

此接口用于B路（被叫）接聽后，通話建立成功的時候。平臺通知用戶AS服務器呼叫已經建立。

請求地址

用戶創建應用時自行配置URL地址。通過POST方式請求通知用戶，只提供XML格式。

請求包頭

屬性	類型	約束	說明
Content-Type	String	必選	類型application/xml
Content-Length	String	必選	消息體的長度

請求包體

屬性	類型	約束	描述	取值
action	String	必選	請求類型	CallEstablish
type	int	必選	呼叫類型	1:專線語音
appId	String	必選	應用ID	應用ID
caller	String	必選	主叫號碼	type取值為1時，主叫號碼為電話號碼
called	String	必選	被叫號碼	type取值為1時，被叫號碼為電話號碼
subType	int	必選	外呼顯號標示	0:不顯號 1:一方顯號 2:雙方均顯號（取值為2僅雙向回撥時存在）
callId	String	必選	呼叫的唯一標示	32位字符串
dateCreated	String	必選	請求時間	回調用戶的時間
userData	String	可選	用戶數據	用戶自定義數據，最長可支持128字節。如用戶在回撥REST請求接口中傳入，則回調會將數據原樣回調給客戶

參數說明：

(1)action：回調類型標記
(2)subType：顯號標識
(3)callId：與REST請求返回的callId一致

用戶AS響應包頭

屬性	類型	約束	描述	舉例
Status-Code	String	必選	應答狀態碼，全部為200	HTTP/1.1 200 OK
Date	String	可選	服務器時間	Wed Nov 9 16:08:57 2011
Content-Length	String	必選	消息體的長度	140

用戶AS響應包體

屬性	類型	約束	描述	取值
StatusCode	String	必選	認證授權結果	用戶返回錯誤碼 0000表示成功，目前平臺不對此字段進行解析
statusMsg	String	可選	認證結果描述	用戶自定義描述，目前平臺不對此字段進行解析

回調請求示例

XML請求示例

    <?xml version='1.0'?>
    <req>
        <action>CallEstablish</action>
        <type>1</type>
        <appId>feff3cbd52c041a1bd5b0492bee56423</appId>
        <caller>13912345678</caller>
        <called>13812345678</called>
        <subType>0</subType>
        <callId>420d9ec4557f4eeabfb003983d5b2049</callId>
        <dateCreated>20160324175652</dateCreated>
        <userData>{"test":"test"}</userData>
    </req>
                        

用戶響應示例

XML響應示例

    <?xml version='1.0' encoding='utf-8'?>
    <Response>
       <statusCode>0000</statuscode>
       <statusMsg>Success</statusMsg>
    </Response>
                        

呼叫掛機計費通知接口

此接口用于呼叫斷開的時候，平臺通知用戶AS服務器。包括正常斷開以及異常斷開情況，通話詳細話單也在此回調接口中一起返回。

請求地址

用戶創建應用時自行配置URL地址。通過POST方式請求通知用戶，只提供XML格式。

請求包頭

屬性	類型	約束	說明
Content-Type	String	必選	類型application/xml
Content-Length	String	必選	消息體的長度

請求包體

屬性	類型	約束	描述	取值
action	String	必選	請求類型	Hangup
type	int	必選	呼叫類型	1:專線語音
appId	String	必選	應用ID
caller	String	必選	主叫號碼	type取值為1時，主叫號碼為電話號碼
called	String	必選	被叫號碼	type取值為1時，被叫號碼為電話號碼
startTimeA	String	必選	回撥時，為主叫接聽時間；	YYYYMMDDHH24MISS20130212000256
startTimeB	String	必選	回撥時，為被叫接聽時間；	YYYYMMDDHH24MISS20130212000256
endTime	String	必選	通話結束時間	YYYYMMDDHH24MISS
duration	String	必選	通話時長。回撥時，如被叫接聽，通話建立，則為B路接聽到結束的時間。如被叫未接聽，則為0	單位：秒
subType	String	必選	外呼顯號標示	0:不顯號 1:一方顯號 2:雙方均顯號（取值為2僅雙向回撥時存在）
callId	String	必選	呼叫的唯一標示	32位字符串
recordUrl	String	可選	回撥時，通話錄音完整下載地址。url需要以.mp3為后綴	若未開啟錄音則默認空
byeType	String	必選	通話掛機類型	0:正常掛斷 1:A無法接通 2:B無法接通 3:A目標忙 4:B目標忙 5:通話達到最大時長 6:服務器錯誤 7:網絡錯誤 255:其他錯誤
dateCreated	String	必選	請求時間	回調用戶的時間
userData	String	可選	用戶數據	用戶自定義數據，最長可支持128字節。如用戶在回撥REST請求接口中傳入，則回調會將數據原樣回調給客戶

參數說明：

(1)subType：顯號標識
(2)callId：與REST請求返回的callId一致
(3)recordUrl：如開啟錄音業務，則此處會返回錄音下載地址
(4)byeType：掛機原因，包含正常掛機及異常掛機多種情況

用戶AS響應包頭

屬性	類型	約束	描述	舉例
Status-Code	String	必選	應答狀態碼，全部為200	HTTP/1.1 200 OK
Date	String	可選	服務器時間	Wed Nov 9 16:08:57 2011
Content-Length	String	必選	消息體的長度	140

用戶AS響應包體

屬性	類型	約束	描述	取值
StatusCode	String	必選	認證授權結果	用戶返回錯誤碼 0000表示成功，目前平臺不對此字段進行解析
statusMsg	String	可選	認證結果描述	用戶自定義描述，目前平臺不對此字段進行解析

回調請求示例

XML請求示例

    <?xml version='1.0'?>
    <req>
        <action>Hangup</action>
        <type>1</type>
        <appId>feff3cbd52c041a1bd5b0492bee56423</appId>
        <caller>13912345678</caller>
        <called>13812345678</called>
        <subType>0</subType>
        <callId>feff3cbd52c041a1bd5b0492bee56423</callId>
        <dateCreated>20160324180031</dateCreated>
        <userData>{"test":"test"}</userData>
        <startTimeA>20160324180016</startTimeA>
        <startTimeB>20160324180022</startTimeB>
        <endTime>20160324180031</endTime>
        <duration>9</duration>
        <recordUrl></recordUrl>
        <byeType>200</byeType>
    </req>
                        

用戶響應示例

XML響應示例

    <?xml version='1.0' encoding='utf-8'?>
    <Response>
       <statusCode>0000</statuscode>
       <statusMsg>Success</statusMsg>
    </Response>