# LatenTX 网页语音客服 优先使用现有 SDK,让伙伴自行开发 UI。沿用项目技术栈,使用 SDK 管理连接与媒体。 WebSocket 协议拨测使用 https://api.latenth.com/realtime/ ;网页通话体验使用 https://api.latenth.com/playground 。以下流程适用于后者。 ## 实现前读取 - https://api.latenth.com/docs/phone-integration.html - https://api.latenth.com/docs/webrtc.openapi.json - https://api.latenth.com/docs/api-reference.html SDK 来源:`https://api.latenth.com/sdk/latentx-voice.js`,导出 `VoiceWebSession`。这是 SIP/WebRTC 接入,不是 OpenAI `/v1/realtime/calls` 或 `client_secrets`。正式使用固定版本副本和校验值,保留附带许可。 ## 最小接入 伙伴后端认证用户、授权模型与通话配置,再用服务器 Key 请求 `POST https://api.latenth.com/voice/v1/webrtc/credentials`。模型 ID 用平台返回值。浏览器只收到短期凭证,长期 Key 始终留在后端。 初始化 `VoiceWebSession`: ```js const session = new VoiceWebSession({ model: allowedModel, credentialEndpoint: '/api/voice-credential', // 伙伴自己的接口,不是平台路径 audioElement: document.querySelector('audio'), onStatus: showStatus, onError: showError, onEnded: resetCallUI, }); // 从用户点击中执行并捕获异常: await session.start(); // session.mute(true); session.stop(); ``` `getCredential` 可替代 credentialEndpoint,返回已解包凭证对象。SDK 支持平台 success/data 包装;具体签名以当前源码为准,不虚构字幕或工具回调。 ## UI 与生命周期 - 提供开始、静音、挂断和连接状态;避免重复开始,连接中也能取消。 - HTTPS 或 localhost,明确处理麦克风拒绝、连接超时和播放被阻止。`playback-blocked` 时提供用户点击的播放按钮。 - 结束、页面离开和组件卸载时调用 stop,释放自己创建的 MediaStream;SDK 不负责停止外部传入的 inputStream。 - 失败或凭证过期后重新申请凭证,不复用上一通。持续时间、模型和工具权限由业务后端约束,不能仅靠前端限制。 - `silence_duration_ms` 用于断句;`idle_timeout_ms` 用于无回应提醒,两者不可混为一谈。 首版只承诺音频与状态,不声称有实时字幕。历史转写查询需要 call_id 和会话归属。网页通话不支持客户端 Function 回调;需要这种能力时改用 Realtime WebSocket 并单独实现音频链路。MCP 自动执行需明确授权,不为跑通演示而打开所有工具。 ## 验收与边界 在用户授权范围内验证麦克风、真实音频、两轮以上对话、静音、打断、挂断和重开。模拟模式必须明显标记,不能使用浏览器 TTS 冒充 LatenTX。成功挂断不证明费用已经结算。 伙伴公网接入必须沿用自己的身份认证、会话归属、模型白名单和额度限制;不要把演示凭证接口直接开放给匿名用户。没有真实调用时,写明“已实现,云端音频未验证”。 ## 诊断与通话结果 按需使用 SDK `onPeerConnection`、`getStats()` 获取丢包、jitter、jitter-buffer delay 和 concealment;收到了数据包不等于音频连续。区分模型生成间隙、媒体网络和浏览器播放问题,不用服务端首包时延代替用户端可听时延。 历史转写和录音按当前文档使用 `GET /voice/v1/conversations/{call_id}`;凭证返回 billing session 时,按文档查询或结束 `/voice/v1/playground/sessions/{id}`。录音、转写和临时凭证属于私有数据,查询必须验证会话归属。开启分段录音时,也可从该会话的 /recordings 查询分段;整通文件和分段分别看状态。不要把麦克风有信号当作已转写、已接纳或已创建回复。 需要完整参考工程时,使用 [Studio Partner](https://github.com/aibpo-labs/studio-partner),按仓库 README 和适用的工程内 Skill 接入,沿用已有的网页语音组件和凭证代理。工程安装步骤以仓库文档为准,平台凭证与 SDK 契约以官方文档为准。安装本 Skill 不下载或启动工程;SDK 安装、连接成功和真实双向音频分别验证。 ## Current management contract Full schemas: https://api.latenth.com/docs/admin.openapi.json (browser subset: https://api.latenth.com/docs/webrtc.openapi.json). `asr_language`/`tts_language` must come from the selected voice model's catalog capabilities. Use published custom model IDs as before; no separate Agent registration. Built-in Knowledge search executes server-side; external MCP still requires `allow_mcp_tools:true`. Use `/playground/sessions/{session_id}` to observe accounting and asynchronous stop, and `/conversations/{call_id}` for transcript/temporary recording links.