通话中放音与转 IVR 接口
适用于:坐席通话进行中的语音注入——给客户播放免责声明/确认音/业务提示语(
PLAY_VOICE_IN_CALL),把通话转接到 IVR 语音菜单或机器人(TALKING_CALLER_TO_IVR),以及对自动外呼的"放音呼叫"追加/更换播放内容(PLAY_VOICE)。 配套:放音前可用 ivr-outbound-voice §3.2 的CHECK_VOIC_NAME校验语音资源;转 IVR 后的按键结果走该文档的话单/结果查询。
所有接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体(README §3)。
1. 通话中放音:PLAY_VOICE_IN_CALL
坐席与客户通话中,向指定一侧(或双方)混入播放一段语音。播放期间原对话继续(混音),适合播确认语、免责声明、背景提示。
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&toneid=15&mixside=callee&opt=PLAY_VOICE_IN_CALL
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| extnum | String | 是 | 通话中任一方分机号(一般为坐席分机);该分机须有且仅有一通进行中通话 |
| toneid / filepath / cordialvoicekey | String | 三选一 | 音源:toneid=后台语音库编号;filepath=服务器本地语音文件绝对路径(需 URL 编码);cordialvoicekey=亲切语配置键 |
| mixside | String | 否 | 播放给谁听:callee(缺省)/caller/both/none,语义见下表 |
| opt | String | 是 | 固定 PLAY_VOICE_IN_CALL |
mixside 语义(重要)
mixside 按通话的两条腿实现:caller=第一腿、callee=第二腿。第一腿/第二腿与场景的对应:
| 场景 | 第一腿(caller) | 第二腿(callee) |
|---|---|---|
| 点击外呼(坐席发起) | 坐席 | 客户 |
| 呼入(客户打进来) | 客户 | 坐席 |
因此**"只让客户听到"**:外呼场景传 mixside=callee,呼入场景传 mixside=caller;both=双方都听;none=双方都不听(仅打保持标记,相当于静默保持)。
响应
| 业务码 | 含义 |
|---|---|
| 200 | 已开始播放(异步,播完自动结束) |
| 400 | 参数错误:extnum/音源缺失,或 filepath 解码失败 |
| 404 | extnum 不是系统分机 |
| 480 | 该分机当前没有进行中的通话(或找不到可注入的通话实例) |
2. 停止放音与播放状态
2.1 STOP_VOICE_IN_CALL
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&opt=STOP_VOICE_IN_CALL
停止该分机通话中的进行中放音。业务码:200 成功 / 404 无相关通话 / 400 参数错误。
2.2 STATE_VOICE_IN_CALL
GET http://{cti_host}:12121/bridge/callctrl?extnum=801&opt=STATE_VOICE_IN_CALL
响应体为文本:playing(放音中)/ standby(空闲,含无通话)。
2.3 DIA_NUM_VOICE_IN_CALL:坐席自录语音接入号
GET http://{cti_host}:12121/bridge/callctrl?opt=DIA_NUM_VOICE_IN_CALL
返回"录制语音"功能的外呼接入号(软参 assis.record.voice.num 配置)。坐席拨该号码可自行录制亲切语,录制的语音供 PLAY_VOICE_IN_CALL 的 cordialvoicekey 引用。未配置时返回空。
3. 通话中转 IVR:TALKING_CALLER_TO_IVR
把进行中的一通通话整体转接到指定 IVR 语音菜单/机器人流程(原坐席退出,客户听到菜单)。适合:坐席判断后转自助、转 AI 机器人、转按键收集流程。
GET http://{cti_host}:12121/bridge/callctrl?caller=801&callee=13512340001&ivrid=12&biz_data=crm-order-8877&queue_priority=5&opt=TALKING_CALLER_TO_IVR
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| caller | String | 是 | 当前通话主叫号码 |
| callee | String | 是 | 当前通话被叫号码 |
| ivrid | int | 是 | 目标语音菜单/IVR 编号(须为数字) |
| biz_data | String | 否 | 业务数据,转接时透传给 IVR/机器人流程 |
| queue_priority | int | 否 | 若 IVR 流程转入排队,指定排队优先级 |
| opt | String | 是 | 固定 TALKING_CALLER_TO_IVR |
| 业务码 | 含义 |
|---|---|
| 200 | 转接已受理 |
| 400 | 参数错误(含 ivrid 非数字) |
| 404 | 找不到 caller+callee 对应的进行中通话 |
| 486/500 等 | 转接执行失败,以现场日志为准 |
4. 放音呼叫中主动放音:PLAY_VOICE
针对自动外呼的"放音呼叫"(media call)——即通过 IVR_TTS_CALL、机器人等发起的、由系统播报的呼叫——按 callid 播放一段网络语音。常用于机器人对话流程中由第三方系统动态指定下一句播报内容。
GET http://{cti_host}:12121/bridge/callctrl?callid=8db03e9d-a07e-4d0d-9cee-9ed1470b8e76@127.0.0.1&voiceurl=http://192.168.1.80:12121/voice/next.wav&opt=PLAY_VOICE
| 参数 | 必填 | 说明 |
|---|---|---|
| callid | 是 | 放音呼叫的 call-id(需 URL 编码);测试场景可用 test@127.0.0.1 命中任一放音呼叫 |
| voiceurl | 是 | 语音文件 URL(http 地址,需 URL 编码),系统拉取后播放 |
| opt | 是 | 固定 PLAY_VOICE |
业务码:200 已开始播放 / 400 参数错误 / 404 没有匹配的放音呼叫(普通坐席通话不能用本接口,须用 §1 的 PLAY_VOICE_IN_CALL)。
5. curl 示例
CTI=http://192.168.1.80:12121
# 1. 呼入通话中,只让客户听到免责声明(呼入场景第一腿=客户 → mixside=caller)
curl "$CTI/bridge/callctrl?extnum=801&toneid=15&mixside=caller&opt=PLAY_VOICE_IN_CALL"
# 2. 查播放状态 / 需要时停止
curl "$CTI/bridge/callctrl?extnum=801&opt=STATE_VOICE_IN_CALL" # → playing
curl "$CTI/bridge/callctrl?extnum=801&opt=STOP_VOICE_IN_CALL" # → 200
# 3. 坐席判断后整通转 IVR 菜单 12,带业务标记
curl "$CTI/bridge/callctrl?caller=801&callee=13512340001&ivrid=12&biz_data=crm-order-8877&opt=TALKING_CALLER_TO_IVR"
6. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| PLAY_VOICE_IN_CALL 返回 480 | 坐席当前无通话,或该分机名下有多通并行通话导致无法定位;确认通话存在且唯一后重试 |
| 客户听不到放音 | mixside 传反了:外呼场景客户是第二腿(callee),呼入场景客户是第一腿(caller),见 §1 对照表 |
| 播放没声音但返回 200 | 音源三选一都没传全(如 toneid 不存在时 file 为空被拒,返回 400);或文件路径需 URL 编码未编码 |
| TALKING_CALLER_TO_IVR 返回 404 | caller/callee 与实际通话方向不匹配(主被叫须与通话记录一致) |
| PLAY_VOICE 返回 404 | callid 不是放音呼叫(media call),普通通话请用 PLAY_VOICE_IN_CALL |
| none 之后通话单边无声 | none 是静默保持,双方都听不到混音,恢复通话需重新放音或由坐席操作;确认业务预期后再使用 |