Twilio：用已保存的声音接听电话¶

集成 → Twilio 会以你已保存的某个声音来接听打到你的 Twilio 电话号码的电话。当有人来电时，VoiceStudio 会通过 Twilio Media Stream 说出你的问候语，然后挂断。合成在你的计算机上使用你选择的声音和引擎运行。Twilio 会收到播放给来电者的 8 kHz 电话音频。

相同的设置也可以运行通话代理，它会以你的声音拨打电话并维持对话，还可以接听来电而不是播放问候语。

该集成默认关闭。在你开启之前，不会有任何监听，也不会有任何数据离开你的计算机。开启后，它需要一个你运行的公共 HTTPS 隧道。

准备工作¶

• 一个 Twilio 账户和一个支持语音通话的电话号码。通话由 Twilio 计费。
• 一个为你的计算机提供公共 https:// 地址的隧道，例如 cloudflared 或 ngrok。Twilio 无法访问 127.0.0.1。
• VoiceStudio 中一个可用的 TTS 引擎。已保存的声音档案是可选的；如果没有，将使用引擎的默认声音。

设置¶

打开集成 → Twilio。该页面是一个引导式清单：每个步骤显示待办或已完成，标题显示整体状态（未设置、就绪、运行中），侧面板中的就绪度会跳转到尚未完成的项目。每个步骤都会单独保存。

1. Twilio 账户。 从 Twilio 控制台首页输入你的 Account SID 和 Auth Token，然后选择保存并检查。VoiceStudio 会检查格式；Twilio 会在签名你的第一次通话时确认令牌。已保存的令牌不会再显示：使用替换或移除。
2. 公共隧道。 选择 cloudflared 或 ngrok。页面会显示适用于你操作系统的安装命令，以及针对通话网关端口启动隧道的确切命令（3950，除非你设置了 OMNIVOICE_TWILIO_PORT），而不是 VoiceStudio 的主端口：

cloudflared tunnel --url http://127.0.0.1:3950
# or
ngrok http 127.0.0.1:3950

将隧道的 https://… 地址粘贴到公共隧道 URL 并保存。只使用源（origin），不要包含路径。检查会显示网关是否正在监听；它会在你开启通话时启动。如果 3950 端口已被占用，网关会使用下一个空闲端口，命令也会更新；请使用新命令重启隧道。 3. 电话号码。 复制语音回调 URL（https://<your-tunnel>/integrations/twilio/voice）。在 Twilio 控制台中，打开电话号码 → 管理 → 有效号码，选择你的号码，然后在语音配置下将来电设置为Webhook、该 URL 和 HTTP POST。保存。一旦有电话通过签名检查，该步骤就会显示已完成（被拒绝或占线的尝试不计入）。 4. 声音与行为。 选择声音（默认声音使用引擎的默认声音；标记为可呼叫的声音是你已验证的自己的声音或设计声音，也就是通话代理可能使用的声音）和引擎（活动引擎跟随你当前的引擎）。选择由什么来应答来电：播放问候语（编写问候语，最多 1,000 个字符）或 AI 代理（通话代理；这样问候语可以留空）。代理开场时使用的 AI 披露声明可在此编辑；没有代理时，添加到问候语会插入一段简短的披露声明。有些地方要求告知来电者他们听到的是 AI 声音。 5. 测试。 播放电话质量预览会将问候语重采样为 8 kHz，进行 μ-law 编码和解码，与来电者听到的完全一致。这完全在你的计算机上运行，并预先渲染问候语，因此第一次真实通话会立即开始说话。当按钮不可用时，原因会显示在按钮下方。 6. 在标题中选择开启通话。拨打你的号码；最近通话会显示每次通话的结果。

快速隧道（例如 cloudflared tunnel --url 和免费的 ngrok）通常每次重启都会获得新地址。只要地址变化，就更新公共隧道 URL 和 Twilio Webhook。否则，签名检查会失败，通话会被拒绝。

安全模型¶

• 独立监听器。 在你计算机上运行的隧道从 127.0.0.1 连接，而 VoiceStudio 的主 API 将本地调用者视为你本人。因此，电话监听器是一个独立的服务器，仅暴露 /integrations/twilio/voice、/integrations/twilio/stream 以及（对于通话代理拨出的通话）/integrations/twilio/status。所有其他路径都返回 404，包括 API 文档。切勿将隧道指向主后端端口，因为那会公开整个 API。
• 签名 Webhook。 每个 Webhook 都必须带有有效的 X-Twilio-Signature。VoiceStudio 使用你的 Auth Token，根据配置的公共 URL 和 POST 参数计算 Twilio 的 HMAC-SHA1 签名。它还要求请求的 AccountSid 与你的匹配。未签名或签名错误的请求会收到纯 403 响应。在一分钟内失败 10 次后，Webhook 会在该分钟剩余时间内返回 429。
• 每次通话的流令牌。 Twilio 不会对 WebSocket 升级进行签名。因此，Webhook 的 TwiML 包含一个随机的单次使用令牌，有效期为 60 秒，并与该通话的 CallSid 绑定。如果媒体流的 start 消息未提供该令牌，媒体流会以代码 1008 关闭。
• 机密信息保留在本地。 Auth Token 会加密存储在 VoiceStudio 的本地设置存储中。它不会再被显示、由 API 返回、记录日志，或包含在任何导出中。移除会将其删除。
• 最小化通话日志。 问候语通话仅保存在内存中，并显示通话 ID 的最后四个字符、时间、结果和所说音频的长度。VoiceStudio 不存储它们的来电者号码或来电者音频。由通话代理处理的通话会保留本地记录及转录文本（请参阅其隐私部分）。
• 关闭即关闭。 关闭集成会停止监听器。每个公共端点也会在每个请求上检查该设置。

限制¶

Docker： 监听器会绑定到容器内部的 127.0.0.1。如果你的隧道运行在另一个容器或宿主机上，请设置 OMNIVOICE_TWILIO_HOST=0.0.0.0 并发布该端口（例如 -p 127.0.0.1:3950:3950）。请仅将其发布给隧道，切勿直接暴露到你的局域网或互联网。

通话工作原理¶

1. Twilio 向 /integrations/twilio/voice 发送带签名的 POST 请求。VoiceStudio 以 TwiML 回复：<Connect><Stream> 连接到 wss://<tunnel>/integrations/twilio/stream，并将通话的 token 作为自定义参数传入，后跟 <Hangup/>。
2. Twilio 打开 WebSocket 并发送 connected 和 start。VoiceStudio 校验 token 后，通过与流式 TTS 相同的流水线逐句合成问候语。每个句子都会被重采样为 8 kHz 单声道、进行 μ-law 编码，并以 20 ms 的 media 帧（每帧 160 字节）发送，因此第一句播放时，后续句子仍在合成中。
3. 在最后一帧之后，VoiceStudio 发送一个 mark。Twilio 会在播放完成后回显该标记。随后 VoiceStudio 关闭流，Twilio 按 TwiML 执行 <Hangup/>。如果收到 stop 事件（主叫方挂断），通话会提前结束。

启用水印时，合成的音频会携带 VoiceStudio 常规的来源水印。

故障排查¶

暂未包含的功能¶

对话和外呼电话由呼叫代理处理。若要改为使用 VoiceStudio 作为你自己的智能体的语音，请参阅智能体语音。目前不支持 Plivo 和 Telnyx。它们的媒体流协议类似，因此提供商代码在设计上已预留适配器以支持它们。