通过 API 拨打 AI 电话并管理 Astra

API 可以配置和发布 Astra（您的 AI 助理），将号码连接到它，并让它拨打外拨电话：POST /v1/api/calls 让您已发布的助理拨打一个号码，进行对话，并将通话记录（包括录音、转录和摘要）记录在您收件箱中联系人的时间线上，费用以 AI 积分计算，与呼入的 AI 接听电话完全相同。

开始之前

• 您的 API 密钥需要正确的范围——在设置 → 开发者 API 中的芯片：管理 AI 助理 (agent:manage) 用于助理配置和号码路由，以及拨打 AI 电话 (calls:place) 用于外拨电话。完全访问密钥包含两者。请参阅获取您的 Ody API 密钥。
• 外拨电话需要一个活跃套餐，一个已发布并启用的助理，以及您的工作区中至少一个活跃号码。
• 积分使用方式与往常完全相同：每次 AI 接听电话消耗 100 积分，15 秒以下的通话免费，每个套餐每月包含 1,000 积分。请参阅Astra 积分和使用。

配置并发布您的助理

GET /v1/api/agent 返回助理的配置以及您当前周期的积分使用情况——这对于在批量通话前检查预算非常方便。PATCH /v1/api/agent 更新它：name、greeting、tone、voice、language、timezone、inHoursAction/offHoursAction（agent、voicemail、app 或 forward）、enabled 和 jobs。只有您发送的字段会更改，jobs 除外，它在提供时会被整体替换：

curl -X PATCH https://api.ody.co/v1/api/agent \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "greeting": "Thanks for calling Acme Plumbing!",
    "tone": "Friendly",
    "jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
  }'

更改会保存为草稿——与您在应用中 AI 助理屏幕上看到的草稿相同。使用以下命令将其发布上线：

curl -X POST https://api.ody.co/v1/api/agent/publish \
  -H "Authorization: Bearer ody_live_…"

将号码连接到助理

POST /v1/api/numbers/{number}/connect 将您的一个号码路由到助理，以便它接听呼入电话（将 + 进行 URL 编码为 %2B）：

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
  -H "Authorization: Bearer ody_live_…"

要将其路由回您的团队，请使用 …/disconnect，并将 mode 设置为 app（呼叫您的团队——默认）、voicemail 或 forward（带有一个 forwardTo 号码）：

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"app"}'

拨打外拨 AI 电话

POST /v1/api/calls 让您已发布的助理拨出电话并进行对话：

curl https://api.ody.co/v1/api/calls \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550199"}'

• to 是必需的 (E.164)。from 是可选的——Ody 优先使用您连接到助理的号码，然后是您的第一个活跃号码；传入 from 以选择您拥有的特定线路。
• 国际目的地遵循您工作区通常的国际通话规则——请参阅国际通话和限制。
• 通话结束后，它会出现在您收件箱中联系人的时间线上，包含录音、转录和摘要——与呼入 AI 电话的“AI 助理处理了此通话”卡片相同。
• 计费： 接听电话时消耗 100 积分，15 秒以下免费——未接听的电话始终免费。

您可以随时接管

通过 API 完成的任何操作都是您真实的账户状态——而不是一个独立的开发者沙盒。您的代码发布的助理就是AI 助理屏幕上的那个；它连接的号码在设置 → 号码中；它拨打的电话会进入您的共享收件箱。这意味着您可以随时介入：在应用中编辑问候语，亲自在对话中回复，或者点击号码的路由芯片将电话发送回您的团队——无需 API 参与。

来自 AI 助理 (MCP)

连接的 AI 助理拥有与 MCP 工具相同的权限：get_agent、configure_agent（传入 publish: true 可一步上线）、connect_agent_to_number 和 place_call。请参阅使用 MCP 连接 AI 工具。

测试模式

使用 ody_test_… 密钥，POST /calls 返回一个模拟通话（一个 sim_… ID，未拨号，不消耗积分），POST /agent/publish 也是模拟的（您的配置保持草稿状态）。通过 PATCH /agent 保存的草稿在两种密钥类型上都是真实的。请参阅使用测试模式安全构建。

相关文章

• 认识 Astra，您的 AI 接待员
• Astra 积分和使用
• 通过 API 购买号码并注册短信
• 使用 MCP 连接 AI 工具