通话语音识别输入接口(START/STOP_VOICE_INPUT)

适用于:通话中让某一侧(一般是客户)"口述信息、系统转文字"——坐席发起开始,客户说完后停止,接口直接返回该侧的识别文本。典型:地址/卡号/诉求的语音填单,免去坐席手工录入。 区别:通话全程的实时识别推送(RocketMQ)是另一套机制,见《VoiceSideStt-RocketMQ-接口文档》;本接口是按需的一段式识别,无需 MQ 对接。

接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体(README §3)。

1. 开始识别:START_VOICE_INPUT

GET http://{cti_host}:12121/bridge/callctrl?extnum=801&side=callee&expires=30&opt=START_VOICE_INPUT
参数类型必填说明
extnumString是通话中的分机号(一般坐席分机),须存在且未过期
sideString否识别哪一侧:caller / callee(缺省);按通话两腿取,呼入场景 caller=客户侧,外呼场景 callee=客户侧(与 in-call-voice-ivr §1 mixside 同一语义)
expiresint否自动截止时长(秒),超时自动停止并释放资源;缺省 7 秒
optString是固定 START_VOICE_INPUT
业务码含义
200识别已开始
400参数错误(side 非法/extnum 缺失)
404分机不存在,或该分机无进行中的通话
480语音识别(STT)未开启——license 或引擎未启用,需管理员开通

2. 停止并取文本:STOP_VOICE_INPUT

GET http://{cti_host}:12121/bridge/callctrl?extnum=801&side=callee&opt=STOP_VOICE_INPUT

参数与 START 相同(extnum、side)。响应体为该侧的识别文本:

广东省深圳市南山区科技园一号
响应体含义
文本内容识别成功(可能为空串,表示该侧没说话)
500识别中/无结果返回
400参数错误或无相关通话

3. 使用时序

坐席801 ──通话中── 客户
   │ START_VOICE_INPUT(extnum=801, side=客户侧, expires=30)
   │      客户口述:"广东省深圳市南山区科技园一号"
   │ STOP_VOICE_INPUT(extnum=801, side=客户侧)
   └──▶ 响应体直接拿到文本 → 填入 OA/CRM 表单
  • expires 按"客户最长会说多久"设置(地址类建议 15-30 秒);到时自动停止,再调 STOP 仍可取已识别文本;
  • 开始后不调 STOP 也能靠 expires 自动释放,但取文本必须调 STOP;
  • 同一分机同一时刻只支持一段识别,重复 START 以现场返回为准,建议严格配对使用。

4. curl 示例

CTI=http://192.168.1.80:12121

# 呼入通话,客户口述地址(客户=第一腿 → side=caller)
curl "$CTI/bridge/callctrl?extnum=801&side=caller&expires=30&opt=START_VOICE_INPUT"   # → 200
sleep 30
curl "$CTI/bridge/callctrl?extnum=801&side=caller&opt=STOP_VOICE_INPUT"
# → 广东省深圳市南山区科技园一号

5. 常见问题排查

现象原因与处理
START 返回 480STT 能力未开启(license/引擎),需管理员开通;确认现场是否部署语音识别引擎
STOP 返回 500识别尚未出结果或已过期释放;先 STOP 一次拿不到时,等 1-2 秒重试,仍不行重新 START
识别文本为空该侧没有检测到语音(说太小声/说错侧);确认 side 与目标人对应
返回 404坐席已挂机后调用;识别必须在通话存续期间完成