专线语音回调通知接口
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>
                        

1 回调AS接口介绍

2 回调AS使用流程

3 回调AS接口详述