Developer cookbook

発信通話を行う（API）

独自のコードからAIによる発信通話をトリガーできます。アンケート、フォローアップ、確認フローに対応します。

発信通話では、宛先番号とエージェント設定をThunderPhoneに渡すことで、AIが代わりに通話を発信します。一般的なユースケース:

• 予約確認
• アンケートの折り返し
• 不在着信後の「再試行」フォローアップ
• ディスパッチ形式の通知

前提条件#

1. VoIP番号を用意する

   発信通話には、VoIP接続を通じて from_numberを所有している必要があります。デモ番号は着信専用です。 独自の番号を持ち込むを参照してください。

2. エージェントを作成する

   発信向けのプロンプトでは、通常、エージェントが自身と目的を名乗ることから始めます。 例: 「こんにちは、明日午後3時の予約を確認するためにAcmeからお電話しています…」。 outbound_speak_orderをagent_first（デフォルト）に設定してください。

3. 残高を正に保つ

   残高が$0.00以下の場合、発信通話は402 Payment Requiredを返します。 POST /v1/billing/top-upでチャージするか、 自動リロードを有効にしてください。

保存済みエージェントで通話を発信する#

最も簡単な方法は、IDでエージェントを参照することです:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

レスポンス:

{ "call_id": 987654321, "status": "initiated" }

インライン設定で通話を発信する#

エージェントとして保存するほどではない一回限りのプロンプトを使用する場合は、 代わりにconfigを渡します。形式は call.incoming webhookの レスポンススキーマと一致します:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

通話を追跡する#

並行して、 telephony.complete webhookを購読してください。 これは通話の終了を最も迅速に把握する方法です。受信webhookを受け取れない場合は、 数秒ごとにGET /v1/calls/{call_id}をポーリングしてください。通話終了後、レコードには end_reason、duration_seconds、録音URLが含まれます。

対応すべき障害モード#

保留時間の制御#

相手先の応答が遅いために長時間化するアウトバウンド通話 （IVRツリー、キュー）は、max_hold_seconds で上限を設定できます。

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

直近 N 秒間に人の音声が受信されない場合、エージェントは通話を終了します。デフォルトは 900（15 分）です。

次のステップ#