通话桥接免费版

一款让AI代理拨打美国电话的桥接工具，通过语音AI代理完成拨号、对话与结果返回的全流程。

概述

在许多业务场景中，需要通过电话渠道获取信息或完成事务（如预约、咨询、投诉）。手动拨打电话耗时且效率低下，尤其是需要等待人工接听或处理电话菜单时。本工具通过语音AI代理代为拨打，用户只需提供通话目标与相关信息，代理完成通话后返回结构化结果。

免费版聚焦于单次外呼与基础通话指令构建能力，适合个人开发者验证AI电话代理的可行性。

接口地址：https://api.call-bridge.dev

核心能力

单次外呼

• 通过POST /call接口发起一通美国电话
• AI代理负责拨号、对话、处理电话菜单与等待
• 支持指定目标号码与详细的通话任务指令
• 通话结束后返回转写文本、结果与录音链接

输入: 用户提供单次外呼所需的指令和必要参数。 处理: 解析单次外呼的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回单次外呼的响应数据,包含状态码、结果和日志。

通话指令构建

• 通话指令（task字段）是代理唯一的信息来源
• 指令越详细，代理应对各种场景的能力越强
• 应包含：身份说明、通话目标、已知事实、问题清单、边界条件
• 代理不知道指令中未提及的信息，需充分准备

输入: 用户提供通话指令构建所需的指令和必要参数。 处理: 解析通话指令构建的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回通话指令构建的响应数据,包含状态码、结果和日志。

状态轮询

• 通话生命周期：排队→拨号中→已接通→已结束
• 通过GET /call/{call_id}轮询状态，建议每3秒一次
• 轮询直到lifecycle = "finalized"表示通话结束
• 结束后返回outcome（网络结果）、transcript（转写）、recording_url（录音）

输入: 用户提供状态轮询所需的指令和必要参数。 处理: 解析状态轮询的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回状态轮询的响应数据,包含状态码、结果和日志。

API Key管理

• 首次未认证外呼的响应中可能包含自动生成的API Key
• Key自动持久化到~/.config/call-bridge/key.json
• 后续调用自动携带Key，无需手动配置
• 用户也可手动提供自己的API Key替换

输入: 用户提供API Key管理所需的指令和必要参数。 处理: 解析API Key管理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回API Key管理的响应数据,包含状态码、结果和日志。

持久化状态

• API Key与用户电话号码持久化存储
• 用户电话号码可作为默认回拨号码复用
• 配置文件路径：~/.config/call-bridge/key.json

输入: 用户提供持久化状态所需的指令和必要参数。 处理: 解析持久化状态的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回持久化状态的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：代理拨打美国电话、的桥接工具、支持单次外呼、任务指令构建与通、话状态轮询、通话桥接免费版是、一款面向独立开发、电话代理工具、通过语音、完成通话后返回转、通话结果与录音链、并将结果结构化返、Use、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：代为咨询商家信息

用户希望了解某商家的营业时间、价格或服务范围，但不想自己打电话。提供商家电话与咨询问题清单，AI代理代为拨打并返回答案。

场景二：预约挂号或订餐

用户需要预约餐厅或挂号，提供相关信息（时间、人数、姓名等），AI代理代为完成预约流程。

场景三：信息比价

用户希望对比多个商家的报价，AI代理分别拨打各商家电话，收集价格信息后汇总对比。

快速开始

预计上手时间：约120秒。

第一步：检查API Key

输入格式

# 检查是否已有API Key
cat ~/.config/call-bridge/key.json 2>/dev/null || echo "首次使用，将在首次外呼时自动获取Key"

第二步：构建通话指令

通话指令是代理的"作战简报"，应包含：

{
  "to": "+15551234567",
  "task": "你好，我是为张先生预约的助手。请帮我预约本周六晚上7点两位用餐，姓名是张先生，电话是15559876543。如果周六满座，请询问下一个可用时间。请确认预约成功后告知预约号。"
}

第三步：发起外呼

curl -X POST https://api.call-bridge.dev/call \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: cb_sk_..." \
  -d '{
    "to": "+15551234567",
    "task": "你好，我是为张先生预约的助手。请帮我预约本周六晚上7点两位用餐..."
  }'

响应示例：

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

若响应中包含api_key，立即保存到~/.config/call-bridge/key.json。

第四步：轮询通话状态

# 每3秒轮询一次
curl -H "X-Api-Key: cb_sk_..." \
  https://api.call-bridge.dev/call/ba645d75-...

轮询直到lifecycle变为finalized：

{
  "call_id": "ba645d75-...",
  "lifecycle": "finalized",
  "outcome": "answered",
  "talk_seconds": 145,
  "transcript": "代理：你好，我想预约本周六晚上7点两位用餐...",
  "recording_url": "https://..."
}

第五步：查看结果

通话结束后：

1. 查看outcome确认网络层面的结果
2. 阅读transcript了解通话内容
3. 判断用户目标是否达成
4. 若未达成，分析缺失的信息或决策点

示例

API Key存储格式

{
  "api_key": "cb_sk_...",
  "user_phone_number": "+15559876543"
}

通话指令构建模板

语音选项

生命周期状态

最佳实践

通话指令编写

• 指令越详细越好，代理只能看到你提供的信息
• 不要让用户提供你可以自行查询的公开信息（如商家电话）
• 明确说明代理可以做什么、不能做什么
• 预判可能的验证步骤（如身份核验、OTP）并指导代理应对
• 说明语音信箱或无人接听时的处理方式

外呼时机选择

• 商家可能在早8点前、晚6点后或周末关闭，提前提示用户
• 美国电话需使用+1开头的完整格式
• 避免在深夜或清晨拨打，尊重对方作息

API Key安全

• Key持久化在~/.config/call-bridge/key.json，设置适当文件权限
• 不要在代码或日志中明文打印Key
• 定期检查Key是否有效，过期后重新获取
• 不要将Key提交到版本控制系统

结果分析

• outcome是网络层面的结果，不代表任务成功
• 必须阅读transcript判断用户目标是否达成
• 若通话被阻断，分析是信息不足还是需要人工介入
• 录音链接可辅助复盘通话质量

常见问题

Q1：提示invalid_phone（电话号码无效）？

美国电话号码必须使用+1开头的11位格式，如+15551234567。检查号码是否完整、是否包含非数字字符。

Q2：提示missing_fields（缺少必填字段）？

外呼请求必须包含to（目标号码）和task（通话指令）两个字段。确保两者都已提供且非空。

Q3：提示auth_required或invalid_api_key（认证失败）？

API Key错误或已失效。检查~/.config/call-bridge/key.json中的Key是否正确，或重新获取Key。

Q4：提示quota_exceeded或trial_exhausted（配额用尽）？

免费试用额度已用完。新用户可获得10次通话与10分钟通话时长的试用额度。通话达到5秒 talk time才算一次有效试用。

Q5：如何挂断正在进行的通话？

curl -X POST -H "X-Api-Key: cb_sk_..." \
  https://api.call-bridge.dev/call/{call_id}/hangup

Q6：能否同时拨打多个电话？

免费版仅支持单次外呼。如需并行拨打多个电话进行信息比价，请使用专业版。

已知限制

本免费体验版限制以下高级功能：

• 仅支持单次外呼，无并行拨打与批量呼叫能力
• 无实时转接（live handoff）功能，无法将用户桥接到通话中
• 无呼入号码配置，无法设置来电应答规则
• 无通话活动管理，无法跨通话保持状态
• 无个性化语音配置与呼入问候语定制
• 试用额度：10次通话或10分钟通话时长（以先到者为准）

解锁全部功能请使用专业版：call-bridge-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 网络: 需可访问https://api.call-bridge.dev
• 电话号码: 需有效的美国+1格式电话号码

依赖详情

API Key 配置

• Call Bridge API Key: 持久化在~/.config/call-bridge/key.json
• 首次获取: 首次未认证外呼的响应中自动返回Key
• 手动替换: 用户可提供自己的Key替换自动获取的Key
• 禁止: 在代码、日志或版本控制中暴露API Key
• 建议: 配置文件设置600权限，仅所有者可读写

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "通话桥接免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "call bridge"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}