坐席监管接口(状态监控 / 监听 / 强插 / 强拆)
适用于:班组长/主管在 OA/CRM 中实时监控坐席通话状态,并对坐席通话执行监听(只听不说)、强插(直接接管通话)、强拆(强制挂断)。 前置条件:执行操作的主管分机需在呼叫中心后台开通"坐席监控"权限(分机管理中设置),否则返回 403。
1. 总体流程
┌─ 轮询坐席状态(EXTNUM_MONITOR,建议 2 秒)──▶ 找到"谁在通话"(state=BUSY_*、remoteNum 非空)
│
└─ 对选中坐席执行 ──▶ CALL_MONITOR 监听(主管分机收听)
FORCE_PICKUP 强插(主管分机接管通话)
FORCE_HUNGUP 强拆(挂断坐席与客户的通话)
监听/强插/强拆都是触发型接口:调用后由 CTI 呼叫主管的分机(leaderExtnum),主管话机振铃,接听后生效。三个接口的参数完全相同,仅 opt 不同。
2. 坐席状态监控(EXTNUM_MONITOR)
查询各分机的实时状态(注册、忙闲、通话对端、置忙状态等),是监管类功能的数据源。
GET http://{cti_host}:12121/bridge/jsoncfg?opt=EXTNUM_MONITOR&json={URL编码后的JSON}
| 参数 | 必填 | 说明 |
|---|---|---|
| opt | 是 | 固定 EXTNUM_MONITOR |
| json | 是 | 查询条件 JSON,整体 URL 编码后传递,字段见下表 |
json 条件字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| assisLogId | String | 是 | 登录标识。无账号体系时可自拟一个全局唯一值,后续轮询保持不变 |
| extnums | String | 否 | 分机号或分组号数组,不传查全部分机 |
| first | Integer | 否 | 页码(从 0 开始),注意不是行偏移;第 N 页传 N-1 |
| maxResults | Integer | 否 | 每页条数(first 有效时必填,>0) |
| condition | String | 否 | 按分机姓名/号码模糊过滤 |
| avoidCallPerform | Integer | 否 | 1 不统计绩效(高性能,监管页用这个);0 统计坐席绩效(慢,勿高频轮询) |
| starttime | String | 否 | 绩效统计起始时间 yyyy-MM-dd HH:mm:ss(avoidCallPerform=0 时有意义) |
| exceptextnum | String | 否 | 排除的分机号 |
示例(json 原文):
{"assisLogId":"oa-monitor-001","first":0,"maxResults":15,"condition":"","avoidCallPerform":1}
URL 编码后:
GET http://{cti_host}:12121/bridge/jsoncfg?opt=EXTNUM_MONITOR&json=%7B%22assisLogId%22%3A%22oa-monitor-001%22%2C%22first%22%3A0%2C%22maxResults%22%3A15%2C%22avoidCallPerform%22%3A1%7D
响应示例
[
{
"assisname": "小张",
"extnumname": "分机6",
"department": "分机6",
"worknum": "013",
"extnum": "806",
"phoneType": "NewRock_NRP1000_2.3.1654.528",
"telRegState": 1,
"state": "BUSY_INCOMING",
"remoteNum": "15875566080",
"pickupTime": "17:49:00",
"pickupDuration": "8",
"presence": "online",
"presencereason": "",
"missingCallCount": 0,
"outgoingCallCount": 0,
"incomingCallCount": 0,
"incomingMissedCount": 0,
"complaintCount": 0,
"total": 0
}
]
字段说明
| 字段 | 说明 |
|---|---|
| extnum | 分机号 |
| extnumname / department | 分机显示名 / 部门 |
| assisname / worknum | 绑定坐席姓名 / 工号 |
| phoneType | 终端设备类型 |
| telRegState | 注册状态:0 未注册 / 1 已注册 |
| state | 话机忙闲:IDEL 空闲(拼写即如此)/ BUSY_OUTGOING 外呼通话中 / BUSY_INCOMING 接听通话中 / OFFLINE 离线 |
| remoteNum | 通话中的对端号码(空闲时无此字段) |
| pickupTime / pickupDuration | 接听时间(HH:mm:ss)/ 已通话秒数 |
| presence | 坐席自设状态:online/busy/reducing/unkown |
| presencereason | 最近一次置状态的原因 |
| missingCallCount 等 | 漏接/呼出/呼入/未接/投诉计数(avoidCallPerform=0 时统计) |
| total | 过滤后总条数(分页时;取第一条即可) |
选做监听/强插/强拆的目标条件:state 为 BUSY_OUTGOING 或 BUSY_INCOMING(即"正在通话"),此时 remoteNum 为该坐席的客户号码。
3. 监听(CALL_MONITOR)
坐席与客户通话中,主管分机接入只听不说,坐席与客户无感知:
GET http://{cti_host}:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=CALL_MONITOR
| 参数 | 必填 | 说明 |
|---|---|---|
| leaderExtnum | 是 | 主管的分机号码(接听收听用,须有"坐席监控"权限且当前空闲) |
| wokerExtnum | 是 | 被监听的分机号码(拼写即如此,不是 workerExtnum) |
| opt | 是 | 固定 CALL_MONITOR |
行为:调用成功后主管分机振铃,接听即开始收听坐席与客户的通话;挂机即退出监听,原通话不受影响。
4. 强插(FORCE_PICKUP)
主管直接接管坐席的通话(替代坐席与客户沟通);对坐席接听的来电和坐席的外呼都有效:
GET http://{cti_host}:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=FORCE_PICKUP
参数同监听。行为:主管分机振铃,接听后坐席被请出通话,主管与客户直接沟通。
5. 强拆(FORCE_HUNGUP)
挂断坐席与客户之间的通话:
GET http://{cti_host}:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=FORCE_HUNGUP
参数同监听。行为:坐席与客户的通话立即被挂断(主管分机不响铃,leaderExtnum 仅用于权限校验)。
6. 三接口共同说明
HTTP 状态码恒为 200,业务码写在响应体(纯文本):
| 业务码 | 含义与处理 |
|---|---|
| 200 | 操作成功(监听/强插:主管话机即将振铃,请注意接听) |
| 400 | 参数错误(缺 leaderExtnum/wokerExtnum) |
| 403 | 主管分机无"坐席监控"权限 → 到呼叫中心后台"分机管理"中为该分机添加权限 |
| 404 | 目标坐席当前没有可操作的通话(刷新状态后再试) |
| 480 | 主管分机离线/未注册 |
| 486 | 主管分机忙(正在通话,无法监听/强插) |
| 503 | 系统资源不足 |
约束与建议:
- 不能对自己操作(
leaderExtnum == wokerExtnum时界面应禁止)。 - 监听/强插需要主管保持空闲并守在话机旁,建议操作前检查主管分机状态(EXTNUM_MONITOR 里查 leaderExtnum 的
state)。 - 监管页轮询 EXTNUM_MONITOR 建议 2 秒一次,
avoidCallPerform=1;assisLogId全程不变。
7. curl 示例
# 查询所有坐席当前状态(第 1 页,每页 15 条,高性能模式)
curl "http://192.168.1.80:12121/bridge/jsoncfg?opt=EXTNUM_MONITOR&json=%7B%22assisLogId%22%3A%22oa-monitor-001%22%2C%22first%22%3A0%2C%22maxResults%22%3A15%2C%22avoidCallPerform%22%3A1%7D"
# 监听 801 的通话(主管分机 803)
curl "http://192.168.1.80:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=CALL_MONITOR"
# 强插接管 801 的通话
curl "http://192.168.1.80:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=FORCE_PICKUP"
# 强拆 801 的通话
curl "http://192.168.1.80:12121/bridge/callctrl?leaderExtnum=803&wokerExtnum=801&opt=FORCE_HUNGUP"
8. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| 403 | 主管分机无"坐席监控"权限,后台分机管理中添加 |
| 404 | 目标坐席没在通话:先轮询 EXTNUM_MONITOR 确认 state=BUSY_* 再操作 |
| 480 | 主管分机离线:话机断电/未注册,查 telRegState |
| 486 | 主管分机正在通话:先结束自己的通话 |
| 监听接通但听不到声音 | 检查主管话机音量/静音键;确认被监听通话仍在进行 |
| json 参数报错/返回 | json 必须 URL 编码;assisLogId 为空时直接返回 [] |