通话代理：用你的声音打电话¶

通话代理可以拨出一通电话，或接听一通电话，并进行简短对话以完成一项任务。例如：“周五晚上 8 点，以 Palash 的名义订一张 2 人桌。”它会用你验证过的声音或设计的声音说话，倾听对方，并为你提供通话记录、结果和摘要。

它基于 Twilio 集成 构建：使用同一个 Twilio 账户、隧道和电话监听器。语音合成和语音识别在您的计算机上运行。对话文本会发送到您在 Settings → LLM Providers 中配置的 LLM；选择本地提供商（Ollama、LM Studio）可使其保留在您的计算机上。Twilio 负责传输通话音频。

前提条件¶

• 已设置并启用 Twilio 集成，并且您的隧道正在运行。外呼电话由 Twilio 计费。在试用账户上，Twilio 只允许您拨打已在 Twilio Console 中验证的号码。
• 您的 Twilio 电话号码（来电显示的号码）。
• Settings → LLM Providers 中的 LLM。
• 一个语音识别模型（听写模型，或默认的 Whisper 模型）。
• 一个可以拨打电话的声音：您验证为自己声音的配置文件，或设计的声音。克隆的他人声音不能拨打电话。

GET /calls/readiness 返回此清单，应用会将其显示为引导式设置。

拨打电话¶

提供号码（国际格式，例如 +14155550123）、任务简报和声音。可选：引擎、语言、仅限本次通话的披露声明，以及时间限制（默认 10 分钟，最多 30 分钟）。

1. VoiceStudio 请求 Twilio 拨打电话。默认情况下，一次只运行一个代理通话（拨出或接听）（在通话设置中最多两个）。没有队列，也没有批量拨号：每次通话都源于您自己的请求。
2. 电话接通后，代理先说披露声明。这句话不能被中断。
3. 代理陈述请求。它会倾听，检测对方是否说完，进行转写，然后回复。合成从回复的第一句话开始，以缩短停顿。
4. 如果对方打断代理说话，代理会停止说话并倾听。
5. 当任务完成或无法完成时，代理会礼貌地结束通话。当被问到简报中未涉及的问题时，它会升级给您（“needs you”）。
6. 通话结束后，VoiceStudio 会写入摘要和结果：booked、done、not_done、needs_you 或 failed。

通话进行期间，您可以查看实时转写。您也可以接管：暂停代理，然后输入它应该说的话。您可以随时挂断。

AI 披露声明¶

默认情况下，每次通话都以以下内容开头：

嗨，我是 {name} 的 AI 助手，代表其打来电话。

{name} 是通话设置中的名称；如果未设置，则使用声音配置文件的名称。您可以在通话设置中编辑此文本，并为单个通话覆盖它。您也可以将其留空。这是您的决定，也是您的责任。 许多地方要求呼叫者说明通话使用的是人工或 AI 声音（参见 法律说明）。

无论披露文本如何，代理都会被指示在有人询问时如实说明它是 AI 助手。

安全防护¶

• 仅限您自己的声音或设计的声音。 外呼会拒绝任何未验证为您自己声音且不是设计声音的配置文件（HTTP 403，voice_not_allowed）。
• 每个请求一个通话。 没有队列、列表或自动重拨。同时进行的代理通话（拨出或接听）数量默认限制为 1（最多 2 个）。超出限制的来电会收到忙音。
• 保持任务专注。 代理只执行简报中的内容，并拒绝不相关的请求。它绝不会编造简报之外关于您的事实。
• 不提供付款或身份证号码。 代理被要求绝不要提供银行卡、银行、密码或政府身份证号码。另有检查会阻止任何包含卡号或不在您简报中的 9 位及以上数字（包括以空格、破折号、点或逗号分隔的数字）的句子。代理会改说：“我无法在电话中分享那个号码。”
• 时间限制。 通话会在达到时间限制后结束（Twilio 也会强制执行）。
• 默认不录音。 参见 录音。

录音¶

默认情况下，通话不会被录音。要录音，请在通话设置中打开 Record calls，并使用声明通话已被录音的披露文本，例如“嗨，我是 Palash 的 AI 助手，本次通话正在录音”。诸如“is recorded”（已录音）、“may be recorded”（可能被录音）或“we're recording this call”（我们正在录音）等短语有效；否定形式（“this call is not recorded”（本次通话未录音））无效。没有此类声明时，即使开启了该设置，通话也不会被录音。

录音是立体声 WAV 文件（对方在左声道，代理在右声道），存储在您数据目录下的 calls/ 文件夹中。它们永远不会被上传。

来电¶

在通话设置中，Answer incoming calls with 可在以下选项之间选择：

• greeting（默认）：与之前一样，使用 Twilio 页面上的固定问候语。
• agent：代理接听，先说披露声明，然后按照来电简报执行（例如：“记下留言：询问对方是谁以及有什么事”）。它使用 Twilio 页面上的声音、引擎和语言。如果没有可用的 LLM，则在配置了问候语的情况下由问候语接听；否则来电将被拒绝并播放忙音。

法律说明¶

这不是法律建议。有关自动化和 AI 语音通话的法律因国家和州而异，您有责任遵守这些法律。例如：

• 在美国，FCC 根据 TCPA 将 AI 生成的声音视为“人工”声音。使用此类声音的通话在许多情况下需要获得被叫方的事先同意，而且多个州要求披露通话是自动化的。
• 许多司法管辖区要求在录音前获得所有相关方的同意。上述录音规则（披露文本必须说明通话已被录音）有所帮助，但在需要同意的情况下，它不能替代同意。
• 电话营销、自动语音电话和“请勿来电”规则即使对单个通话也可能适用。

将通话代理用于你本人会自己处理的普通个人事务，例如预订、预约和向商家咨询。不要用它冒充任何人。

隐私¶

• 通话记录、摘要和完整电话号码仅存储在你的本地数据库中。API 返回的号码会经过掩码处理（+1••••••0123）。
• Delete 会移除通话的记录和录音。
• 对话文本会发送给你配置的 LLM 提供商。使用本地提供商时，除通话音频外，不会有任何数据离开你的计算机。

API¶

所有路由都位于 VoiceStudio 的本地 API 上，绝不会使用电话监听器或 Twilio 隧道。桌面模式默认使用本地操作员访问。在 通话 → 来电 中，操作员可以为通过 API 密钥认证的电话开启 允许配对呼叫控制。共享 PIN 或受信任的网络不能授权呼叫控制。通话设置保留严格的管理员门槛；配对电话无法自行开启此权限。服务器模式的管理员访问权限不变。

CallRecord： {id, direction, to_masked, status, created_at, started_at, ended_at, duration_s, profile_id, brief, outcome, summary, disclosure, takeover, agent_state, recording, error, transcript?, timeline?}。对于来电，to_masked 是主叫号码。status 可以是 queued、initiated、ringing、in_progress、completed、busy、no_answer、failed 或 canceled。转写轮次为 {speaker: "agent" | "caller", text, t}，其中 t 是自通话被接听以来的秒数。可选的 source 为 disclosure 或 manual（通过 /say 说出），而 interrupted: true 标记被对方插话打断的轮次。

事件（data: {json} 行）：

• {type: "status", status, t}
• {type: "transcript", speaker, text, final, t}：代理的轮次在说话时以 final: false 流式传输，然后以 final: true 到达一次。
• {type: "agent_state", state}：listening、thinking 或 speaking。
• {type: "outcome", outcome, summary}
• {type: "ended", call: CallRecord}：最后一个事件；之后数据流关闭。

错误带有 detail: {code, message}：invalid_number、missing_brief（400）；voice_not_allowed（403）；profile_not_found（404）；not_configured、integration_disabled、listener_not_running、missing_from_number、llm_unavailable、busy、not_connected、call_ended（409）；twilio_error（502，包含 Twilio 的消息和 twilio_code）。

工作原理¶

• POST /calls 使用你的 Account SID 和 Auth Token 调用 Twilio 的 REST API（Calls.json）。Url 是电话监听器的语音 webhook，带有通话 id（?call=），StatusCallback 为 /integrations/twilio/status。Twilio 会对两者签名，VoiceStudio 会像对来电那样精确检查签名。
• 通话被接听时，webhook 会以 <Connect><Stream> 响应，其一次性令牌同时绑定 Twilio 通话和代理会话。
• 主叫方音频（8 kHz μ-law）由基于能量的语音活动检测器切分为话语（静音持续 700 ms 即结束一段话语），上采样至 16 kHz，并由听写/采集语音引擎转写。
• LLM 会收到 brief、披露声明、护栏和对话内容。它回复 SAY:、ACTION: none | end_call | escalate 以及可选的 OUTCOME: 行，并进行流式输出，这样第一句话在其余内容写入时就被合成。任何位于该格式之前的内容——例如聊天模板将开头标签预填入提示词而产生的推理——都会被保留下来，绝不会被说出或记录。
• 回复使用所选语音的流式 TTS 管线进行合成，重采样为 8 kHz μ-law，并以 20 ms 帧发送。在插话（barge-in）情况下（代理说话时对方约 200 ms 的语音），VoiceStudio 会向 Twilio 发送 clear 以丢弃缓冲音频。