坐席资料绑定与分机外呼属性接口
适用于:第三方系统(OA/CRM/排班)把自家员工体系与 CTI 分机绑定——登录/上线时下发工号、姓名、部门、工作时间(
SET_WORKER_ID);为分机配置来电状态 HTTP 推送地址(弹屏,SET_CALLS_POP_UP_URL);设置 E1 线路外呼显示号码(SET_EXT_OUT_CALL_DSPLAY)与客户回拨直达(SET_EXT_DIRECT_CALL_BACK)。 配套:实时状态也可走 WebSocket 订阅(websocket-call-state,推荐);本组的 HTTP 推送适合无 WebSocket 条件的对接方。
所有接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体(README §3)。
1. 坐席上班绑定:SET_WORKER_ID
坐席在第三方系统登录/上班时调用,把工号等资料写入 CTI 分机(之后话单、监控、报表均以该工号呈现):
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&workerid=41735&department=%E7%A0%94%E5%8F%91&uname=%E5%A4%8F%E5%A4%A9&opt=SET_WORKER_ID
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| extnum | String | 是 | 坐席分机号 |
| workerid | String | 是 | 员工工号 |
| department | String | 否 | 部门/姓名备注(写入分机名称;需 URL 编码,服务端按系统类型解码) |
| uname | String | 否 | 坐席助手显示姓名(需 URL 编码) |
| officehours | String | 否 | 工作时间段,格式与 OMS 分机配置一致 |
| opt | String | 是 | 固定 SET_WORKER_ID |
| 业务码 | 含义 |
|---|---|
| 200 | 绑定成功 |
| 400 | 参数错误(extnum/workerid 缺失) |
| 404 | 分机不存在 |
| 420 | 目标不是分机(FXS)类型,不能绑定工号 |
注意:接口内部有约 2 秒等待(保证资料落库后再操作状态),响应偏慢是正常设计;绑定后建议间隔 2 秒以上再调示忙/示闲(ext-presence),否则可能异常。
2. 来电状态推送地址:SET_CALLS_POP_UP_URL
为分机设置呼叫状态 HTTP 推送 URL:该分机相关的通话每次状态变化(振铃/接通/挂机等),CTI 主动 GET 该 URL。等价于服务端推送版"来电弹屏",无需轮询。
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&domain=oa.example.com&urltype=http&port=8080&path=pop&extend=crm&opt=SET_CALLS_POP_UP_URL
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| extnum | String | 是 | 分机号;也可是已存在的话务组号(直接给整组配置) |
| domain | String | 是* | 接收推送的服务器地址(IP/域名)。不传 domain 再次调用 = 清除配置(见下) |
| urltype | String | 否 | 协议,缺省 http |
| port | String | 否 | 端口(数字) |
| path | String | 否 | 路径(不含开头 /) |
| extend | String | 否 | 附加业务参数,拼为 ?extend=<值> 原样随每次推送带回 |
| opt | String | 是 | 固定 SET_CALLS_POP_UP_URL |
拼接规则:urltype://domain[:port][/path][?extend=xxx],如上例得到 http://oa.example.com:8080/pop?extend=crm。
行为说明:
- 分机会被加入一个隐藏的单成员话务组(组名
state_notify_<分机号>),推送地址挂在组上;业务上无需关心该组,不要手工改动它; - 清除:对同一分机不带 domain 再调一次即可(删除推送组,返回 200);
extnum传话务组号时,直接对整组生效(组内所有成员的通话都推送);- 推送为异步 GET、无重试;CTI 内部推送队列满时会清空丢弃积压——接收端应快速应答,且不要把该推送当作唯一可靠信源(关键状态以话单查询兜底)。
| 业务码 | 含义 |
|---|---|
| 200 | 设置/清除成功 |
| 400 | 参数错误(extnum 缺失) |
| 404 | 分机/组不存在 |
2.1 推送报文格式(CTI → 第三方)
CTI 在每次状态变化时发起 HTTP GET(异步,不重试;推送 URL 已带 query 时以 & 续接):
http://oa.example.com:8080/pop?extend=crm&id=8db03e9d-...&caller=13512340001&callee=801&state=ringing&direction=incoming
| 参数 | 说明 |
|---|---|
| id | 通话唯一标识(call-id),同通电话多次推送保持一致 |
| caller / callee | 主叫 / 被叫号码 |
| state | 状态:init / calling / ringing / ringing_confirm / talking / hungup / canceled |
| direction | incoming(该方为被叫)/ outgoing(该方为主叫) |
| businessId | 可选,业务标识(如主叫业务 MAINCALL),有则带 |
| remote | 可选,对端真实号码(中继场景),有则带 |
典型用法:收到 state=ringing 且 direction=incoming 时按 caller 弹屏;talking 开始计时;hungup 后可查话单。
3. 外呼显示号码:E1 通道:SET_EXT_OUT_CALL_DSPLAY
分机外呼固定走指定 E1 通道(线路)并显示指定号码:
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&channel=2003&dspnum=75512345678&opt=SET_EXT_OUT_CALL_DSPLAY
| 参数 | 必填 | 说明 |
|---|---|---|
| extnum | 是 | 分机号 |
| channel | 是* | E1 外呼通道(线路号);channel 与 dspnum 都不传 = 清除绑定 |
| dspnum | 是* | 外呼时显示的号码 |
| opt | 是 | 固定 SET_EXT_OUT_CALL_DSPLAY |
业务码:200 成功 / 400 参数错误 / 404 分机不存在 / 420 非分机类型。
4. 客户回拨直达:SET_EXT_DIRECT_CALL_BACK
开启后,该分机外呼联系过的客户回拨外呼显示号码时,直接接到该分机(不再进 IVR/排队):
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&offon=true&opt=SET_EXT_DIRECT_CALL_BACK
| 参数 | 必填 | 说明 |
|---|---|---|
| extnum | 是 | 分机号 |
| offon | 是 | true 开启 / false 关闭 |
| opt | 是 | 固定 SET_EXT_DIRECT_CALL_BACK |
业务码:200 成功 / 400 参数错误 / 404 分机不存在 / 420 非分机类型。分机离线/忙时回拨行为按系统默认策略(转组/失败),以现场配置为准。
5. curl 示例(坐席上班全流程)
CTI=http://192.168.1.80:12121
# 1. 坐席上班:绑工号+部门+姓名(约2秒后返回)
curl "$CTI/bridge/callctrl?extnum=801&workerid=41735&department=%E7%A0%94%E5%8F%91&uname=%E5%A4%A4%E5%A4%A9&opt=SET_WORKER_ID"
# 2. 配置来电弹屏推送(接收端 8080/pop)
curl "$CTI/bridge/callctrl?extnum=801&domain=oa.example.com&port=8080&path=pop&extend=crm&opt=SET_CALLS_POP_UP_URL"
# 3. (可选)固定 E1 通道显示号码 + 开启回拨直达
curl "$CTI/bridge/callctrl?extnum=801&channel=2003&dspnum=75512345678&opt=SET_EXT_OUT_CALL_DSPLAY"
curl "$CTI/bridge/callctrl?extnum=801&offon=true&opt=SET_EXT_DIRECT_CALL_BACK"
# 4. 坐席下班:解除弹屏推送(不带 domain 即清除)
curl "$CTI/bridge/callctrl?extnum=801&opt=SET_CALLS_POP_UP_URL"
6. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| SET_WORKER_ID 响应慢(约2秒) | 内部设计(资料落库后等待 2 秒),非故障;不要并发重复提交 |
| 绑定工号后立即示忙失败 | 与内置 2 秒等待竞态;绑定调用返回后再等 2 秒操作状态 |
| 配了弹屏 URL 收不到推送 | 接收端须可被 CTI 服务器直接访问(防火墙放行);推送为 GET、无重试,接收端应快速应答;核对拼接出的完整 URL 是否可达 |
| 推送 URL 的 extend 丢失 | extend 拼在 ?extend= 上,若 URL 已含 ? 会以 & 续接,接收端按标准 query 解析即可 |
| 想同时要坐席忙闲状态 | 忙闲变化不在本推送范围,用 WebSocket 订阅(websocket-call-state)或 GET_EXT_PRESENCE_STATE 轮询(ext-presence) |
| SET_EXT_OUT_CALL_DSPLAY 返回 420 | 目标是话务组/中继而非 FXS 分机;只对模拟分机生效 |