phone-calls

StablePhone で AI 電話をかける

https://stablephone.dev で、AI を活用した電話をかけたり、電話番号を購入したり、x402 決済で通話の文字起こしを取得したりできます。

セットアップ

インストールとウォレットの設定については、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 エージェントへの指示（話す内容、振る舞い方。最大 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 — 添付するカスタムのキーと値のデータ

Do-Not-Call（DNC）： 電話番号が Do-Not-Call リストに登録されている場合は 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 秒ごとにポーリングします。通話は通常、max_duration に応じて 1～5 分で完了します。

音声オプション

音声	説明
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 認証を使用します（認証ヘッダーのウォレット）。

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"}'

{"token": "jwt..."} を含む 202 を返します。

手順 2：結果をポーリングする（SIWX、無料）

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

status が "complete" になるまで 3～5 秒ごとにポーリングします。

完了時のレスポンス：

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

注意事項：

• "unknown" は番号が存在するものの、状況を判定できないことを意味します（固定電話／VoIP の可能性が高いです）
• トークンは 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."
}'

コストの見積もり

タスク	コスト
1回の通話	$0.54
通話＋専用番号	$20.54
番号の月額維持費	$15.00
月10回の通話＋番号	$20.00 + $5.40 = 初月 $25.40