录音下载与播放接口
适用于:在 OA/CRM 中在线播放通话录音、下载录音/视频归档、通过话机收听录音。 数据来源:呼叫记录中的
callid(见 call-log-query)或 WebSocket 弹屏通知的id。
播放/下载共三个接口:FileDownServlet(文件流,下载与网页播放)、RecordPlayerSvlt(现成播放页 HTML)、PLAY_CALL_LOG_RECORD(呼叫分机用话机听)。
1. 接口地址与用法
GET http://{cti_host}:12121/Oms/FileDownServlet?callid=<URL编码的callid>
注意 context 是 /Oms(不是 /bridge),默认端口同为 12121;HTTPS 部署时为 https://{cti_host}:8443/Oms/FileDownServlet?...。
按优先级排列的三种常用参数:
1.1 按 callid 下载(推荐)
GET http://{cti_host}:12121/Oms/FileDownServlet?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82
| 参数 | 必填 | 说明 |
|---|---|---|
| callid | 是 | 呼叫唯一标识(@ 等特殊字符需 URL 编码为 %40)。来源:呼叫记录查询的 callid、WebSocket dialog 通知的 id、点击呼叫 backid 返回的 UUID |
| type | 否 | 不传下载录音;callervideo 主叫侧视频 / calleevideo 被叫侧视频(视频通话场景) |
服务端按 callid 查呼叫记录取录音文件(无人工录音时回落机器人录音 robotrecord)。
1.2 其他录音来源定位(可选参数)
| 参数 | 说明 |
|---|---|
| robotcallid | 下载机器人录音:robotcallid=<callid>,取该话单的 robotrecord 字段(callid 无人工录音时,callid 方式已自动回落 robotrecord) |
| callid4prerecord | 下载 IVR 预录音文件(prerecord 字段) |
| judgeId | 下载质检/评价关联录音 |
| toneid | 下载语音库中某编号的提示音文件 |
旧版说明书中的
logId参数(按话单 id 下载)当前版本源码已移除,请改用callid。
1.3 按文件路径下载
GET http://{cti_host}:12121/Oms/FileDownServlet?base64file=<文件路径的Base64>
| 参数 | 必填 | 说明 |
|---|---|---|
| base64file | 是 | 服务器录音文件绝对路径的 Base64 编码(即呼叫记录 recordVoice 字段的值) |
1.4 合并关联录音(可选,旧功能)
GET http://{cti_host}:12121/Oms/FileDownServlet?allcallid=<URL编码的callid>&backpath=true
allcallid:把与该 callid 相关的所有通话录音按时间合并后提供下载。backpath=true 时不返回文件,返回 JSON。官方说明书标注该功能 3.10.355 版本后不再支持和维护(当前源码仍保留实现,新对接不建议依赖):
{ "msg": "/opt/data/records/monitor/2024-05-28/b595b42e-....wav", "success": true }
2. 响应说明
| 项 | 说明 |
|---|---|
| Content-Type | .wav → audio/x-wav;.mp3 → audio/mpeg;.mp4/.h264 → application/x-msdownload |
| 其他头 | Content-Disposition: attachment; filename=原文件名、Accept-Ranges: bytes(支持断点/拖动播放)、Access-Control-Allow-Origin: * |
| 无录音/参数无效 | 响应体为错误提示文本(非文件流) |
| 仅支持 | .wav / .mp3 / .mp4 / .h264 后缀 |
3. 在线播放示例
Accept-Ranges: bytes + 音频 Content-Type 使其可直接作为 <audio>/<video> 的 src 实现边下边播:
<audio controls preload="none"
src="http://192.168.1.80:12121/Oms/FileDownServlet?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82">
您的浏览器不支持 audio 元素
</audio>
# 下载归档
curl -o record.wav "http://192.168.1.80:12121/Oms/FileDownServlet?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82"
典型联动:通话结束(WebSocket 推送 hungup)→ 按记录 recordVoice 是否非空判断有无录音 → 有则用 callid 拼上述 URL 在线播放或下载。
4. RecordPlayerSvlet 现成播放页(返回 HTML)
OMS 话单页面"播放"按钮使用的接口:按 callid 查记录,返回一个内嵌 <audio> 标签(音频源指向 FileDownServlet)的 HTML 页面。适合不想自己做播放页的场景,直接把 URL 放进 iframe/新窗口即可。
GET http://{cti_host}:12121/Oms/RecordPlayerSvlt?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82
| 参数 | 必填 | 说明 |
|---|---|---|
| callid | 三选一 | 播放该话单录音(优先 recordVoice,回落 robotrecord),页面下方附带话单备注(cname/servicetype/manustate/record) |
| robotcallid | 三选一 | 只播机器人录音 |
| prerecordcallid | 三选一 | 播放 IVR 预录音 |
| base64file(或 bf) | 可选 | 按文件路径 Base64 播放 |
| judgeId / toneid | 可选 | 质检录音 / 语音库文件 |
| browsertype | 否 | 遗留参数,默认走 <audio> 标签 |
仅支持 .mp3/.wav,其他后缀返回错误提示页;免登录(同 FileDownServlet 的 IP 校验规则)。第三方集成一般直接用 §3 的 FileDownServlet 作 <audio> src,本接口多用于免开发的播放页。
5. PLAY_CALL_LOG_RECORD 话机播放(呼叫分机听录音)
话务员用话机接打电话、电脑无耳麦的场景:CTI 先呼叫分机,接听后通过话机播放录音;播放中可不挂机再次调用,切换播放另一条。
GET http://{cti_host}:12121/bridge/callctrl?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82&extnum=801&skipseconds=4&opt=PLAY_CALL_LOG_RECORD
| 参数 | 必填 | 说明 |
|---|---|---|
| callid | 是 | 呼叫记录 callid(该记录须有 recordVoice) |
| extnum | 是 | 接收播放的分机号,该分机会先振铃 |
| skipseconds | 否 | 从第 N 秒开始播(默认 0) |
| opt | 是 | 固定 PLAY_CALL_LOG_RECORD |
业务码(SIP 风格,见 README §3.2):200 已发起呼叫(若该分机正处于播放通话,则切换到新录音);400 参数缺失或录音文件不存在;404 无此话单或无录音;486 分机忙(非播放状态的通话占用);500 系统错误。
# 坐席页"用话机听"按钮
curl "http://192.168.1.80:12121/bridge/callctrl?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82&extnum=801&skipseconds=4&opt=PLAY_CALL_LOG_RECORD"
6. 鉴权与安全
- 默认(软参
oms.file.download.auth.offon未开启)无需登录即可下载。 - 开启后需来源 IP 在白名单(
legitimate.servlet.client.ip.prefix)或已登录 OMS;否则 302 跳转登录页。 - 跨系统集成时,建议至少开启 IP 白名单限制下载来源。
7. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
| 返回文本而非文件 | callid 无对应录音、参数拼错或文件后缀不受支持;先在呼叫记录里确认 recordVoice 非空 |
| callid 明明正确却 404/空 | @ 未 URL 编码(%40) |
| 播放无法拖动进度 | 中间代理剥掉了 Range 请求头;确认链路支持 Range |
| 大量下载后系统变慢 | 该接口在通话记录量大时有性能压力,批量拉取请错峰/限速,并考虑定期转储历史记录 |
| 视频下载得到音频 | 视频需带 type=callervideo/calleevideo 参数 |
| 旧文档的 logId 下载不可用 | 当前版本源码已移除 logId 参数,改用 callid 或 base64file |
| 话机播放返回 404 | 话单无 recordVoice(未开录音);机器人录音场景改查 robotrecord 是否非空 |