点击呼叫接口(Click to Dial)

适用于:OA/CRM 页面上点击客户姓名或号码即可发起呼叫;点击挂机。 配套:配合 websocket-call-state 订阅可实时展示呼叫进展,配合 call-log-query 查询呼叫结果。

1. 业务流程

CLICK_TO_DIAL 的呼叫顺序为先呼叫坐席分机,坐席接听后再呼叫客户电话:

OA/CRM ──HTTP──▶ CTI ──振铃──▶ 坐席分机 801(坐席摘机)
                        └────外呼──▶ 客户 135xxxxxxxx(客户接听,双方通话)

因此调用接口后,坐席话机先响铃,接听后才拨打客户号码——这是正常行为,不是故障。

2. 发起点击呼叫

GET http://{cti_host}:12121/bridge/callctrl?caller=801&callee=135xxxxxxxx&authtype=no&opt=CLICK_TO_DIAL
参数类型必填说明
callerString是主叫分机号码(坐席分机),如 801
calleeString是被叫电话号码(客户号码),外线号码按现场拨号规则(可能需加 0 或前缀)
authtypeString是鉴权方式:no 不鉴权;md5 MD5 鉴权(见 §3);auth1 自定义数字加密(需与厂方约定)
pwdStringauthtype=md5 时必填MD5(caller + callee + 密码),密码为与 CTI 预先约定的一致值
optString是CLICK_TO_DIAL 固话/E1/GoIP 等线路外呼;CLICK_TO_IP_DIAL 网络电话(SIP 线路)外呼
backidString否填 true 时响应体返回本次点击呼叫的 UUID(clickcallid),用于后续查记录(见 §5)
clicktokenString否业务标记字符串(≤64 字符),原样写入呼叫记录 calllog.clicktoken,用于 OA/CRM 与通话记录关联
channelString否指定外呼通道(线路/手机卡的号码);暂不支持分组号码

{cti_host}:12121 为 CTI 服务器 HTTP 地址,12121 为默认端口,以现场配置为准。

响应

HTTP 状态码恒为 200,业务结果写在响应体(纯文本):

业务码含义
200呼叫已受理,坐席话机即将振铃
400参数错误或缺 opt
402授权(license)数量限制
403禁止:号码在黑名单,或该分机无外呼权限
486主叫分机忙(正处在通话中)或网关线路忙
500系统错误
502指定网关账号类型错误(非出群网关)或网关离线
503呼叫频率过快,超过系统限制
606opt 参数填写错误

携带 backid=true 时,成功响应体为 UUID 字符串(非 200),如:

d0bd6022-6cbb-409d-9443-6f2d1ee830b7

该值即呼叫记录中的 clickcallid 字段。

curl 示例

# 最简形式(不鉴权)
curl "http://192.168.1.80:12121/bridge/callctrl?caller=801&callee=13512340001&authtype=no&opt=CLICK_TO_DIAL"

# 带业务标记并返回 clickcallid
curl "http://192.168.1.80:12121/bridge/callctrl?caller=801&callee=13512340001&authtype=no&backid=true&clicktoken=crm-order-8877&opt=CLICK_TO_DIAL"

3. MD5 鉴权(authtype=md5)

pwd = MD5(caller + callee + 约定密码),32 位小写十六进制:

# 例:caller=801, callee=13512340001, 约定密码=secret123
echo -n "80113512340001secret123" | md5sum
curl "http://192.168.1.80:12121/bridge/callctrl?caller=801&callee=13512340001&authtype=md5&pwd=<上面算出的md5>&opt=CLICK_TO_DIAL"

密码需预先在 CTI 侧配置一致。authtype=no 则完全放开(此时建议配合 IP 白名单,见 README 鉴权说明)。

4. 点击挂机(CLICK_TO_HUNGUP)

配合点击呼叫使用,挂断指定主被叫之间的呼叫(无论振铃中还是已接通):

GET http://{cti_host}:12121/bridge/callctrl?caller=801&callee=135xxxxxxxx&opt=CLICK_TO_HUNGUP
参数必填说明
caller是主叫分机号码
callee是被叫电话号码
opt是固定 CLICK_TO_HUNGUP

响应体业务码:200 成功 / 400 参数错误。

5. 查询呼叫结果(闭环)

点击呼叫是异步受理,接口返回 200 只代表已开始呼叫。查询结果的两种方式:

方式一:用 clickcallid 精确查询(推荐,backid=true 拿到 UUID 后使用):

GET http://{cti_host}:12121/bridge/callctrl?callid=d0bd6022-6cbb-409d-9443-6f2d1ee830b7&opt=CALL_LOG_GET_WITH_CALLID

callid 参数需 URL 编码;返回该次呼叫的完整记录 JSON(字段说明见 call-log-query)。注意:记录在呼叫结束后才完整(含时长、录音路径),呼叫进行中查询可能拿到 STATE_RECEIVING 状态。

方式二:WebSocket 订阅(见 websocket-call-state):订阅 caller 分机,按 ringing → talking → hungup 的状态流驱动界面。

6. 常见问题排查

现象原因与处理
返回 486坐席分机正在通话;等空闲后再拨,或界面置灰
返回 403号码命中黑名单(后台"黑名单维护"解除),或分机无外呼权限
返回 503触发外呼频控;降低调用频率(勿在循环里无间隔拨号)
返回 502外呼线路(网关)离线或类型配置错误,联系系统管理员
接口 200 但坐席话机不响检查分机是否在线注册;WebSocket 订阅该分机观察是否有 dialog 事件
客户未接听但拿不到结果呼叫结束后用方式一按 clickcallid 查询,state=STATE_FAILED、duration 为振铃时长