发起外呼（API）

从您自己的代码触发 AI 驱动的外呼——用于问卷调查、跟进或确认流程。

外呼功能允许您将目标号码和智能体配置交给 ThunderPhone，由 AI 代表您拨打电话。典型使用场景：

• 预约确认
• 问卷回访
• 未接来电后的“第二次尝试”跟进
• 调度式通知

前提条件#

1. 选择已启用外呼的号码

   使用您通过 VoIP 连接拥有的号码，或在“电话号码” 页面申请允许将您的 ThunderPhone 号码用于外呼。ThunderPhone 号码初始仅支持呼入。 ThunderPhone 会人工审核每项申请；审核通过后，这些号码可在获批的每日限额内拨打电话 （每日 00:00 UTC 重置）并运行营销活动，您也可以申请提高限额。客户的 VoIP 号码没有每日限额， 因此我们建议将其用于外呼。请参阅 使用您自己的号码。

2. 创建智能体

   适用于外呼的提示词通常以智能体说明自身身份和目的开始——“您好，这里是 Acme，致电是为了 确认您明天下午 3 点的预约……”将 outbound_speak_order 设置为 agent_first（默认值）。

3. 保持正余额

   如果余额 ≤ $0.00，外呼将返回 402 Payment Required。请在控制台的 组织 → 账单设置 中充值或启用自动充值。您的 sk_live_ 密钥可以通过 GET /v1/billing 查询余额，但 无法充值或更改自动充值设置。

使用已保存的智能体拨打电话#

最简单的方式——通过 ID 引用智能体：

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12
  }'

响应：

{ "call_id": 987654321, "status": "initiated" }

使用内联配置拨打电话#

如果您需要一次性提示词，不值得将其保存为智能体， 请改为传入 config。其结构与 call.incoming webhook的响应架构一致：

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

跟进通话#

同时，订阅 telephony.complete webhook——这是了解通话已结束的最快方式。如果您无法接收入站 webhook，请每隔几秒轮询一次 GET /v1/calls/{call_id}；通话结束后，记录中会包含 end_reason、duration_seconds 和录音 URL。

如果您的智能体配置为在通话后提取结构化数据，该数据会在最终处理完成后单独发送。

向已保存的智能体传递每通电话变量#

已保存的智能体可以在提示文本中使用 {{name}} 或 {{name|there}} 等占位符。当您使用 agent_id 发起出站通话时，请通过 variables 传入该通电话对应的值：

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

使用以占位符名称为键的字符串值。这些变量适用于已保存的智能体；本指南中的内联 config 示例不会使用它们。

值得处理的失败情形#

有关完整且稳定的资格代码列表以及两种 409 响应格式，请参阅出站通话参考。 如果有效号码在请求被接受后、通话发起前变得不符合条件，最终检查会返回不可重试的 409 负载。

控制等待时间#

对于因被叫方响应缓慢而长时间运行的出站通话 （IVR 菜单树、队列），可以使用 max_hold_seconds 设置上限：

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

如果在过去 N 秒内未收到任何人工语音，智能体将挂断。默认值为 900 秒（15 分钟）。

后续步骤#