自动语音外呼接口(语音通知 / TTS 播报 / 语音验证码 / 双外线桥接)
适用于:无坐席参与的通知类外呼——订单/缴费提醒(TTS 文本播报)、语音验证码、以及把两个外线号码桥接通话。 与 click-to-call 的区别:点击呼叫需要坐席先接听;本组接口由系统自动外呼并播报,全程无需坐席。 配套:呼叫结果用本组的
IVR_TTS_CALL_RESULT/GET_CAPTCHA_RESULT轮询闭环;落地话单走 call-log-query 查询。
所有接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体(README §3)。
0. 两组接口怎么选
| IVR_TTS_CALL(语音菜单/TTS) | CLICK_TO_*_CAPTCHA(语音验证码) | CLICK_OUT_OUT(双外线桥接) | |
|---|---|---|---|
| 播报内容 | 后台配置的语音菜单(VXML),支持 TTS 文本变量 | 提示音 + 逐位播报数字验证码 | 不播报,直接桥接两外线通话 |
| 受理方式 | 异步队列(排队外呼,可自动重试) | 同步发起(流控拒绝) | 同步发起 |
| 结果查询 | 按 token 查文本结果 | 按 id 查状态码 | 返回 clickcallid,走话单查询 |
| 典型场景 | 回访通知、还款提醒、会议通知 | 注册/登录验证码、动态口令 | 隐号回访、两客户号码直连 |
1. IVR_TTS_CALL:外呼播放语音菜单(支持 TTS)
系统自动外呼被叫,接通后播放指定语音菜单;菜单中的文本变量通过 tts* 参数实时合成播报,可收集被叫按键(DTMF)、支持失败自动重呼。
GET http://{cti_host}:12121/bridge/callctrl?token=order-20260924-001&callee=13512340001&toneid=7&tts1=张先生&tts2=385.60&opt=IVR_TTS_CALL
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| opt | String | 是 | 固定 IVR_TTS_CALL |
| callee | String | 是 | 被叫电话号码 |
| toneid | int | 是 | 语音菜单(VXML)编号,须在后台已配置,否则返回 400 |
| token | String | 建议 | 任务唯一标识,用于 IVR_TTS_CALL_RESULT 查结果;同时会进入透传参数表 |
| tts1、tts2… | String | 否 | TTS 文本变量:参数名对应语音菜单中的变量名,值在呼叫前先合成语音,按菜单流程插入播报 |
| extnum | String | 否 | 外呼使用的主叫分机/接入号;缺省用系统"自动总机"配置 |
| callerid | String | 否 | 转坐席时的号码显示 |
| ipcall | String | 否 | true=走网络电话(SIP)线路;缺省 false 走固话线路 |
| retryDelayTime | int | 否 | 失败重呼间隔(秒);缺省 300 秒 |
| maxTryTimes | int | 否 | 最大尝试呼叫次数 |
| pwd | String | 视配置 | 鉴权串,见 §4;CTI 配置 servlet.play.regcode.pwd=no 时免鉴权 |
| 其他任意参数 | String | 否 | 除上表保留字(opt/extnum/callee/toneid/pwd/ipcall/callerid/retryDelayTime/maxTryTimes)外的参数(含 token)原样收入透传表,供语音菜单流程(如转坐席时指定坐席)使用 |
响应(受理结果)
| 业务码 | 含义 |
|---|---|
| 200 | 任务已受理,进入外呼队列(异步执行,不代表已拨出) |
| 400 | 参数错误:callee 为空,或 toneid 对应的语音菜单不存在 |
| 401 | pwd 鉴权失败 |
| 480 | 系统尚未启动完成 |
| 483 | 重复提交:该号码已有同任务在等待/呼叫中(按被叫号码+token 判重) |
| 503 | 外呼通道未就绪(线路忙尽/不可用) |
1.1 查询结果:IVR_TTS_CALL_RESULT
GET http://{cti_host}:12121/bridge/callctrl?token=order-20260924-001&opt=IVR_TTS_CALL_RESULT
响应体为分段文本(非纯数字):
state=1;1122;calltime=1
| 段 | 说明 |
|---|---|
state=N | 任务状态,枚举见 §2 状态码总表 |
客户按键 | 被叫在语音菜单中的 DTMF 输入(如 1122);无输入则该段缺失 |
waiting-recall | 本次失败(忙/失败)且未达 maxTryTimes,系统稍后会自动重呼 |
calltime=N | 已呼叫次数 |
token 不存在时响应体为 404。结果先查内存(进行中任务),再查数据库(历史任务),任务数据保留期以现场为准。
1.2 任务监控:IVR_TTS_CALL_MONITOR
GET http://{cti_host}:12121/bridge/callctrl?opt=IVR_TTS_CALL_MONITOR
响应体:queue=排队队列长度;playcount=等待中+呼叫中的任务数。用于对接方做提交前的并发水位判断。
1.3 重呼机制(重要)
- 忙线/失败的任务,若已设
maxTryTimes且呼叫次数未达上限,系统按retryDelayTime自动重呼,结果中出现waiting-recall; - "呼叫中"状态超过 10 分钟视为超时失败,进入重呼;
- 成功、空号、关机为最终状态,不再重呼。
2. 状态码总表(两组接口通用)
IVR_TTS_CALL_RESULT 的 state= 值与 GET_CAPTCHA_RESULT 的返回值同源:
| 值 | 含义 | 是否最终态 |
|---|---|---|
| 0 | 等待呼叫(队列中) | 否 |
| 1 | 呼叫成功(语音已播完) | 是 |
| 2 | 呼叫失败(未接/线路失败) | 是(未达重试上限时会重呼) |
| 3 | 空号 | 是 |
| 4 | 正在呼叫 | 否 |
| 5 | 用户忙 | 是(未达重试上限时会重呼) |
| 6 | 用户关机 | 是 |
| 7 | 用户振铃 | 否 |
| 8 | 放音中 | 否 |
3. 语音验证码:CLICK_TO_IP_CAPTCHA / CLICK_TO_FIXEDLINE_CAPTCHA
系统自动外呼被叫,接通后先播放提示音(toneid),再逐位播报数字验证码(code),播放次数可控。同步受理,立即进入外呼流程。
GET http://{cti_host}:12121/bridge/callctrl?id=vc-8877&extnum=801&callee=13512340001&toneid=19&code=112233&playtimes=2&opt=CLICK_TO_FIXEDLINE_CAPTCHA
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| opt | String | 是 | CLICK_TO_IP_CAPTCHA 网络电话(SIP)线路;CLICK_TO_FIXEDLINE_CAPTCHA 固话/E1 线路 |
| id | String | 是 | 任务标识,用于 GET_CAPTCHA_RESULT 查状态 |
| callee | String | 是 | 被叫电话号码 |
| code | String | 建议 | 待播报的验证码(纯数字) |
| toneid | int | 否 | 播报数字前播放的提示音编号;不传则直接播数字 |
| extnum | String | 否 | 外呼使用的通道分机;不传走默认外呼策略 |
| voicefile | String | 否 | 服务器本地语音文件绝对路径(替代提示音);格式不合法时服务端自动转码,转码失败返回 400 |
| playtimes | int | 否 | 验证码播放次数,缺省 1 |
| precallcount | int | 否 | 通道忙时允许的最大并发播放数(流控),缺省 0 |
| pwd | String | 视配置 | 鉴权串,见 §4 |
| 业务码 | 含义 |
|---|---|
| 200 | 呼叫已发起 |
| 400 | 参数错误 / voicefile 转码失败 |
| 401 | pwd 鉴权失败 |
| 420 | id 缺失等参数形态错误 |
| 480 | 系统尚未启动完成 |
| 486 | 流控:当前播放任务数已达上限(软参 play.reg.flood.control)或通道忙(precallcount 限制) |
3.1 查询状态:GET_CAPTCHA_RESULT
GET http://{cti_host}:12121/bridge/callctrl?id=vc-8877&opt=GET_CAPTCHA_RESULT
响应体为单个状态数字(枚举见 §2):1=播报成功、5=用户忙、3=空号……;404=无此 id 的记录(或已过期)。该接口只返回状态,不返回被叫按键——需要收集按键的验证流程请改用 IVR_TTS_CALL(语音菜单收集 DTMF)。
3.2 校验语音资源:CHECK_VOIC_NAME
GET http://{cti_host}:12121/bridge/callctrl?vname=welcome&opt=CHECK_VOIC_NAME
vname 为后台语音库中的语音名称(参数需 URL 编码)。存在则原样返回该名称,不存在返回 NOT_FOUND。提交外呼任务前可先校验提示音是否就位。
4. pwd 鉴权算法(两组外呼接口通用)
CTI 侧软参 servlet.play.regcode.pwd 配置了密码时必须携带 pwd,算法:
pwd = MD5( 配置密码 + callee + code + yyyy-MM-dd ) # code 仅验证码接口有,IVR_TTS_CALL 无 code 时拼空串
日期取 CTI 服务器当天(注意与 GET_SERVER_DATE 对时)
配置为 no 或留空时不鉴权。鉴权失败返回 401。
5. CLICK_OUT_OUT:点击呼叫两个外线号码
不需要任何坐席参与:系统先后呼叫 caller 与 callee 两个外线号码并桥接双方通话(典型:隐号回访、第三方系统撮合两方通话)。
GET http://{cti_host}:12121/bridge/callctrl?caller=13512340001&callee=13712340002&opt=CLICK_OUT_OUT
| 参数 | 必填 | 说明 |
|---|---|---|
| caller | 是 | 第一外线号码(先呼叫方,接听后听等待提示) |
| callee | 是 | 第二外线号码(先呼方接听后再呼出) |
| opt | 是 | 固定 CLICK_OUT_OUT |
约束(不满足时的返回):两个号码都不能是 CTI 内部分机(否则 400);任一号码正在通话中返回 486。
成功时响应体为本次呼叫的 clickcallid(UUID 字符串,非 200),凭它走 call-log-query 的 CALL_LOG_GET_WITH_CALLID 查询话单;其他失败返回业务码。
6. curl 示例(完整闭环)
CTI=http://192.168.1.80:12121
# 1. TTS 通知外呼:菜单 7,变量 tts1/tts2 合成播报
curl "$CTI/bridge/callctrl?token=order-20260924-001&callee=13512340001&toneid=7&tts1=%E5%BC%A0%E5%85%88%E7%94%9F&tts2=385.60&retryDelayTime=600&maxTryTimes=3&opt=IVR_TTS_CALL"
# → 200
# 2. 轮询结果(未完成时 state=0/4/7/8;客户按了 1122)
curl "$CTI/bridge/callctrl?token=order-20260924-001&opt=IVR_TTS_CALL_RESULT"
# → state=1;1122;calltime=1
# 3. 语音验证码:固话线路播 2 遍
curl "$CTI/bridge/callctrl?id=vc-8877&callee=13512340001&toneid=19&code=112233&playtimes=2&opt=CLICK_TO_FIXEDLINE_CAPTCHA"
sleep 30
curl "$CTI/bridge/callctrl?id=vc-8877&opt=GET_CAPTCHA_RESULT" # → 1
# 4. 双外线桥接
curl "$CTI/bridge/callctrl?caller=13512340001&callee=13712340002&opt=CLICK_OUT_OUT"
# → d0bd6022-6cbb-409d-9443-6f2d1ee830b7 (clickcallid)
7. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| IVR_TTS_CALL 返回 483 | 同一号码已有任务在队列/呼叫中(按号码+token 判重);等结果到最终态再提交,或换 token 前先确认上一任务结束 |
| IVR_TTS_CALL 返回 200 但结果一直 state=0 | 外呼通道忙,任务在队列中排队;用 IVR_TTS_CALL_MONITOR 看 queue/playcount 水位 |
| 结果出现 waiting-recall | 首呼忙/失败,系统在 retryDelayTime 后自动重呼;无需自行重新提交,避免重复任务(会 483) |
| GET_CAPTCHA_RESULT 一直 404 | id 拼写不一致,或记录已过期;提交与查询用同一 id |
| 验证码返回 401 | pwd 算法/日期不对:日期取 CTI 服务器当天,先用 GET_SERVER_DATE 对时 |
| 验证码返回 486 | 并发播放任务已达流控上限(play.reg.flood.control)或 precallcount 限制;降低提交频率 |
| CLICK_OUT_OUT 返回 400 | 号码写成了内部分机号;本接口只接受两个外线号码 |
| 播报的 TTS 变量没生效 | tts* 参数名必须与语音菜单中配置的变量名一致,且文本需 URL 编码 |