对外事件推送

获取事件推送的数据需要第三方系统提供一个接收七陌推送数据的接口，目前可推送的内容包括通话记录，坐席状态，满意度调查等。如需自行配置可群内联系负责对接的研发开通该权限，开通后登陆云客服系统即可在设置->对接->通话事件中自行配置，多个地址间用;（英文分号）分隔开。

1.通话状态推送

1.1 平台对外提供四类通话事件接口：

  • 呼叫振铃Ring(话务进入呼叫中心触发的事件)

  • 被呼振铃Ringing

  • 接通Link

  • 通话结束Hangup (Unlink也当成Hangup处理)

  • 示例如图：

注意：不同事件推送的参数会有所不同，如果只用来记录通话记录则只接收通话结束事件即可

1.2 通话接口可以提供如下数据

给第三方系统推送参数如下列表所示：

参数名 描述
CallNo 主叫号码
CalledNo 被叫号码
CallSheetID 通话记录ID,CallSheetID 是这条通话记录再DB中的唯一id
refCallSheetId 转接前通话的CallSheetID，可以用来定位转接电话的上一通通话
CallID 通话ID,通话连接的在系统中的唯一标识。CallID 是在通话进行中channel的id,可以用这个id来挂断通话之类的操作。一个channel有一个CallID,但一个call可能会出现在多个通话中,比如呼入转接。
CallType 通话类型：dialout外呼通话,normal普通来电,transfer呼入转接,dialTransfer外呼转接
Ring 通话振铃时间（话务进入呼叫中心系统的时间）
RingingDate 被叫振铃开始时间（呼入是按座席振铃的时间,外呼按用户振铃的时间）
Begin 通话接通时间（双方开始通话的时间,如果被叫没接听的话为空）
End 通话结束时间
QueueTime 来电进入技能组时间
Agent 处理坐席的工号
Exten 处理坐席的工号,历史原因该字段与Agent相同
AgentName 处理坐席的姓名
Queue 通话进入的技能组名称
State 接听状态：dealing（已接）,notDeal（振铃未接听）,leak（ivr放弃）,queueLeak（排队放弃）,blackList（黑名单）,voicemail（留言）,limit（并发限制）,failed (失败) 注意：只有dealing和voicemail状态的通话有录音，其他状态的通话录音地址不可用
CallState 事件状态：Ring, Ringing, Link, Hangup(Unlink也当成Hangup处理)
ActionID 通过调用外呼接口时,该字段会保存请求的actionID,其它情况下该字段为空
WebcallActionID 通过调用webcall接口,该字段会保存请求的actionID,其它情况下该字段为空
RecordFile 通话录音文件名：用户要访问录音时,在该文件名前面加上服务器路径即可,如：FileServer/RecordFile
FileServer 通过FileServer中指定的地址加上RecordFile的值可以获取录音
Province 目标号码的省,例如北京市。呼入为来电号码,呼出为去电号码
District 目标号码的市,例如北京市。呼入为来电号码,呼出为去电号码
IVRKEY 通话在系统中选择的按键菜单,10004@0。格式为：按键菜单的节点编号@选择的菜单按键。如果为多级菜单则为：10004@0-10005@1。
AccountId 账户编号字段,默认不推送有需求的用户对接时联系七陌技术支持人员进行开通
AccountName 账户名称字段,默认不推送有需求的用户对接时联系七陌技术支持人员进行开通
CdrVar 软电话条中的自定义参数，只有在软电话条中用CdrVar自定义id后才会有该字段。
DialoutStrVar 外呼接口和小号外呼接口中的自定义参数，只有在这两个接口中使用DialoutStrVar参数才会有该字段。
HangupPart agent 坐席挂机， customer 用户挂机，system 系统挂机
RealCalled 如果使用的是小号接口外呼或者CallCenter小号模式外呼，这里存放的是真实被叫，CalledNo存放的是小号。
MonitorFilename 录音文件地址，只有State=dealing 时才有该字段
Account 账户编号
RingingTimestamp 被叫振铃开始时间时间戳
TransferNum 转接后的技能组编号
EXTRA-UD-999 自定义字段信息，字段内容不要包含“：”和“；”，可传json字符串。如需使用该字段，请联系运维人员设置extra 参数。 如：Set(EXTRA-UD-999=${SIP_HEADER(EXTRA-UD-999)})

注意：录音下载地址为： FileServer+RecordFile。通话事件是实时推送，但是录音生成需要时间，生成时间根据通话时长和服务器压力而定，如需将录音拉取到本地，建议次日凌晨再进行拉取，拉取频率限制是1次/1s。如需立刻听取录音，建议直接使用我们默认地址进行听取。

1.3 事件推送对接示例

用户可以提供针对某个事件的接收url接口。当有事件产生时,平台会访问这个url,在url路径中传递参数。

如接收Hangup事件的url：

//此url仅为举例,实际url为平台使用者提供给七陌,并配置到云客服的接口  
www.xxxx.com/callback

系统在收到hangup事件时便会访问,并传递参数,如下例：

http://www.xxxx.com/callback?CallNo=01080455579&CallSheetID=5f7b40fc-5c70-4fbd-b191-973a5cf0b69e&CalledNo=18380462532&CallID=cc-ali-0-1566469352.884784&CallType=dialout&RecordFile=monitor%2Fbj.ali.3.7%2F20190822%2F20190822-182243_N00000022688__918380462532_cc-ali-0-1566469352.884784.mp3&Ring=2019-08-22+18%3A22%3A32&Begin=2019-08-22+18%3A22%3A50&End=2019-08-22+18%3A22%3A54&QueueTime=&Queue=&Agent=7000&Exten=7000&AgentName=7000&ActionID=&DialoutStrVar=&CallState=Unlink&State=dealing&FileServer=http%3A%2F%2F120.27.133.149&MonitorFilename=http%3A%2F%2F120.27.133.149%2Fmonitor%2Fbj.ali.3.7%2F20190822%2F20190822-182243_N00000022688__918380462532_cc-ali-0-1566469352.884784.mp3&CallStatus=dealing&RealState=Ringing&Province=%E5%9B%9B%E5%B7%9D%E7%9C%81&District=%E6%88%90%E9%83%BD%E5%B8%82&RingingTimestamp=1566469363.633871&RingingDate=2019-08-22+18%3A22%3A43

2.坐席状态推送

坐席状态接口提供坐席的上线/离线,置闲/置忙状态事件

2.1.坐席上线/离线

2.2.坐席置忙/置闲

接口提供的字段：

参数名 描述
Type 事件类型：login登录/登出,busy置忙/置闲
Exten 坐席工号,如8001
ExtenType 坐席登录方式,none|Local|sip|gateway：无电话方式|直线方式|软电话方式|网关方式
ChangeExtenTypeFlag 接听方式是否切换：true/false
State 状态：1（登录/置忙）,0（登出/置闲）
Agent 坐席
Time 发生时间
BusyType 置忙类型：0空闲，1忙碌,2小休,3-9（用户自定义）,97（呼叫中）,98 系统置忙（每个外呼或呼入通话接通时,系统都会将坐席置忙,等通话结束+后处理时长过后,系统会将坐席置成坐席的前一个状态）,99（通话中）
SendOrder before(前一条事件)，after(后一条事件)

3.满意度结果推送

来电成功进行满意度评价之后,7moor系统将调用接口,将评价的按键送给接口。

该接口提供的字段：

参数名 描述
CallSheetID 通话记录的唯一id,用来表示,这个满意度的结果是属于哪一通通话的。
SurveyContent 满意度按键的值

4.排队事件推送

通话进入技能组触发排队开始；坐席接听、溢出、主叫挂机，结束排队触发排队结束。
通过GET方式url传参请求第三方接口，可联系技术支持配置。
推送字段如下：

字段名 字段描述 示例
AccountId 账户id N00000022688
CustomerNumber 客户号码 18589258622
QueueNumber 技能组编号 10070579
QueueName 技能组名称 测试技能组
FirstQueueTime 加入技能组时间 1670919490.884063
QueueStartTime 技能组开始时间 1670919490.884063
CallUniqueId 通话id，通话唯一标识 cc-ali-0-1670919489.194754
EventUniqueId 事件唯一id 8b83b6d2-dc54-406a-8051-22025105326e
EventType 事件类型 queueJoin（加入技能组）、queueOverflow（溢出）、agentConnect（坐席接听）、queueCallerAbandon（主叫挂机）
QueueEndTime 技能组结束时间（排队结束时间） 1670919498.249059
说明：通过通话唯一标识识别当前通话，事件类型做判断排队 + -

排队开始：EventType=queueJoin。 排队结束：EventType=queueOverflow、agentConnect、queueCallerAbandon

5.IVR轨迹事件推送

呼入通话经过的IVR轨迹相关事件推送，其中包含日程、节点、技能组、坐席、挂机、满意度等 通过GET方式url传参请求第三方接口，可联系技术支持配置

推送字段如下：

字段名 是否必传 字段描述 示例
Account 是 本事件所属账户 N00000000449
Pbx 是 发生本事件的服务器名称 pbx.tx.test02.7
UniqueID 是 事件唯一ID cc-ali-0-1637306534.78
Channel 是 事件发生的通道名称【URLEncode】 SIP%2Fpansytest07-0000004e
ChannelType 是 事件发生的通道名称类型 normal
SequenceNum 是 事件位于本次话务中的位置 数字从1开始
Timestamp 是 事件发生的时间， 格式为【秒毫秒微秒】，乘以1000之后取整为毫秒时间戳 1637306534.993062
Location 是 事件发生时，话务所处位置，用来判断节点，IVR推送节点类型 取值见附表
LocationID 是 事件发生时，话务所处位置ID, 系统节点此参数为空字符串 10003
LocationName 是 事件发生时，话务所处位置名称【汉字为Unicode编码】 \u9ed8\u8ba4\u65e5\u7a0b
FromCID 是 主叫号码 10086
FromDID 是 被叫号码 10010
Linked 是 事件发生时通话是否已经接通 true/false
HangupUser 否 挂机特定参数，仅当 Linked 为true时 （通话已接听）本参数有值 agent、customer等
HangupCause 否 挂机特定参数，仅当Linked 为false时（通话已接听）本参数有值 16等

附表如下：

Location值 节点类型
time 服务号日程
announcement 播放语音节点
queue 技能组
hangup 系统节点挂机
peer 呼叫坐席
agent_hangup 坐席挂机
asrend 语音识别完成
textannouncement 播放文本节点
ivr 按键菜单节点
ivr-input 按键菜单节点，收到的按键输入
date 时间节点
validate 采集输入节点
assignment 赋值节点
twowaycall 双向回呼节点
encryptmd5 MD5加密节点
route 按变量路由节点
callurl CallUrl节点
voicemail 留言节点
room 会议室节点
satisfaction 满意度节点
ExtensionPeer 自定义节点
menu 转IVR菜单节点

6.事件推送失败重发功能

我们的事件推送支持失败重发,需要单独提出对您的账号开启事件失败重发功能,否则此功能默认不开启。

开启失败重发功能后,第三方接收消息的接口接收成功后需要返回给我们字符串200 。

如果我们推送后接口返回的值中不是字符串200,我们则认为第三方接口接收失败。进入重发流程,一条失败的消息,会在 10秒、30秒、60秒、600秒 后重发,直到第三方接口返回200。如果这4次重发都失败,我们将不会再重发。推送失败的消息我们会记录下来，第三方可以通过查询通话记录推送失败接口获取失败的记录。

7.查询通话记录推送失败接口

7.1 接口概述

该接口针对开启重推通话记录的账号，主要用来获取重推失败的通话记录。

7.2 接口请求

  • HTTP请求方式：POST
  • 请求链接：{HOST}/v20180426/cdr/getDispatcherFailureData/{ACCOUNTID}?sig={SIG}
  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名，{ACCOUNTID}替换为账户编号，{SIG}是根据鉴权规则生成的，请看鉴权文档，查看具体的生成规则
  • 鉴权方式：接口鉴权

7.3 接口参数

字段 类型 是否必须 备注
page int 是 当前页
pageSize int 是 每页多少条，最多1000条
failedBeginTime string 是 失败记录查询开始时间，格式yyyy-MM-dd HH:mm:ss
failedEndTime string 是 失败记录查询结束时间，格式yyyy-MM-dd HH:mm:ss

注意:查询时间区间为30天。

7.4 系统返回

返回Json对象，样例：

{
    "success": true,
    "data": [
        {
            "_id": "1b4465b6-310d-49fd-9f4f-10e1c236ce03",
            "url": "http://api.ilorry.xyz/hangup?CallNo=01080455992&CallSheetID=48cf3641-ed03-44b5-b499-08d42e1e1900&CalledNo=19940817951&CallID=cc-ali-0-1594918436.996189&CallType=dialout&RecordFile=monitor/bj.alixdf.1.3/20200717/20200717-005356_N00000015182_20754546_919940817951_cc-ali-0-1594918436.996189.mp3&Account=N00000015182&Ring=2020-07-17 00:53:56&Begin=2020-07-17 00:54:03&End=2020-07-17 00:54:07&QueueTime=&Queue=&HangupPart=customer&Agent=8021&Exten=8021&AgentName=8021&ActionID=&DialoutStrVar=&CallState=Unlink&State=dealing&FileServer=https://pbx-bj-xdf.7moor.com&MonitorFilename=https://pbx-bj-xdf.7moor.com/monitor/bj.alixdf.1.3/20200717/20200717-005356_N00000015182_20754546_919940817951_cc-ali-0-1594918436.996189.mp3&CallStatus=dealing&RealState=Ringing&Province=四川省&District=成都市&DistrictCode=028&RingingTimestamp=1594918436.763618&RingingDate=2020-07-17 00:53:56",
            "failedTime": "2020-07-17 00:54:14",
            "failedTimeStamp": "1594918454",
            "ip": "http://api.ilorry.xyz/hangup"
        }
    ]
}

返回值字段说明:

字段 类型 备注
_id string 推送事件id
url string 推送通话记录内容
failedTime string 推送失败时间
failedTimeStamp string 推送失败时间戳
ip string 推送地址

8 通话事件配置接口

第三方系统通过发送HTTP POST请求来定制通话事件推送，当平台产生相应的通话事件后，会向提供的接口推送与事件相对应的消息

8.1 接口请求

  • HTTP请求方式：POST
  • 请求链接：{HOST}/v20170704/callEvent/addCallEvent/{ACCOUNTID}?sig={SIG}
  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名，{ACCOUNTID}替换为账户编号，{SIG}是根据鉴权规则生成的，请看鉴权文档，查看具体的生成规则
  • 鉴权方式：接口鉴权

8.2 接口参数如下

参数名 类型 是否必填 描述
eventType String 是 CallEvent(固定不变)
concreteType String 是 定制事件类型：HanupURL(挂机)，RingURL(呼叫振铃)，RingingURL(被呼振铃)，LinkURL(接通)
url String 是 接收推送消息的地址，您这边提供的地址
name String 是 本条定制的名字，会在界面展示
pbx String 是 通话服务器编号：可以对接数据处查询
eventToken String 是 第三方认证（您这边的token，可以任意填值）
eventParam String 否 自定义推送参数 a:1,b:2,c:3….

请求示例

{
    "eventType": "CallEvent",
    "concreteType": "HanupURL",
    "url": "https://test.baidu.com/phonebridge/v3/callnotify",
    "name": "7Moor",
    "pbx": "XXX",
    "eventToken":"hsdfgj2638757273424",
    "eventParam": "zapikey:1003,appkey:1111"
}

8.3 系统返回

接口返回的response是一个json格式字符串，包含如下字段：

参数名 值 说明
Command Response 值固定不变
Response WebCall 值固定不变
ActionID 随机数 与调用接口时传的ActionID相同。如果调用接口时没传ActionID，则值是CallEvent+随机数。
Succeed true/false 本次接口调用是否成功。
Message 数字 a) 400 Error action缺少必传参数 b) 401 PBX not foundPBX参数有误 c) 500 Server error 服务器错误，请联系售后 e) 502 Account cc product not found 账号未开通云客服产品 f) 505 Service no can not fond 服务号没找到

400Response例子

{
  "Command":"Response",
  "Succeed":false,
  "Message":"400 Error action ",
  "ActionID":"CallEvent1382293010856915711",
  "Response":"CallEvent"
}

请求成功Response例子

{
    "Response": "EventInterfaceAddApi",
    "ActionID": "addCallEvent0.42021811901872375",
    "Message": null,
    "Command": "Response",
    "Succeed": true
}