phone-calls

使用 StablePhone 拨打 AI 电话

通过 https://stablephone.dev 使用 x402 付款，拨打 AI 电话、购买电话号码并获取通话记录。

设置

安装和钱包设置请参阅 rules/getting-started.md。

快速参考

任务	接口端点	价格
拨打电话	https://stablephone.dev/api/call	$0.54
检查通话状态	GET https://stablephone.dev/api/call/{call_id}	免费
购买电话号码	https://stablephone.dev/api/number	$20.00
为号码充值（30 天）	https://stablephone.dev/api/number/topup	$15.00
列出你的号码	GET https://stablephone.dev/api/numbers	免费
iMessage/FaceTime 查询	https://stablephone.dev/api/lookup	$0.05
查询状态	GET https://stablephone.dev/api/lookup/status?token=...	免费

拨打电话

npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{
  "phone_number": "+14155551234",
  "task": "Call this person and ask if they are available for a meeting tomorrow at 2pm. Be polite and professional."
}'

必填：

• phone_number — E.164 格式，仅支持美国/加拿大的 +1 号码（例如 +14155551234）
• task — 给 AI Agent 的指令（说什么、如何表现；最多 4000 个字符）

可选：

• from — 外呼来电显示号码（必须是有效的 StablePhone 号码，格式为 +1）
• first_sentence — 指定开场白
• voice — 语音预设（见下方的语音选项）
• max_duration — 最长通话时间（分钟，1-30，默认 5）
• wait_for_greeting — 等待接听方先说话（默认 false）
• record — 录制通话音频（默认 true）
• model — "base"（默认，质量最佳）或 "turbo"（延迟最低）
• transfer_phone_number — 来电者要求人工服务时转接到的号码
• voicemail_action — "hangup"（默认）、"leave_message" 或 "ignore"
• voicemail_message — 要留言的内容（当操作为 "leave_message" 时必填）
• metadata — 要附加的自定义键值数据

拒接来电名单（DNC）： 如果号码在拒接来电名单中，则返回 403；不要重试 DNC 号码。

检查通话状态

轮询，直到 completed 为 true：

npx agentcash@latest fetch https://stablephone.dev/api/call/{call_id}

响应字段：

• status — 通话状态
• completed — 布尔值，通话结束时为 true
• answered_by — "human"、"voicemail" 或 "no_answer"
• call_length — 通话时长，单位为秒
• summary — AI 生成的通话摘要
• transcript — 完整的文字通话记录
• transcripts — 带时间戳的通话记录片段数组
• recording_url — 通话录音的 URL
• price — 实际费用

每隔 5-10 秒轮询一次。通话通常会在 1-5 分钟内结束，具体取决于 max_duration。

语音选项

语音	描述
nat	美式英语女声（默认）
josh	发音清晰的美式英语男声
maya	年轻、轻柔的美式英语女声
june	美式英语女声
paige	平和、柔和的女声
derek	柔和、亲切的男声
florian	德语男声

购买电话号码

购买号码用作外呼来电显示号码：

npx agentcash@latest fetch https://stablephone.dev/api/number -m POST -b '{"area_code": "415", "country_code": "US"}'

可选：

• area_code — 3 位数的美国/加拿大区号（省略时随机分配）
• country_code — "US"（默认）或 "CA"

号码会在 30 天后过期。充值可延长有效期。

为号码充值

npx agentcash@latest fetch https://stablephone.dev/api/number/topup -m POST -b '{"phone_number": "+14155551234"}'

从当前到期时间起延长 30 天。多次充值的时长会累加。任何人都可以为任何号码充值。

列出你的号码

使用 SIWX 身份验证（从 auth header 获取钱包）：

npx agentcash@latest fetch https://stablephone.dev/api/numbers

iMessage/FaceTime 查询

检查电话号码是否支持 iMessage 或 FaceTime。查询为异步操作（30-90 秒）。

步骤 1：开始查询（付费，$0.05）

npx agentcash@latest fetch https://stablephone.dev/api/lookup -m POST -b '{"phone_number": "+14155551234"}'

返回 202 和 {"token": "jwt..."}。

步骤 2：轮询结果（SIWX，免费）

npx agentcash@latest fetch "https://stablephone.dev/api/lookup/status?token=JWT_TOKEN"

每隔 3-5 秒轮询一次，直到 status 为 "complete"。

完成时的响应：

{
  "status": "complete",
  "phone_number": "+1...",
  "imessage": "available|unavailable|unknown",
  "facetime": "available|unavailable|unknown|pending",
  "carrier": {"carrier": "...", "number_type": "..."},
  "country": {"name": "...", "iso2": "...", "flag": "..."}
}

注意：

• "unknown" 表示该号码存在，但无法确定其状态（可能是固定电话/VoIP）
• Token 会在 60 分钟后过期
• 大约 1 小时内查询同一号码会复用缓存结果

工作流

快速拨打电话

• （可选）检查余额：npx agentcash@latest balance
• 根据任务说明拨打电话
• 轮询状态，直到通话结束
• 查看通话记录和摘要

npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{
  "phone_number": "+14155551234",
  "task": "Ask if the business is open on weekends and what their hours are."
}'

留下语音留言

npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{
  "phone_number": "+14155551234",
  "task": "Leave a voicemail about the appointment.",
  "voicemail_action": "leave_message",
  "voicemail_message": "Hi, this is a reminder about your appointment tomorrow at 3pm. Please call back to confirm."
}'

如需自然地留下语音留言，请使用 "voicemail_action": "ignore"，这样可以绕过检测，让 AI 在语音信箱系统中自然地说话。

转接通话

npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{
  "phone_number": "+14155551234",
  "task": "Qualify this lead. Ask about their budget and timeline. If they are interested, offer to transfer to a sales rep.",
  "transfer_phone_number": "+14155559999",
  "voice": "josh",
  "max_duration": 10
}'

设置专用号码

• 购买电话号码（$20）
• 将其用作外拨电话的来电显示号码
• 在到期前充值（$15/30 天）

npx agentcash@latest fetch https://stablephone.dev/api/number -m POST -b '{"area_code": "212", "country_code": "US"}'

然后将其用作 from：

npx agentcash@latest fetch https://stablephone.dev/api/call -m POST -b '{
  "phone_number": "+14155551234",
  "from": "+12125551234",
  "task": "Confirm the reservation for Friday at 7pm."
}'

费用估算

任务	费用
单次通话	$0.54
通话 + 专用号码	$20.54
号码月度维护	$15.00
每月 10 次通话 + 号码	$20.00 + $5.40 = 首月 $25.40