分机示忙示闲接口(SET_EXT_PRESENCE_STATE)

适用于:OA/CRM 弹屏录单等场景,坐席录入客户信息期间临时置忙话机,让话务组暂停向该分机分发来电;保存退出后置闲恢复接听。 配套:配合 websocket-call-state 订阅 presence 事件,可实时刷新坐席忙闲看板;配合 agent-supervision 的 EXTNUM_MONITOR 可轮询忙闲。

1. 状态语义与对来话的影响

分机在线状态共三个可设置值(存于分机属性,重启后仍保留):

注意:置忙影响的是话务组/排队分发。点对点直呼该分机的呼叫路径不经过组分发,置忙不改变其行为。

2. 设置忙闲状态(SET_EXT_PRESENCE_STATE)

GET http://{cti_host}:12121/bridge/callctrl?extnum=801&state=busy&reason=LeaveSeat&opt=SET_EXT_PRESENCE_STATE

{cti_host}:12121 为 CTI 服务器 HTTP 地址,12121 为默认端口,以现场配置为准。GET 与 POST 等价(服务端 POST 委托给 GET 处理)。

响应

HTTP 状态码恒为 200,业务结果写在响应体(纯文本业务码,与全部 /bridge/callctrl 接口一致,见 README §3.1):

curl 示例

# 弹屏时置忙
curl "http://192.168.1.80:12121/bridge/callctrl?extnum=801&state=busy&reason=LeaveSeat&opt=SET_EXT_PRESENCE_STATE"

# 录单保存后置闲
curl "http://192.168.1.80:12121/bridge/callctrl?extnum=801&state=online&opt=SET_EXT_PRESENCE_STATE"

# 坐席临时改为少接来电(仍保留在话务组)
curl "http://192.168.1.80:12121/bridge/callctrl?extnum=801&state=reducing&opt=SET_EXT_PRESENCE_STATE"

# 带中文原因(UTF-8 percent-encoding)
curl "http://192.168.1.80:12121/bridge/callctrl?extnum=801&state=busy&reason=%E5%BD%95%E5%8D%95%E4%B8%AD&opt=SET_EXT_PRESENCE_STATE"

调用模式建议

弹屏生命周期内"置忙 → 业务完成 → 置闲"必须成对调用:置忙后未置闲,该分机将持续不被分配来电。客户端崩溃/关页导致漏发置闲时,可用 GET 接口(见 §3)配合看板核查,或由坐席手动恢复。接口幂等,重复设置相同状态无副作用。

3. 查询分机忙闲状态(GET_EXT_PRESENCE_STATE)

GET http://{cti_host}:12121/bridge/callctrl?extnum=801&opt=GET_EXT_PRESENCE_STATE

分机存在时响应体(注意:键名无引号的非严格 JSON,不要用严格 JSON 解析器,建议正则提取):

{"extnum":"801", "state":"online", "expired":false}

分机不存在或查询失败时,响应体为文本 unkown。

4. 设置成功后的服务端联动

一次成功的 SET 会触发以下动作,对接方可据此设计下游逻辑:

1. 状态持久化:写入分机表(presentstate/presencereason/presencetime),重启不丢;
2. WebSocket presence 通知:向订阅该分机的客户端推送 {"extnum":"801","state":"busy","sceenShowType":"presence"}(字段 sceenShowType 为历史拼写,勿改;见 websocket-call-state §4.2);
3. 操作日志:写入后台操作日志,操作人取坐席助手登录名/工号/分机号;置忙时服务端自动附加备注(offduty 下班置忙 / working 通话置忙 / rest 闲时置忙),与 reason 参数相互独立;
4. 话务统计打点:就绪/案面时长统计(置闲且空闲时打就绪起点)。

5. 常见问题排查