TelCRM(国信)呼叫中心 集成 API 文档
面向将 OA/CRM 等系统与呼叫中心做基础集成的 AI 编程工具与开发人员。所有接口均来自对服务端源码、官方《国信呼叫中心二次开发接口说明书》V3.66 与官方 demo(WebPlugin/diapnl、webapps/demo/callstate)的核对,冲突处以服务端源码为准。
1. 文档索引(按集成场景)
| 你要做的事 | 看这份文档 |
|---|---|
| 来电弹屏 / 实时通话状态 / 坐席忙闲 / 排队看板 | websocket-call-state — WebSocket 呼叫状态订阅 |
| 页面点击拨号 / 点击挂机 | click-to-call — 点击呼叫 |
| 无坐席自动外呼(语音通知/TTS 播报/语音验证码/双外线桥接) | ivr-outbound-voice — 自动语音外呼 |
| 弹屏录单时置忙免打扰 / 保存后置闲 / 忙闲状态查询 | ext-presence — 分机示忙示闲 |
| 坐席上班绑工号/部门 / 来电状态 HTTP 推送弹屏 / 外呼显示号码 / 回拨直达 | agent-ext-binding — 坐席资料绑定与分机外呼属性 |
| 通话记录列表 / 详情 / 结果查询 | call-log-query — 呼叫记录查询 |
| 挂机话单批量推送同步到第三方服务器 | call-log-push — 呼叫记录推送 |
| 号码维度沟通小结弹屏 / 按号码统计通话次数(频控、机器人呼入统计) | call-summary-call-count — 沟通总结与通话计数 |
| 来电是否打得太频繁(防骚扰拦截 / 机器人呼入频控,true/false 判定) | incoming-frequency-guard — 呼入频次越限判断 |
| 录音在线播放 / 下载归档 / 话机收听 | recording-download — 录音下载与播放 |
| 坐席状态监控 / 监听 / 强插 / 强拆 | agent-supervision — 坐席监管 |
| 三方通话 / 多方会议 / 成员管理 | conference — 三方会议全链路 |
| 通话中转给同事或外线(盲转一步转走 / 显转先沟通再转) | call-transfer — 盲转与显转 |
| 通话中放确认音/免责声明 / 转IVR/机器人 / 对放音呼叫动态换播 | in-call-voice-ivr — 通话中放音与转 IVR |
| 通话中客户口述信息转文字(语音填单) | voice-input — 通话语音识别输入 |
| 挂机邀评满意度 / 发短信 / 短信通道余额 | sms-and-evaluation — 短信与挂机邀评 |
| 系统健康探测 / 排队看板 / 对时 / 网页软电话账号 | system-status-queue — 系统状态与排队监控 |
| 大模型故障上报 / 恢复上报(knServer 对接,联动机器人入口拦截) | ai-model-fault-recovery — 大模型故障与恢复 |
最小集成路径示例:来电弹屏+点击回拨+录音 = 订阅 WebSocket(websocket-call-state)+ CLICK_TO_DIAL(click-to-call)+ CALL_LOG_QUERY + FileDownServlet(call-log-query / recording-download)。
其他未在本文档展开的接口(客户资料导入、批量外呼任务、WebService/SOAP 通道、服务器关机等运维类操作等)见随产品的官方《二次开发接口说明书》。
2. 服务器端口一览
| 端口 | 协议 | 用途 |
|---|---|---|
| 12121 | HTTP | /bridge/* 业务接口、/Oms/FileDownServlet 录音下载(本文档全部 HTTP 接口) |
| 8443 | HTTPS | 同上的加密通道(证书需现场配置) |
| 7397 | WebSocket(明文) | ws://{cti_host}:7397/websocket 呼叫状态订阅 |
| 7399 | WebSocket(加密) | wss://{cti_host}:7399/websocket,带服务端 ping/pong 心跳 |
端口均为默认值,以现场实际配置为准。URL 中服务器地址本文档统一以 {cti_host} 表示。
3. 必读通用约定
3.1 业务码在响应体,HTTP 状态码恒为 200(重要)
/bridge/callctrl 系列接口:无论成功失败,HTTP 状态码都是 200,业务结果写在响应体,为纯文本数字(SIP 风格码),例如成功是文本 200,权限不足是文本 403。不要用 HTTP 层判断成败。
curl "http://{cti_host}:12121/bridge/callctrl?caller=801&callee=13512340001&authtype=no&opt=CLICK_TO_DIAL"
# 响应体: 200 ← 文本"200"表示成功
例外:
/bridge/jsoncfg、/bridge/conference返回 JSON(错误也是 HTTP 200 + body 内错误信息,如{"code":404,"message":"unknown opt: xxx"});- 鉴权失败(配置了白名单/Basic 且未通过)是真实 HTTP 401;
- 录音下载
/Oms/FileDownServlet返回文件流或错误文本。
3.2 业务码总表(SIP 风格)
| 码 | 含义 | 常见场景 |
|---|---|---|
| 200 | 成功 | 一切接口 |
| 400 | 参数错误 | 缺参数/拼写错/opt 非法 |
| 402 | 授权(license)限制 | 点击呼叫并发超授权 |
| 403 | 禁止 | 黑名单号码、分机无权限(如强插/监听/外呼) |
| 404 | 目标不存在 | 无相关通话、分机不存在、会议不存在 |
| 420 | 默认错误(BAD_EXTENSION) | 兜底错误码 |
| 480 | 暂时不可用 | 分机离线、会议创建中 |
| 483 | 重复提交 | 重复创建会议、重复提交任务 |
| 486 | 忙 | 分机忙、线路忙、被邀请方忙 |
| 487 | 已终止 | 有终端挂机导致操作失败 |
| 500 | 系统错误 | 服务端异常 |
| 502 | 网关错误 | 网关账号类型错误/离线 |
| 503 | 资源不足/频控 | 系统资源不足、呼叫频率超限 |
| 606 | 不可接受 | opt 参数取值错误 |
各接口特有业务码以对应文档章节为准。
3.3 数据格式约定
| 项 | 约定 |
|---|---|
| JSON 日期字符串 | yyyy-MM-dd HH:mm:ss |
时间戳字段(如 beginTime) | 毫秒 epoch(数值型) |
| 日期型查询参数 | yyyy-MM-dd 或 yyyy-MM-ddTHH:mm:ss(T 分隔日期与时间) |
| CORS | 全部接口响应 Access-Control-Allow-Origin: *,可跨域调用 |
| 字符编码 | UTF-8 |
3.4 鉴权模型
/bridge/*接口:可配置 IP 前缀白名单(legitimate.servlet.client.ip.prefix)或 HTTP Basic Auth(legitimate.servlet.basic.auth),任一通过即放行;127.0.0.1恒放行;两者都未配置时完全放行。未通过返回 HTTP 401。- 点击呼叫支持业务级 MD5 鉴权(
authtype=md5,见 click-to-call)。 - WebSocket 订阅(7397)无鉴权,可订阅任意分机;录音下载默认放行。
- 集成建议:生产环境用防火墙/安全组限制 12121/7397/7399 端口来源,或在 CTI 配置 IP 白名单/Basic Auth。
3.5 拼写陷阱表(历史拼写,必须原样传递)
以下拼写与直觉不符但是接口的真实字段/参数名,写错不报错、只返回 400/404 或静默无效:
| 正确拼写(勿改) | 位置 |
|---|---|
wokerExtnum | 强拆/强插/监听的被操作分机参数 |
drection | 呼叫记录方向字段/dirction 查询参数 |
ringdration / talkdration | 分机视角记录的振铃/通话时长字段 |
stauts | 会议状态字段;会议查询软参 conference.http.json.stutas.offon |
unkown | 状态枚举值(presence 取值之一) |
sceenShowType | WebSocket 通知类型字段 |
IDEL | 坐席监控的话机空闲状态值(非 IDLE) |
suddept | 转出号码库 TELTRANS_QUERY 的二级部门查询字段(非 subdept) |
4. 典型集成组合
- 来电弹屏:订阅 WebSocket → 收到
ringing的 dialog → 按caller打开客户资料;通话中talking计时;hungup后可查记录/放录音。 - 点击回拨:客户详情页按钮 →
CLICK_TO_DIAL(带clicktoken业务标记)→ 坐席话机响铃接听后自动外呼客户。 - 通话留痕:通话列表用
CALL_LOG_QUERY/EXTNUM_CALL_LOG_QUERY分页查询;详情与录音按callid获取。 - 坐席监管:轮询
EXTNUM_MONITOR(2 秒)→ 对通话中的坐席执行CALL_MONITOR/FORCE_PICKUP/FORCE_HUNGUP。 - 三方支援:坐席通话中
CALL_THIRD呼第三方 → 私下沟通 →CALL_THIRD_CONFERENCE三方或CALL_THIRD_TRANSFER显转。 - 电话转接:无需沟通直接
CLICK_TO_TRANSFER盲转;需先沟通走CALL_THIRD→CALL_THIRD_TRANSFER显转,不满意可CALL_THIRD_RESUME恢复(见 call-transfer)。 - 话单同步:配置
calllog.post.*软参开启推送(call-log-push)→ 挂机话单批量 POST 到第三方(应答 200/400)→ 收到的recordVoice非空即按callid走 FileDownServlet 取录音。
5. 版本与事实来源
- 依据官方说明书 V3.66(系统版本 3.10.629,2026-07-28)与服务端源码核对整理;
- 接口行为如与现场版本有出入,以现场部署版本实际行为为准,并欢迎在本文档目录下补充勘误。