返回官网智能客服
实时语音开放平台

让你的呼叫系统,拥有 AI 的声音。

通过 SDK 接入应用,通过 SIP 连接现有电话系统。复用智能体、知识与业务流程。

SDK 接入SIP 接入
查看接入指南需开通语音与电话权限,并完成模型、额度和线路配置。
你的应用SDK
呼叫中心 / PBXSIP
实时语音智能体识别 · 推理 · 合成
知识与工具通话记录与分析
接入架构示意;实际可用性取决于已开通的资源与部署。
SDK / SIP

实时语音开放平台

同一套智能体,两条接入路径

进入开放平台
中国站

需开通语音与电话权限,并完成模型、额度和线路配置。

调用计费

接口文本按文本接待套餐计费;语音按语音套餐或已开通的实时语音计价结算。SDK、兼容协议和接口试听均适用。套餐包含对应 Token 消耗,不重复扣费。余额不足拒绝调用;同一幂等键重试不重复计费。

接入步骤

  1. 1
    准备智能体

    发布语音配置,完成模型、语音资源与额度检查。

  2. 2
    选择接入层

    网页复制渠道嵌入代码;服务端创建限定操作范围的 API Key。

  3. 3
    建立会话

    使用返回的传输类型、地址和会话凭证。长期密钥仅存放在服务端。

  4. 4
    验证与结束

    验证双向音频、打断、断线处理,并主动结束会话释放资源。

调用示例

接入示例JavaScript
<script src="https://YOUR_ORIGIN/widget.js" charset="utf-8"
  data-base="https://YOUR_ORIGIN"
  data-public-key="YOUR_PUBLIC_KEY"
  data-reception-mode="voice"
  data-voice="true"
  data-entry-id="YOUR_ENTRY_ID"
  data-title="云蝠在线客服"
  data-greeting="欢迎来到云蝠,有什么可以帮你?"
  data-color="#3870FF"
  data-style="floating"
  data-skin="business"
  data-position="right"
  data-offset-x="24"
  data-offset-y="24"
  data-width="380"
  data-height="740"
  data-color-scheme="light"
  data-follow-system-theme="false"
  data-language="auto"
  data-launcher-style="icon"
  data-launcher-identity="voice"
  data-launcher-text="聊一聊"
  data-radius="14,14,14,14"
  data-expand="expanded"
  data-attribution="true"
  data-resize="true"
  defer></script>

替换站点地址和渠道 / 入口 ID;先在渠道中保存语音接待配置。

应用、呼叫系统与会议助手

最佳实践

推荐架构:业务服务管理会话,媒体适配器处理双向音频,平台复用已发布的语音智能体。

下载完整攻略

会议助手

腾讯会议优先考虑官方连接器 + SIP 媒体桥。默认被点名后发言,避免抢话和音频回环。

  1. 腾讯会议 · 官方连接器
  2. SIP 参会端 · 双向媒体
  3. 会议适配器 · 发言控制
  4. 语音智能体
  1. 1
    许可

    腾讯会议的 SIP/H.323 会议室连接器为付费服务,一个接入设备占用一个连接器并发许可。先确认企业许可、主持人入会策略、设备兼容性及网络配置。

  2. 2
    入会

    由第三方 SIP 参会端或 PBX 拨打官方连接器,使用官方给出的“会议号@接入地址”规则;有密码时按官方格式处理。SIP Peer 需向腾讯单独申请,凭据在两端配置。

  3. 3
    控制

    会议创建、邀请、成员管理属于第三方会议控制层,不能代替音频流。会议号、SIP Call-ID、平台 sessionId 的映射保存在适配器服务端;这些不是 voice.start 的新增字段。

  4. 4
    双向音频

    确认参会端可接收会议声音并向会议回送 AI 声音。给 AI 的输入必须排除自身 TTS,优先使用独立参会者流或减去自身的混音;普通混音不保证说话人身份可辨。

  5. 5
    发言

    推荐主持人点击“询问 AI”或明确唤醒词触发;进入后不自动开场,同一会议同时只允许一轮回答。主持人静音、他人插话或取消时立即清空旧播放队列;这些控制需在会议适配器实现。

  6. 6
    退出

    等待室、主持人拒绝、被移出、会议结束、媒体失联都触发本地清理和 AI 会话结束。长时间静默不能用心跳、静音帧或伪造 activity 维持计费。

可用范围
API / SDK
已有会话与电话控制接口;HTTP SDK 不采集、传输或播放音频。
网页语音
已有嵌入组件和 React 三段式示例;仍需权限、资源与计费准入。
SIP 媒体
现有私有执行器仅支持本人授权的出呼试通、智能体计划、最长 120 秒;生产桥待完善。
会议助手
提供接入设计与验收攻略;尚无腾讯会议、Zoom 或 Teams 成品适配器。
国际站
语音写入和外呼暂受地域门禁限制,需先核验新加坡资源及美元计费。
真实接口

统一入口 /v1/operations/{operationId}。按操作授权;所有 POST 带稳定 Idempotency-Key,并保存 X-Request-Id。

方法操作用途
GETvoice.read检查资源;check=billing 检查额度准入
POSTvoice.start启动,返回实际 transport 与临时凭证
POSTvoice.lease仅 Go 三段式 / 对应 LiveKit 按原绑定续租
POSTvoice.end结束本人会话并触发资源回收
POSTphone-calls.dialE.164 号码拨号控制;不接受会议 SIP URI
GETphone-detail.read通过 id 查询存档状态,不是运营商实时探测
POSTphone-calls.hangup请求挂断,随后查详情确认终态
GETvoice-records.read按授权范围读取记录,不是实时转写订阅
媒体协议
  • websocket:服务端原生三段式支持 Opus、PCM16、PCMU、PCMA;G.711 为 8 kHz 单声道。使用返回的 url、ticket、reconnectToken 与 audioCodec,不手工拼接媒体地址。
  • provider-realtime:默认 PCM16。千问与豆包的原生客户端须支持 24 kHz Opus 首包 20 ms 和续包 40 ms,才可申请 preferOpusOutput。在 binary-v1 认证和 ready 中核对 outputAudioCodec,每包从 skipSamples 起只播放 samples 个样本。livekit:使用返回的 url、token、room 与 identity。openai-live:由已有 WebRTC 客户端提供 sdpOffer 并处理返回 SDP。
  • 媒体适配器建议使用 20 ms 帧和有界播放队列;按协商采样率做一次转码,避免重复重采样。断线重连要清空旧回答,不能把缓存音频重播到新的轮次。以上为实现建议,不是统一媒体 DTO。
生命周期与错误
  • 建议适配器状态:等待入会 → 已入会静默 → 被询问 → 回答 → 静默 → 退出。这些是调用方设计,不是新增公开 API 或已实现的会议事件。等待室和许可失败时不启动付费 AI。
  • 401/403 检查密钥来源、有效期、操作和账号权限;422 检查发布、资源与地域;428 完成已有验证流程;429 按 Retry-After 退避。409 或网络超时先核对原请求,不换幂等键重复拨号。
  • 通用业务 Webhook 不等于已有实时 transcript / voice.started / voice.ended 全套订阅。媒体事件遵循实际 transport;通话终态从 phone-detail.read 核对,记录从 voice-records.read 读取。
回应效率
  • 目标:用户说完到正式可听首音在热会话中尽量小于 1 秒。分别记录判停、ASR 尾包、模型首段、TTS 首包与播放器排队;按冷/热链路统计 P50/P95,这不是当前性能承诺。
  • 预热 ASR/TTS、连接及静态开场资源;识别、模型流和短句合成异步重叠。语音关闭可选思考;不能靠减少必要回答内容或静音填充来伪装提速。
  • 打断优先于排队播完,取消旧轮模型与 TTS。等待垫词默认关闭,只使用就绪缓存音频;当前原生 SIP 桥不支持该独立提示音。预热不得提前启动付费通话。
费用与静默
  • 三段式语音优先使用语音套餐分钟。企业开启余额付费并设置月上限后,不足部分按企业生效单价扣余额。SDK 返回本通可付费时长,结束时退回未用预留。每通有效时长向上取整:1–60 秒为 1 分钟,65 秒为 2 分钟。以服务端账单为准,不按供应商 token 向客户重复扣费。
  • 端到端语音独立扣钱包,不走套餐;默认 ¥0.50/分钟,按实际计费秒数折算,管理端有效配置及授权决定准入。供应商成本、线路话费和第三方连接器许可另行核对。
  • 当前付费语音在连续 60 秒无有效互动时截止并结束;截止前等待仍计入有效时长,截止后不再追加客户时长。不能按整个会议预约时长扣费,也不能因浏览器未关闭而持续挂账。
  • 会议常驻旁听不是现有短语音会话能力。按需方案只在询问时启动,结束即结算;短会话多次启动可能各占 1 分钟。若要常驻互动,需先完成专门的活动判定与计费契约,不能通过保活绕过静默截止。
上线验收
  • 双方分别负责:客户负责会议/PBX许可、入会权限和对端网络;适配方负责媒体桥、发言控制与生命周期;平台负责已公开控制契约、资源授权、记录与计费。
  • 先授权试通,再隔离 PoC,最后小流量正式接待。验收需包含入会/拒绝、双向音频、连续多轮、多人插话、AI 回声隔离、静音/取消/退出及人工兜底;未支持的功能明确阻断。
  • 验证额度不足、地域未就绪、撤销密钥、重连、重复请求与静默超过 60 秒。相同幂等键不重复创建,最终账单可与 sessionId、SIP Call-ID、业务编号逐项核对。
  • 会议成员应能识别 AI 参与者,主持人可以随时停止。按客户要求配置录音/转写保留与访问范围,不把会议密码、音频、票据或完整媒体 URL 写入普通日志。
其他会议平台
Zoom
RTMS 官方路径提供实时媒体接收,不能据此推定支持 AI 音频回注。Web Meeting SDK 官方注明用于真人场景、不支持机器人或 AI 纪要;先确认平台允许的双向通话路径。
Teams
官方 application-hosted media bot 可作为适配路线;按其 Graph 权限、管理员授权、媒体运行环境及预览限制单独实施。我们的 Node HTTP SDK 不能代替该媒体机器人。
其他平台
先核验官方是否提供双向实时媒体或获准的 SIP 入会,再设计适配器。只有会议管理 REST API、字幕或录制下载时,不能承诺会中语音发言。
官方参考
核对日期:2026-10-10。参考架构与建议参数不代表第三方链路已验收。

协议兼容

沿用现有音频客户端,接入已发布的智能体。

ESP32 固件接入
接入文档
输入 24 kHz输出 24 kHzJSON · PCM16
连接示例JavaScript
import WebSocket from 'ws';
import { YunfuVoiceClient, YunfuVoiceSocket } from './voice-client.mjs';

// Persist distinct start/end keys. Unknown results must not create another paid session.
const startRequestId = process.env.YUNFU_START_REQUEST_ID;
const endRequestId = process.env.YUNFU_END_REQUEST_ID;
if (!startRequestId || !endRequestId || startRequestId === endRequestId)
  throw Error('Set separate persisted start and end idempotency keys');
const voice = new YunfuVoiceClient({
  baseUrl: process.env.YUNFU_BASE_URL,
  apiKey: process.env.YUNFU_API_KEY,
});
const session = await voice.startSession({
  agentId: "AGENT_ID", mode: 'published', mediaProtocol: 'openai-realtime',
}, { idempotencyKey: startRequestId });
async function releaseSession() {
  try {
    await voice.endSession({sessionId: session.sessionId}, {idempotencyKey: endRequestId});
  } catch (error) {
    // Reconcile the original request; retry end with the same key and body.
    console.error('voice.end unconfirmed', {status: error?.status, requestId: error?.requestId});
  }
}
let media;
try {
  media = new YunfuVoiceSocket(session, {
    WebSocket,
    onAudio(pcm, {generation, sampleRate}) {
      // Play PCM16 samples at sampleRate. Track actual playback by generation.
    },
    clearPlayback() {
      // REQUIRED: stop your player and remove queued audio on interruption/disconnect.
    },
    onEvent(event) {
      // Speech events include source: server-vad or asr-boundary; unavailable sources are not invented.
      // yunfu.connection.recovering keeps the original session and admission.
    },
    onError(error) { console.error('Voice media', {code: error.code}); },
    onClose: releaseSession,
  });
} catch (error) {
  await releaseSession();
  throw error;
}
media.ready.catch(() => console.error('Voice was not ready; reconcile session cleanup'));
// SDK handles protocol startup, 5-second heartbeat and bounded token-based recovery.
// Feed 20 ms PCM16 mono frames; false means the frame was not accepted.
const sendAudio = pcm => media.sendAudio(pcm);
const finish = () => media.close();
// Interrupt: media.interrupt(). Only confirmed interruptions clear the player.
// After actual playback: media.confirmPlayback(generation, playedMs).
// Read current state without renewing: await voice.getSessionConnection(session.sessionId).
// For a 16 kHz device: voice.startDeviceSession({agentId: 'AGENT_ID'}, {idempotencyKey}).
// For a 16 kHz speaker, select outputSampleRate: 16000. For explicit WAV chunks, use onWav and sendWav.

服务端用 API Key 创建会话,再用返回的一次性凭证和准确 Origin 建连。长期密钥保留在服务端。

事件与范围
开始session.update
上传音频input_audio_buffer.append
接收音频response.output_audio.delta
结束session.close
就绪后再上传音频session.created → session.update → session.updated
生成结束,不等于播放结束response.output_audio.done / response.done
打断当前回复response.cancel / yunfu.interrupted
心跳 / 播放回执yunfu.ping / yunfu.playback.complete

模型、音色、提示词、工具与判停沿用已发布配置。暂不支持客户端覆盖配置、清空音频、改写历史、G.711,以及原厂 SIP/WebRTC 接口直换。千问 OpenAI Realtime 握手声明 manual_audio_commit:true 时,可发送音频后 commit,等待 input_audio_buffer.committed,再 response.create;仍须遵循播放保护。Volc JSON 是本站扩展;沿用历史 Dialogue 二进制帧的客户端可参考 Binary 子集;接入新版原厂 SDK 前逐项核对事件、鉴权和音频格式。

实际播完后再确认播放,使用 PBX 的媒体时钟;收到最后一包音频不代表已播完。

PBX / SIP → 你的媒体桥 → 兼容 WebSocket → 语音智能体

SIP 网关处理信令、编码和 RTP;此适配层负责 WebSocket 音频,不替代 SIP 线路。

API Key 仅放在业务服务端。兼容连接 ticket 必须在 connectionPolicy.ticketExpiresAt 前首次使用(三段式还受初始租约限制),握手后即被消费;使用回执中的准确 URL;设备可省略 Origin,提供时须准确匹配,不把长期密钥写入浏览器或媒体地址。网页语音优先使用托管组件或现有 WebRTC 流程,不直接套用此服务端 WebSocket 示例。

实时语音使用单声道 PCM16,Dialogue 二进制帧直接承载采样。需要 WAV 分块时选择 audio_container=wav 并等待网关确认。判停和打断遵循已发布配置;每 5 秒发送心跳,收到 yunfu.interrupted 时清除 interrupted_generation 及更早的待播音频。仅实际播放时钟可以确认匹配的 generation。结束媒体连接后仍须确认 voice.end 回执,断线事件不代表记录和会后处理已完成。

请求、回执与权限
agentId / mode当前有权访问的智能体编号;mode 必须为 published。模型、音色、提示词、工具及判停均沿用已发布快照。
mediaProtocolopenai-realtime | openai-live | volc-realtime | volc-dialogue;仅服务端 API start 可用,不能同时传 sdpOffer。
API 操作授权voice.start、voice.lease、voice.end、voice-records.read;三段式还需 voice.turn,并保留现有资源与计费准入。
connectionPolicy票据绝对到期时间 ticketExpiresAt、恢复窗口 reconnectWindowMs、resumeSupported 与 speechEvents;缺少该对象时按旧网关处理,不假设可重连。
sessionId / ticket使用准入回执的会话编号。ticket 是一次性媒体凭证,不是 API Key,也不是供应商密钥。
compatibility使用回执中的 version、protocol、url、origin、inputSampleRate、outputSampleRate、audioFormat、channels,不自行拼接入口。
browserOrigin服务端媒体桥可省略,沿用平台 Origin;客户域名需属于已授权渠道的允许列表,不能任意填写。
错误与恢复方式

首次请求前持久化 start 与 end 各自独立的幂等键。写入结果不明时先核对,或以原键、原请求体重试;不能因超时就生成新键重复创建付费会话。已消费或过期的 ticket 不可复用。通过 voice.read?sessionId 查询状态;声明 resumeSupported 的网关仅在恢复窗口内接受 reconnectToken 与 resume=1,不重建计费、不自动重新 start。

错误标识处理方式
HTTP 400 / 401核对会话、transport、ticket 时效及消费状态、准确 Origin;不要重用已消费的媒体票据。
HTTP 403 / 409核对操作或资源授权、revision 与幂等冲突;同一幂等键不能更换请求体。
HTTP 429 / 503有 Retry-After 时按其退避,并检查容量、资源和网关;创建结果不明时先核对原会话。
snapshot_owned / published_turn_policy移除客户端配置覆盖,或遵循已发布的打断策略,不静默修改智能体配置。
output_format_locked建连时选择下行采样率,首段回复开始后不要再切换。
unsupported_event / invalid_audio使用协商的容器、采样率与受支持事件。WAV 每帧携带完整头,裸 PCM 每帧只带样本;手动 commit 仅限握手声明 manual_audio_commit:true 的千问 OpenAI Realtime。
invalid_playback核对实际播放时钟与匹配的 generation;收到音频包不能当作播放完成。
native_connection_failed / native_not_ready检查网关与模型资源,保留会话编号并确认回收结果。
error / 二进制 599读取 error.code 与客户端事件关联,保留请求编号;日志不要写入 ticket、鉴权头或完整媒体地址。
官方对照与兼容边界

这里提供云蝠已实现的事件子集,不等于完整替换 OpenAI 或火山接口。火山 JSON 和事件 9000 属于本站桥接扩展;沿用历史 Dialogue 二进制帧的客户端可参考 Binary 子集;接入新版原厂 SDK 前逐项核对事件、鉴权和音频格式。供应商密钥、原厂 WebRTC/SIP 调用及 RTC StartVoiceChat 房间任务是不同契约。示例 model 标识只标记协议,不选择供应商模型;原生 OpenAI Live 资源仍使用其 WebRTC 专用路径。

完整示例 · 开箱即可运行

OrbitBook 预约管理 SaaS

在虚构的预约产品中体验真实语音接入。OrbitBook 使用平台浏览器 SDK 完成语音识别、模型回答与语音合成,业务卡片和预约数据均为示例。

浏览器 SDKASR · 模型 · TTS中文 / English
下载示例源码ZIP

包含前端与服务端源码、浏览器 SDK、预构建产物和中英双语 README;不含密钥。

在你的电脑上运行

  1. 1
    下载并解压

    安装 Node.js 22+,解压 ZIP 后进入项目目录,按 README 设置平台地址。

  2. 2
    直接启动

    已包含构建产物,无需先安装依赖。

    npm start也可以运行 node server.mjs
  3. 3
    配置你的 API Key

    打开下方地址,在“本地接入设置”中填写自己的密钥,按提示完成助手配置。

    http://127.0.0.1:4300

修改源码后重新构建: npm install && npm run build

需开通语音权限并配置模型与语音资源。真实调用沿用平台当前计费、额度与权限规则。

接口地图

统一通过操作网关调用。密钥按操作授权,接口继续检查资源归属与功能权限。

完整接口文档

智能体接入配置

  • GETvoice-access.read
  • POSTvoice-access.save
  • POSTvoice-access.disable

语音会话

  • GETvoice.read
  • POSTvoice.realtime-transport
  • POSTvoice.start
  • POSTvoice.turn
  • POSTvoice.lease
  • POSTvoice.end

线路与路由

  • GETtelephony.read
  • POSTtelephony.saveLine
  • POSTtelephony.register
  • POSTtelephony.testLine
  • GETphone-channels.read
  • POSTphone-channels.saveChannel

通话控制

  • POSTphone-calls.dial
  • POSTphone-calls.hangup
  • GETphone-calls.read
  • GETphone-detail.read

记录与导出

  • GETvoice-records.read
  • GETphone-records.export
OpenAPI · SDK / SIP/v1/operations/{operationId}
凭证、事件与上线检查

凭证与请求

  • Bearer API Key 仅用于服务端。浏览器使用渠道入口或会话凭证。
  • 写操作必须带 Idempotency-Key;超时先查状态,避免重复拨号。
  • 使用 X-Request-Id 排查请求,生产环境使用 HTTPS。

事件与结果

  • 请求完成不代表通话完成;通过通话详情核对最终状态。
  • 业务 Webhook 使用时间戳与 HMAC 签名,按事件 ID 去重。
  • 媒体事件随传输类型变化;SIP 网关回调由平台处理,不能作为业务 Webhook。

联调清单

  • 入呼 / 出呼、双向声音、静音、打断与挂断。
  • 认证过期、网络断开、并发上限和余额不足。
  • 测量用户说完到首段可听音频的 P50 / P95,区分冷启动与热会话。
查看请求日志