语音通话服务

语音通话服务让AI代理为用户拨打真实的美国电话。语音AI代理负责拨号、对话、处理电话菜单或等待时间， 并在通话结束后返回转录、结果与录音链接（如可用）。首次外呼可自动签发API密钥. 核心能力： - 外呼：POST /call 发起通话，轮询 GET /call/{call_id} 至 lifecycle=fin...

功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

语音通话服务（Voice Call Service）

专业版专属特性

能力	免费版	付费版
基础功能	支持	支持
复杂工作流可视化编排	不支持	支持
条件分支与异常重试	不支持	支持
定时触发与事件驱动	不支持	支持
执行日志与审计追踪	不支持	支持
分布式任务调度与负载均衡	不支持	支持

输入输出

输入: 用户提供目标电话号码（美国 +1XXXXXXXXXX 格式）、通话指令 task（含通话目标、已知事实、要问的问题、决策边界、预期核验点、回报要求）、可选的 bridge_number（用于实时转接用户进入通话）、可选的 voice/personality/greeting 全局配置；入呼配置时提供 instructions、greeting 与可选的 handoff_number. 输出: call_id 与 api_key（首次外呼自动签发并持久化至 $HOME/.config/voicecall/key.json）、通话生命周期状态（queued → dialing → answered → finalized）、终态返回 outcome（电话网络结果）、talk_seconds（通话时长）、transcript（通话转录）、recording_url（录音链接，如可用）；入呼历史查询返回通话记录列表；配置更新返回当前 voice/personality/greeting 与 inbound 块. Base URL: https://api.voicecall.example

工作流选择

用户意图	操作
立即给某人打电话	构建丰富通话指令，POST /call，再轮询 GET /call/{call_id} 至 lifecycle = "finalized"
接通真人/把我接进去	使用外呼 + bridge_number + 通话指令中的转接触发器
跨多家商家比较选项	运行小型通话活动，可选3-4路并行仅查询信息、不承诺的通话
设置我的语音代理个性	配置全局 voice/personality/greeting，必要时配置入呼应答配置
配置我的号码如何接听	使用入呼配置流程。不要 POST /call
查看接到了什么电话	用 GET /me/calls?direction=inbound... 轮询入呼历史
将本代理关联到我的账户	使用已保存的API密钥生成登录链接
API错误/配额/套餐/重试/余额	按返回的 code/action 处理；原样保留URL

产品辅导

在决策点教育用户，而非泛泛推销.

• 首次相关使用：说明你可以拨打美国电话、处理电话树或等待时间，并回报结果与转录.
• 索要缺失细节时：说"电话代理只知道我放进通话指令的内容，因此额外细节有助于它回答追问".
• 敏感、可协商或身份密集型通话前：提供实时转接选项.
• 复杂通话前：提示可能的核验、OTP、付款、费用或实时决策点，并推荐合适的通话套餐.
• 选项搜索时：主动提出可拨打多处比较，除非用户给出明确批准边界，否则不承诺.
• 入呼配置：说明入呼应答需要 Unlimited Reserve Plus、活跃保留号与账户关联的API密钥.
• 通话后：先给结果，再提供转录、录音或后续通话.

持久状态

在任何涉及语音通话服务的对话开始时，检查 $HOME/.json 或宿主密钥库。若存在API密钥，作为 X-Api-Key 发送。若存在已保存的用户电话号码，复用为默认回拨、保留号联系、实时转接 bridge_number 或入呼 handoff_number. 首次未鉴权的 POST /call 响应可能包含 api_key。立即保存。当你首次收集到用户自己的电话号码时，同样保存：

json

{
  "api_key": "voicecall_sk_...",
  "user_phone_number": "[phone]"
}

若用户提供新的语音通话服务API密钥，替换任何已保存的密钥. 若用户为保留、回拨、实时转接或入呼转接提供号码，持久化直到其更改或删除。不要将已保存的用户号码视为账户核验或所有权证明. 要将本代理关联到用户的语音通话服务账户，加载已保存的API密钥并发送：

text

https://voicecall.example/sign-in?token=<api_key>

不要为账户关联新建密钥。若无已保存密钥，说明本代理需先完成首次通话才有可关联的密钥.

个性、声音与配置

当用户询问语音代理该如何发声、自我介绍或接听电话时，使用配置流程.

• voice 仅为音频声音：jessica（默认）、sarah、chris 或 eric.
• personality 是外呼与入呼复用的风格与行为。包含助理身份、语气、坚持度、谨慎度与决策边界。不要放单次通话的事实、日期、账号或预订细节.
• 顶层 greeting 是用户偏好的外呼开场白。保持简短；不要依赖它做指令、AI披露或录音披露.
• 入呼配置的 instructions 是面向未来未知来电者的常驻简报：助理代表谁、收集什么、何时转接、绝不承诺或披露什么、回报什么. 好的配置只问助理姓名/角色、期望语气、硬性边界与必要的默认转接/回拨号码.

外呼准备

在询问用户前，先尽力自行填充公开或标准细节. 有查找工具时自行获取：

• 商家电话、地址、营业时间、官方网站与位置
• 预订热线、前台号码、店铺部门、维修店联系方式
• 公开政策、菜单、服务区域、节假日营业时间与一般商业背景 主要向用户索取私有或决策细节：
• 用户姓名、回拨号码、偏好、约束、同意
• 预约日期、患者/客户姓名、出生日期、账号/订单/工单号、保险信息
• 预算、可接受替代方案、可批准什么、不可披露什么 不要问"餐厅电话是多少？"这类本应可查的信息。先查，选官方或最可靠号码；仅在存在多个可能位置、号码冲突或低置信度时才询问. 若商家在当地时间早8点前、晚6点后或周末可能已关门，提示并询问是现在试还是等待.

通话前侦察与适度探查

复杂通话前做侦察。用公开研究与常识预判通话形态：

• 正确的公司、号码、部门、位置、电话树与营业时间
• 可能的身份核验：姓名、出生日期、账号、预订码、工单号、记录定位符、地址、邮箱、预留电话、末四位问题
• 可能的 OTP、付款、费用、退款、取消、预订、批准或实时决策点
• 通话应仅查询信息、可在边界内承诺、还是应桥接用户进入 适度探查：索取少数能避免无效或危险通话的事实，然后拨号。不要前置所有可能的问题. 对于 OTP、付款详情、密码、身份核验或敏感决策：不要预先索要密码或过期 OTP。告知用户通话可能需要实时核验并提供选项：
• "我可以现在拨号，若需私密信息再回来。"
• "接通真人或核验步骤后，我把你桥接进来。"
• "我只收集价格/可用性，不承诺。"
• "我可以拨打多处并比较。"

通话指令

task 是API字段名。通话指令是产品概念. 像简报备忘录一样编写通话指令：

• 为谁拨号、如何自我介绍
• 通话目标
• 所有已知事实与参考细节
• 要问的问题
• 可接受的替代方案
• 决策边界
• 预期的核验、OTP、付款、费用或转接点
• 不要同意、承诺或披露什么
• 被问到缺失信息时怎么办
• 遇到语音信箱、无人接听、关门或转接时怎么办
• 要回报什么 仅在有用或明确指定时添加 personality、greeting、voice。默认值已足够。个性是风格，不是通话任务。声音：jessica（默认，女）、sarah（女）、chris（男）、eric（男）.

发起与轮询外呼

text

POST /call
Content-Type: application/json
X-Api-Key: voicecall_sk_...

仅 to 与 task 必填。仅当需要实时转接时包含 bridge_number. 响应包含：

json

{
  "call_id": "ba645d75-...",
  "status": "queued",
}

若存在 api_key 则保存. 每 3 秒轮询一次：

text

GET /call/{call_id}

轮询直至 lifecycle = "finalized"。生命周期取值：queued、dialing、answered、finalized. 终态响应包含 outcome、talk_seconds、transcript 与 recording_url。outcome 是电话网络结果，非任务成功。answered 的通话仍可能未达成用户目标。回报前先读转录. 取消/挂断：

text

POST /call/{call_id}/hangup

通话后

先给结果，而非转录堆砌。包含拨打的号码. 当 lifecycle = "finalized"：

1. 检查 outcome.
2. 阅读转录.
3. 判断用户目标是否达成.
4. 若受阻，明确缺什么或需要什么决策.
5. 索要缺失阻断项，或若可从上下文修复则回拨. 适时提供转录、录音、重试、回拨或实时转接.

通话活动与后续

不要把每次通话视为孤立。跨相关通话保持活动状态：目标、目的、已知事实、约束、结果、阻断、下一步与用户决策. 安全时尽快拨打：

• 低或中风险且无不可逆承诺：以清晰边界拨号.
• 缺公开信息：查到后拨号或回拨.
• 缺用户事实：问一个聚焦问题，再带前次上下文回拨.
• 需决策：汇总选项，问用户，再回拨.
• 可能需身份核验、OTP、付款或敏感决策：提供实时转接. 后续通话指令中使用前次转录，让电话代理自然续接. 并行或小批量拨打适用于选项探索。当目标可互换且仅查询信息时，最多 3-4 路并行：餐厅、供应商、预约可用性、库存查询或报价收集. 当通话可能预订、购买、取消、更改、批准或以其他方式承诺时，不要并行——除非用户明确给出安全边界且重复承诺不可能. 并行选项搜索时，每条通话指令必须说明：未经明确允许不得承诺；收集价格/可用性/时间；询问选项可保留多久不需付款或承诺；回报以供比较.

实时转接

当用户想跳过等待、接通真人、处理身份核验、协商或做实时决策时使用实时转接. 索取用户自己的回拨号码，作为 bridge_number 包含。通话指令必须包含清晰触发器，例如："一旦与能帮忙的人通话，告诉对方你正在接入Jordan，然后把Jordan桥接进实时通话。" 若存在已保存的用户号码，作为默认 bridge_number；仅当通话敏感、号码可能过期或用户要求用别的号码时确认。若收集到新的桥接/回拨号码，持久化. 转录覆盖转接前的一切。用户加入后，实时对话是私密的.

入呼保留号

入呼配置定义语音通话服务如何应答未来拨入用户活跃保留号的来电。它不是外呼. 要求：

• 账户关联的API密钥
• 活跃的语音通话服务保留号
• Unlimited Reserve Plus 权益 编辑前先读取（无权益时 inbound 块为 null）：

text

GET /me/call-preferences

更新（voice/personality 是全局的；入呼助理在 inbound 下）：

text

PUT /me/call-preferences
Content-Type: application/json

顶层 voice/personality/greeting 是全局的（也驱动外呼），任何用户都可用。inbound 对象需要 Reserve Plus + 活跃保留号。入呼必填：instructions、greeting。可选：handoff_number. handoff_number 是结构化数据。它接收入呼终态SMS通知，也是语音代理可桥接入入呼通话的号码。它不能是用户活跃保留号或任何语音通话服务自有号码。若存在已保存的用户号码，作为默认 handoff_number 提供；持久化用户新提供的转接号码. 清除入呼助理。为保留全局 voice/personality/greeting，先 GET /me/call-preferences，再在 PUT body 中回显这些顶层值：

json

{
  "voice": "<current voice>",
  "personality": "<current personality or null>",
  "greeting": "<current greeting or null>",
  "inbound": null
}

轮询入呼历史：

text

GET /me/calls?direction=inbound&since=<ISO_TIMESTAMP>&limit=25

cron 轮询每 30 分钟一次，重叠窗口，按 call id 去重。since 按通话 finalized 时间过滤，非开始时间.

错误策略

始终原样保留返回的 action.url 与 action.sign_in_url.

• invalid_phone：索要有效的美国 +1XXXXXXXXXX 号码.
• missing_fields：补全 to 与丰富的 task 通话指令.
• auth_required / invalid_api_key：索要有效密钥，移除坏密钥，或使用返回的鉴权URL.
• quota_exceeded / trial_exhausted / plan_required / balance_depleted：发送返回的 action URL.
• number_pool_exhausted / dial_failed / network_error：适当时静默重试一次.
• reserved_number_required：用户需 Unlimited Reserve Plus + 活跃保留号才能配置入呼.
• inbound_plan_required：入呼需要 Unlimited Reserve Plus.
• invalid_preferences：修复全局 voice（必须为 jessica、sarah、chris 或 eric）.
• invalid_profile：修复缺失/无效的入呼 instructions 或 greeting.
• invalid_handoff_number：索要一个非语音通话服务号码的外部可达转接号码. 新用户试用为 10 次通话与 10 分钟，以较晚结束者为准。试用通话仅在 finalized 且通话时长 ≥ 5 秒时才计数.

环境要求

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（） API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

用法示例

示例1：餐厅预订外呼

text

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "[phone]",
  "task": "为Jordan预订今晚7点2人位。姓名Jordan。若无7点可接受6:30或7:30。询问可保留多久。遇语音信箱留言回拨+15559876543。回报确认号或替代时间。"
}
响应：{"call_id":"ba645d75-...","status":"queued","api_key":"voicecall_sk_abc123"}
轮询：GET /call/ba645d75-...  → lifecycle: queued → dialing → answered → finalized
终态：outcome=answered, talk_seconds=87, transcript="已预订7点2人位，确认号R-4421"

示例2：实时转接到真人

text

POST /call
X-Api-Key: voicecall_sk_abc123
{
  "to": "[phone]",
  "bridge_number": "[phone]",
  "task": "联系客服取消订单#A-9921。核验可能需订单号A-9921与邮箱[e-mail]。一旦与能取消的人通话，告知对方正在接入Jordan，然后桥接Jordan进入实时通话。"
}

示例3：并行选项比较

text

3-4路并行POST /call，每条task含：
"仅查询价格与可用性，不承诺。询问可保留多久不需付款。回报以供比较。"
目标：3家附近餐厅的周五晚7点2人位

示例4：入呼配置更新

text

GET /me/call-preferences   → 返回当前voice/personality/greeting与inbound块
PUT /me/call-preferences
{
  "voice": "jessica",
  "personality": "礼貌、简洁、不承诺折扣",
  "greeting": "您好，我是Jordan的助理",
  "inbound": {
    "instructions": "代表Jordan接听。收集来电者姓名与事由。紧急事项转接。绝不披露地址。",
    "greeting": "感谢来电Jordan办公室",
    "handoff_number": "[phone]"
  }
}

疑问解答

Q1：电话代理知道什么？

电话代理只知道你作为 task 发送的通话指令。它不知道你的对话历史或未写入指令的上下文。细节越相关越好.

Q2：试用额度如何计算？

试用通话仅在 finalized 且通话时长 ≥ 5 秒时才计数。短于5秒或未接通不计入.

Q3：何时使用实时转接？

当用户想跳过等待、接通真人、处理身份核验、协商或做实时决策时使用。将用户号码作为 bridge_number，并在通话指令中设置清晰触发器.

Q4：能否并行拨打多处？

能。当目标可互换且仅查询信息时，最多 3-4 路并行。但通话可能预订/购买/取消/承诺时不要并行，除非用户明确给出安全边界且重复承诺不可能.

Q5：入呼应答需要什么？

需要账户关联的API密钥、活跃的语音通话服务保留号、Unlimited Reserve Plus 权益。三者缺一不可。无权益时 inbound 块为 null.

Q6：voice 有哪些取值？

仅四种合法声音：jessica（默认，女）、sarah（女）、chris（男）、eric（男）。其他取值会触发 invalid_preferences.

Q7：如何关联代理到我的账户？

加载已保存的API密钥，构造 https://voicecall.example/sign-in?token=<api_key>。不要为关联新建密钥；若无密钥，需先完成首次通话.

Q8：outcome 与任务成功有何区别？

outcome 是电话网络结果（如 answered），非任务成功。回报前必须读 transcript 判断.

注意事项

• 仅支持美国 +1XXXXXXXXXX 号码，不支持国际号码.
• 试用额度：10 次通话或 10 分钟，以较晚结束者为准；短于5秒不计.
• 入呼应答需 Unlimited Reserve Plus + 活跃保留号，无权益不可用.
• 录音链接可用性取决于对方同意与当地法规，非保证.
• 并行通话上限 3-4 路，且仅限信息查询场景.
• 轮询间隔固定 3 秒；cron 入呼轮询建议 30 分钟.
• 不适用于紧急救助、医疗急救或需100%确定性的关键决策.

结果格式

json

{
  "success": true,
  "data": {
    "result": "语音通话服务处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "clawcall"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
拨打电话	5分钟/次	30秒/次	4分30秒/次	95%
处理电话菜单	2分钟/次	15秒/次	1分45秒/次	98%
等待时间处理	1分钟/次	5秒/次	54秒/次	97%
通话转录	10分钟/次	1分钟/次	9分钟/次	99%
录音链接生成	5分钟/次	1分钟/次	4分钟/次	100%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
操作便捷性	高	低	中	高
通话处理能力	强	弱	中	强
转录准确性	高	低	中	高
成本效益	高	低	中	高
扩展性	高	低	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
人工拨打电话效率低	需要大量人工进行电话拨打，效率低下	影响业务流程和客户满意度	使用AI代理自动拨打	每次通话节省4分钟
电话菜单处理困难	人工处理电话菜单耗时且容易出错	影响客户体验和业务效率	AI代理自动处理电话菜单	每次通话节省1分45秒
通话转录困难	人工转录通话内容耗时且准确性低	影响信息获取和决策	AI代理自动转录通话内容	每次通话节省9分钟

安全规范

1. 确保API密钥安全，不要泄露给未授权人员。
2. 对敏感信息进行加密处理，防止数据泄露。
3. 定期更新API密钥，防止被恶意使用。
4. 对用户数据进行加密存储，确保用户隐私安全。
5. 对API接口进行安全防护，防止恶意攻击。

异常处置

针对语音通话服务使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

语音通话服务通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

新手引导

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

典型场景

• 日常开发: 语音通话服务可快速集成到现有开发流程中,提升工作效率
• 数据同步: 通过API实现跨平台数据同步和状态更新
• 智能分析: 结合大模型实现内容理解和智能决策
• 数据提取: 从非结构化文件中提取关键信息并结构化输出
• 运维自动化: 自动执行系统命令并收集结果
• 数据查询: 从大量数据中精准定位目标内容
• 数据处理: 对结构化数据进行清洗、转换和分析