分机列表查询接口（坐席分机数据来源）
适用于:第三方系统(OA/CRM)需要全量分机字典的场景——维护"自家用户 ↔ CTI 分机号"映射表、坐席绑定分机时的下拉选择、分机存在性校验、同步在线状态快照。一次调用返回系统内全部坐席型分机(含离线)及其工号绑定、示忙状态、注册在线标记。 配套:绑定写入侧见 agent-ext-binding.md(
SET_WORKER_ID);单个分机的状态探测见 ext-presence.md(GET_EXT_PRESENCE_STATE);状态实时变化订阅见 websocket-call-state.md。本接口是拉全量快照,适合低频同步(如登录时/每日一次),不适合轮询当实时状态用。
接口为 GET http://{cti_host}:12121/bridge/callctrl,正常通过鉴权后，响应体为 JSON，而不是纯数字业务码。鉴权失败可能返回 HTTP 401；端口与鉴权约定见集成 API 文档。
1. 接口定义
GET http://{cti_host}:12121/bridge/callctrl?opt=GET_EXT_LIST
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| opt | String | 是 | 固定 GET_EXT_LIST |
无其他参数:返回的是全量字典(含离线分机)。可按 registered 筛选已注册分机；state 表示示忙状态，两者含义不同。
2. 响应格式
{
"success": true,
"total": 2,
"rows": [
{"extnum": "801", "name": "研发/夏天", "worknum": "41735", "uetype": "EXT_TYPE", "state": "online", "registered": true},
{"extnum": "802", "name": "", "worknum": "", "uetype": "WEBRTC_TYPE", "state": "unkown", "registered": false}
]
}
| 字段 | 类型 | 说明 |
|---|---|---|
| success | boolean | true 查询成功;false 见 §4 降级语义 |
| total | int | rows 条数(仅 success=true 时有) |
| rows | array | 分机列表,按 extnum 字典序排序 |
| rows.extnum | String | 分机号 |
| rows.name | String | 分机显示名。即 SET_WORKER_ID 的 department 参数写入的值(历史语义:该参数实际是"部门/姓名备注",存分机名称列);未设置为空串 |
| rows.worknum | String | 绑定的坐席工号(来自 SET_WORKER_ID);未绑定为空串 |
| rows.uetype | String | 终端类型:EXT_TYPE SIP 分机 / WEBRTC_TYPE 网页软电话分机 / TRUNK_EXT_TYPE 中继分机 |
| rows.state | String | 示忙状态:online 空闲 / busy 示忙 / reducing 减少来电 / unkown 未知(历史拼写,非 typo,勿写成 unknown) |
| rows.registered | boolean | true = 当前已注册在线且未过期/未欠费停用;false = 离线(含注册过期、欠费停用) |
包含范围:仅坐席型分机(上述三种 uetype);出群网关(GW_TYPE/GOIP/E1/IMS)等设备类型不在返回内。
3. curl 示例
CTI=http://192.168.1.80:12121
# 全量分机字典
curl "$CTI/bridge/callctrl?opt=GET_EXT_LIST"
# 只取在线分机(jq 过滤)
curl -s "$CTI/bridge/callctrl?opt=GET_EXT_LIST" | jq '.rows | map(select(.registered))'
# CRM 侧建"工号→分机"映射(jq)
curl -s "$CTI/bridge/callctrl?opt=GET_EXT_LIST" \
| jq '.rows | map(select(.worknum != "")) | map({key: .worknum, value: .extnum}) | from_entries'
以上工号映射示例仅适用于工号唯一的情况；若多个分机绑定同一工号，from_entries 会覆盖前面的值，调用方应先处理重复绑定。
4. 降级语义(重要)
| 响应 | 含义 | 调用方应当 |
|---|---|---|
{"success": true, "total": N, "rows": [...]} | 查询成功。rows 为空数组 = 系统内确实没有坐席型分机 | 正常处理(空数组是真数据) |
{"success": false, "error": "user manager not ready"} | CTI 用户管理服务尚未就绪(常见于系统启动初期) | 不要清空/覆盖本地映射表;保留旧数据,延时重试 |
{"success": false, "error": "query failed"} | 服务端内部异常 | 同上;若持续出现,查 CTI 日志 getExtList failed |
不要以 total==0 或 rows==[] 判断失败——失败时没有 total/rows 字段,只有 success:false。这是防止对接方把降级响应当真全量、误清本地"坐席-分机"映射的设计。
5. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
返回 {"success":false,...} | 用户管理服务未就绪或内部异常,按 §4 处理;持续失败查服务端日志 callctrl user manager unavailable / getExtList failed |
| 某分机在 OMS 有,接口没返回 | 该分机不是坐席型(是网关/中继设备等);核对 OMS 中该号码的终端类型 |
state 一直是 unkown | 表示示忙状态未知；请结合 registered 和现场配置核查，二者含义不同 |
name 与 CRM 传入的部门不一致 | name 是最后一次 SET_WORKER_ID 写入的值(全局只有一份,后写覆盖);CRM 侧应以自家数据为权威,本字段仅作展示 |
registered:false 但话机明明在线 | registered 由注册有效期+欠费标记计算;分机注册过期未续期或欠费停用都会是 false,在 OMS 核对该分机状态 |
| 想要状态的实时变化 | 本接口是快照,不要高频轮询;订阅 websocket-call-state.md 或按需查单个分机(ext-presence.md) |
响应体不是 JSON 而是 400 | opt 拼写错误走统一 400 分支;确认 opt=GET_EXT_LIST 原样传递 |
6. 版本
GET_EXT_LIST 为 2026-10-07 新增接口(系统版本 3.8.681 起)；更早版本可能不支持。对接前可用 GET ...?opt=ABOUT 核对现场版本，并以实际部署版本联调结果为准。