电话转接接口(盲转 / 显转)
适用于:坐席通话中把当前通话转给另一个分机或外部号码。盲转一步完成、立即转话;显转先呼叫第三方并私下沟通,确认后再完成转接。 来源:官方 demo
WebPlugin/diapnl(src/components/HelloWorld.vue、ExtnumsState.vue、OutsideTransfer.vue)与官方《二次开发接口说明书》核对整理。 配套:配合 websocket-call-state 订阅坐席分机可实时观察转接各阶段的通话状态;显转涉及的CALL_THIRD系列在 conference 中有更完整的三方路径说明。
所有 callctrl 接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体(见 API 文档总览 通用约定)。
1. 盲转与显转对比
| 盲转(CLICK_TO_TRANSFER) | 显转(CALL_THIRD → CALL_THIRD_TRANSFER) | |
|---|---|---|
| 过程 | 一步直接把当前通话转给目标号码,坐席立即退出 | 先呼叫第三方(客户听等待音乐),坐席与第三方私下沟通后,再确认完成转接 |
| 坐席能否先与第三方通话 | 不能 | 能(沟通不满意可放弃并恢复原通话) |
| 适用场景 | 明确要转走,无需与接转方沟通(转分机、转外线) | 需要先把客户情况交代给接转方(如转给资深坐席) |
| 前置条件 | 坐席在响铃或通话中 | 坐席必须在通话中 |
| 接口数 | 1 个 | 2~3 个(呼叫第三方 → 确认转接 / 放弃恢复) |
demo 中"转接"页的盲转与"转出"页的转出共用同一接口 CLICK_TO_TRANSFER,仅 target 取值不同(分机号 / 外部号码)。
2. 盲转:CLICK_TO_TRANSFER
坐席(801)与客户响铃或通话中,直接把通话转给目标号码(802 或外部手机/固话),成功后坐席即可挂机:
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&target=802&opt=CLICK_TO_TRANSFER
| 参数 | 必填 | 说明 |
|---|---|---|
| extnum | 是 | 发起转接的坐席分机号 |
| target | 是 | 转接目标号码(分机号或手机/固话) |
| opt | 是 | 固定 CLICK_TO_TRANSFER |
业务码:200 成功(坐席可放下话筒) / 非 200 即失败,常见 400 参数错误、404 找不到该坐席的相关通话、486 目标忙,完整码表见 API 文档总览 3.2 节。
注意:demo 代码中前置判断写的是
callstate === 'ringring'(疑为ringing笔误)或talking,实际使用建议以 WebSocket 订阅到的ringing/talking状态为准。
3. 显转:先呼叫第三方再转接
3.1 第一步:呼叫第三方 CALL_THIRD
坐席(801)与客户通话中,呼叫第三方(802)。CTI 先给客户播放等待音乐,再接通坐席与第三方:
GET http://{cti_host}:12121/bridge/callctrl?callee=801&target=802&opt=CALL_THIRD
| 参数 | 必填 | 说明 |
|---|---|---|
| caller 或 callee | 二选一 | 坐席的分机号:坐席是当前通话的被叫侧传 callee(来电场景通常如此);坐席是主叫侧传 caller(点击呼叫外呼场景)。demo 中的取法:caller === 坐席分机 时传 caller,否则传 callee |
| target | 是 | 第三方号码(分机号或手机/固话) |
| opt | 是 | 固定 CALL_THIRD |
业务码:200 成功 / 400 参数错误 / 404 找不到该坐席的相关通话 / 500 系统错误。
3.2 (可选)查询第三方状态 CALL_THIRD_GET_THIRD_STATE
用于界面提示第三方是振铃中还是已接听,详见 conference 2.2 节(180 振铃 / 200 已接听 / 603 忙或拒绝)。
3.3 第二步:二选一
| 目标 | 接口 | 说明 |
|---|---|---|
| 确认显转 | opt=CALL_THIRD_TRANSFER | 客户与第三方通话,坐席退出,可挂机 |
| 放弃并恢复 | opt=CALL_THIRD_RESUME | 挂断第三方,坐席与客户恢复原通话(第三方无论振铃或已接听都可调用) |
两个接口参数相同:坐席分机号(caller 或 callee,取法与 3.1 一致),无 target:
GET http://{cti_host}:12121/bridge/callctrl?callee=801&opt=CALL_THIRD_TRANSFER
业务码:
| 接口 | 业务码 |
|---|---|
| CALL_THIRD_TRANSFER | 200 成功(坐席可挂机) / 400 参数错 / 404 无相关通话(之前未调 CALL_THIRD) / 500 系统错误 |
| CALL_THIRD_RESUME | 200 成功 / 400 / 404 / 500 |
同一第三方通话也可以升级为三方通话(
CALL_THIRD_CONFERENCE),而不是转接——见 conference 路径 A。
3.4 显转时序
坐席801 ──通话中── 客户
│ CALL_THIRD(target=802)
├──▶ 客户听等待音乐;坐席与第三方802私下沟通
│ ├── CALL_THIRD_TRANSFER ─▶ 客户↔802 通话,坐席退出(显转完成)
│ └── CALL_THIRD_RESUME ─▶ 挂断802,坐席↔客户恢复通话
4. 辅助接口(选择转接目标)
demo 转接页通过以下查询接口帮坐席挑选目标号码,均为 GET http://{cti_host}:12121/bridge/jsoncfg,返回 JSON。
4.1 查询分机实时状态:EXTNUM_MONITOR
"转接"页(转分机场景)用它列出本组分机及忙闲状态,坐席点选一行作为转接目标:
GET http://{cti_host}:12121/bridge/jsoncfg?opt=EXTNUM_MONITOR&json={"first":0,"maxResults":10,"condition":"","exceptextnum":"801","avoidCallPerform":1,"assisLogId":-1}
json 参数为 URL 编码后的 JSON 字符串:
| 字段 | 说明 |
|---|---|
| first | 分页起始页码(从 0 开始,demo 中 pageNum - 1) |
| maxResults | 每页条数 |
| condition | 模糊查询条件(姓名/号码),空串表示不过滤 |
| exceptextnum | 要排除的分机号(一般为坐席自己) |
| avoidCallPerform | demo 固定传 1 |
| assisLogId | demo 固定传 -1 |
响应为数组,元素含 extnumname(姓名)、extnum(分机号)、telRegState(0 表示离线)、presence(busy / reducing 已置忙)、state(BUSY_OUTGOING / BUSY_INCOMING 进行中的通话)、remoteNum(对端号码)、total(总条数,在首个元素上)。该接口的完整说明见 agent-supervision。
4.2 查询转出号码库:TELTRANS_GET_DEPTS / TELTRANS_QUERY
"转出"页(转外部号码场景)从号码库按部门选目标。
先取部门树:
GET http://{cti_host}:12121/bridge/jsoncfg?opt=TELTRANS_GET_DEPTS&json=nothing
响应:{"state":200,"total":N,"data":[{"cfkey":"一级部门","cfvalue":"二级部门1,二级部门2"}]},cfvalue 为逗号分隔的二级部门列表。
再按部门+条件分页查号码:
GET http://{cti_host}:12121/bridge/jsoncfg?opt=TELTRANS_QUERY&json={"first":0,"maxResults":10,"dept":"客服部","suddept":"一组","condition":""}
| 字段 | 说明 |
|---|---|
| first / maxResults | 分页(同 4.1) |
| dept | 一级部门(cfkey) |
| suddept | 二级部门(拼写即如此,demo 源码中的字段名) |
| condition | 模糊查询条件 |
响应:{"state":200,"total":N,"data":[{"dept":"客服部","subdept":"一组","uname":"张三","shortnum":"6001","telnum":"139xxxxxxxx"}]},取 telnum 作为 CLICK_TO_TRANSFER 的 target。
5. curl 示例(完整流程)
CTI=http://192.168.1.80:12121
# ── 盲转:坐席801把当前通话直接转给802 ──
curl "$CTI/bridge/callctrl?extnum=801&target=802&opt=CLICK_TO_TRANSFER"
# 响应体: 200
# ── 显转:坐席801(来电被叫侧)先呼第三方802 ──
curl "$CTI/bridge/callctrl?callee=801&target=802&opt=CALL_THIRD"
# (可选)观察第三方状态:180 振铃 → 200 接听
curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_GET_THIRD_STATE"
# 确认显转(坐席退出)
curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_TRANSFER"
# 或放弃并恢复与客户通话:
# curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_RESUME"
# ── 辅助:查可选分机 / 查转出号码库 ──
curl "$CTI/bridge/jsoncfg?opt=EXTNUM_MONITOR&json=%7B%22first%22%3A0%2C%22maxResults%22%3A10%2C%22condition%22%3A%22%22%2C%22exceptextnum%22%3A%22801%22%2C%22avoidCallPerform%22%3A1%2C%22assisLogId%22%3A-1%7D"
curl "$CTI/bridge/jsoncfg?opt=TELTRANS_GET_DEPTS&json=nothing"
6. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| 盲转/显转返回非 200 | 不要用 HTTP 状态码判断(恒为 200),读响应体业务码;404 多为坐席不在通话中或 caller/callee 传错侧 |
| CALL_THIRD 返回 404 | 坐席不在通话中,或传参侧错误:来电场景坐席是被叫,应传 callee=坐席分机;点击呼叫外呼场景坐席是主叫,传 caller |
| 显转调 CALL_THIRD_TRANSFER 返回 404 | 之前未成功调用 CALL_THIRD,或第三方通话已结束 |
| 盲转后客户听不到声音 | 目标号码未接听前客户处于转接等待,属正常;目标久未应答会按系统配置回退或释放 |
| EXTNUM_MONITOR 查不到某分机 | 检查 exceptextnum 是否把目标排除了;condition 是否过滤掉了 |
| TELTRANS_QUERY 查不到号码 | 确认 dept/suddept 与 TELTRANS_GET_DEPTS 返回的 cfkey/cfvalue 完全一致;suddept 字段名不要改成 subdept |
| 盲转和显转怎么选 | 不需要与接转方沟通选盲转(一步);需要先交代情况选显转(CALL_THIRD 系列) |