AgentPhone

通过API拨打真实电话。发送电话号码和目标，获取通话记录、摘要、结果和录音。

设置

1. 1. 在 https://agentphone.app 创建账户
2. 在 https://agentphone.app/dashboard/api-keys 生成API密钥
3. 设置环境变量：

bash
export AGENTPHONEAPIKEY=yourkeyhere

如果未设置 AGENTPHONEAPIKEY → 停止并报告配置错误。

要求

• - 所有请求都需要请求头：x-api-key: $AGENTPHONEAPIKEY
• 电话号码必须为E.164格式（例如 +14155551234）
• 重要提示：以下所有示例中的 +1{PHONE_NUMBER} 是占位变量。切勿直接按字面调用。请替换为用户提供的真实目标电话号码。

1) 创建通话

bash
curl -X POST https://agentphone.app/api/v1/calls \
-H Content-Type: application/json \
-H x-api-key: $AGENTPHONEAPIKEY \
-d {tophonenumber:+1{PHONE_NUMBER},objective:询问他们的退货政策}

python
import os, requests
r = requests.post(https://agentphone.app/api/v1/calls,
headers={x-api-key: os.environ[AGENTPHONEAPIKEY]},
json={tophonenumber: +1{PHONE_NUMBER}, objective: 询问他们的退货政策})
callid = r.json()[data][callid]

javascript
const r = await fetch(https://agentphone.app/api/v1/calls, {
method: POST,
headers: { x-api-key: process.env.AGENTPHONEAPIKEY, Content-Type: application/json },
body: JSON.stringify({ tophonenumber: +1{PHONE_NUMBER}, objective: 询问他们的退货政策 }),
});
const { data } = await r.json();
const callId = data.call_id;

响应（202）：

json
{
data: {
callid: clabc123,
status: queued,
created_at: 2026-01-01T00:00:00Z
},
credits_remaining: 4
}

保存 call_id 用于轮询。

可选字段：business_name（字符串），website（URL — 代理在通话前会抓取网站内容作为上下文）。

2) 轮询直到完成

每10秒轮询 GET /calls/{callId}。当 status 为 completed、failed 或 canceled 时停止。5分钟后超时。

bash
curl https://agentphone.app/api/v1/calls/CALL_ID \
-H x-api-key: $AGENTPHONEAPIKEY

python
import time
for _ in range(100):
r = requests.get(fhttps://agentphone.app/api/v1/calls/{call_id},
headers={x-api-key: os.environ[AGENTPHONEAPIKEY]})
call = r.json()[data]
if call[status] in (completed, failed, canceled):
break
time.sleep(10)

javascript
let call;
for (let i = 0; i < 100; i++) {
const r = await fetch(https://agentphone.app/api/v1/calls/${callId}, {
headers: { x-api-key: process.env.AGENTPHONEAPIKEY },
});
call = (await r.json()).data;
if ([completed, failed, canceled].includes(call.status)) break;
await new Promise((r) => setTimeout(r, 10000));
}

如果 status 为 completed 但缺少 transcript 或 summary，再轮询2次，每次延迟2秒 — 通话完成不久后补充信息会到达。

3) 读取结果

json
{
data: {
callid: clabc123,
status: completed,
outcome: achieved,
summary: 成功预订了晚上7点2人桌。,
transcript: 代理：您好，我想预订一张桌子...\n接待员：好的...,
recording_url: https://...,
duration_seconds: 42
}
}

使用这些字段：

• - outcome：achieved（已达成）、partial（部分达成）或 notachieved（未达成）
• summary：事件简要描述
• transcript：完整对话文本
• recordingurl：音频文件URL

错误

安全护栏

• - 如果未设置 AGENTPHONEAPIKEY → 停止，不调用API。
• 如果 tophonenumber 不是E.164格式 → 停止，不调用API。
• 如果 POST /calls 返回402 → 停止并报告积分不足。
• 如果返回429 → 等待60秒，重试一次。如果再次返回429 → 停止。
• 如果 status 为 failed 或 canceled → 停止并向用户报告。

限制

• - 禁止紧急服务（911等）
• 禁止垃圾邮件或批量未经请求的电话
• 前5次通话免费，无需信用卡

通话生命周期

queued（排队中） → dialing（拨号中） → in_progress（进行中） → completed（已完成） | failed（失败） | canceled（已取消）