📦 AgentPhone — 打电话订位
v1.0.1通过外部 API 实现真实拨号，可订餐厅、取消订阅、穿越 IVR 菜单，并获取通话转录与录音。
by 详细分析 ▾
运行时依赖
版本
缩短描述以适配 ClawHub 显示
安装命令
点击复制技能文档
# AgentPhone 通过 API 拨打真实电话。发送电话号码和目标，即可获得通话记录、摘要、结果和录音。 ## 设置 1. 在 https://agentphone.app 创建账户 2. 在 https://agentphone.app/dashboard/api-keys 生成 API 密钥 3. 设置环境变量： ``bash export AGENTPHONE_API_KEY=your_key_here ` 如果 AGENTPHONE_API_KEY 未设置 → 停止并报告配置错误。 ## 要求 - 所有请求必须带请求头：x-api-key: $AGENTPHONE_API_KEY - 电话号码必须为 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: $AGENTPHONE_API_KEY" \ -d '{"to_phone_number":"+1{PHONE_NUMBER}","objective":"Ask about their return policy"}' ` `python import os, requests r = requests.post("https://agentphone.app/api/v1/calls", headers={"x-api-key": os.environ["AGENTPHONE_API_KEY"]}, json={"to_phone_number": "+1{PHONE_NUMBER}", "objective": "Ask about their return policy"}) call_id = r.json()["data"]["call_id"] ` `javascript const r = await fetch("https://agentphone.app/api/v1/calls", { method: "POST", headers: { "x-api-key": process.env.AGENTPHONE_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ to_phone_number: "+1{PHONE_NUMBER}", objective: "Ask about their return policy" }), }); const { data } = await r.json(); const callId = data.call_id; ` 响应（202）： `json { "data": { "call_id": "cl_abc123", "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: $AGENTPHONE_API_KEY" ` `python import time for _ in range(100): r = requests.get(f"https://agentphone.app/api/v1/calls/{call_id}", headers={"x-api-key": os.environ["AGENTPHONE_API_KEY"]}) 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.AGENTPHONE_API_KEY }, }); 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": { "call_id": "cl_abc123", "status": "completed", "outcome": "achieved", "summary": "Successfully booked a table for 2 at 7pm.", "transcript": "Agent: Hi, I'd like to book a table...\nHost: Sure...", "recording_url": "https://...", "duration_seconds": 42 } } ` 使用以下字段： - outcome：achieved、partial 或 not_achieved - summary：简短描述通话结果 - transcript：完整对话文本 - recording_url：音频文件 URL ## 错误 | 代码 | 含义 | 操作 | |------|---------|--------| | 400 | 输入无效 | 修正字段后重试 | | 401 | API 密钥错误或缺失 | 检查 x-api-key 请求头 | | 402 | 余额不足 | 停止并告知用户 | | 429 | 限流（10 次/分钟） | 等待 60 秒后重试一次 | ## 安全限制 - 如果 AGENTPHONE_API_KEY 未设置 → 停止，不调用 API。 - 如果 to_phone_number 不是 E.164 格式 → 停止，不调用 API。 - 如果 POST /calls 返回 402 → 停止并告知余额不足。 - 如果 429 → 等待 60 秒，重试一次。若再次 429 → 停止。 - 如果 status 为 failed 或 canceled → 停止并告知用户。 ## 约束 - 禁止拨打紧急服务（911 等） - 禁止垃圾或批量骚扰电话 - 前 5 通电话免费，无需信用卡 ## 通话生命周期 queued → dialing → in_progress → completed | failed | canceled`