着信通話を処理する（API）

エンドツーエンドで、エージェントを設定し、電話番号に割り当て、通話を受け、文字起こしを確認します。

ターミナルから実行する、標準的な「AIで電話に応答する」フローです。 以下を行います。

1. プロンプトと音声を指定してエージェントを作成します。
2. 電話番号をプロビジョニング（または持ち込み）し、その受信ハンドラーとしてエージェントを割り当てます。
3. 番号に電話をかけます。通話ログ、文字起こし、録音を確認します。

API 呼び出しの合計: 4 回。所要時間: 5 分未満。

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

エージェントには、通話を実行するプロンプト、音声、製品ティアがまとめられています。エージェントでは、max_call_duration_seconds や ring_duration_seconds などの通話制限も設定できます。エージェントは intro_clip と intro_ring_count にも対応しており、エージェントが話し始める前に録音済みのイントロと最大2回の呼び出し音を再生できます。新しいエージェントにはタイムゾーンも必要です。エージェントが多言語対応の場合は、language_switching を設定して、言語を切り替える前に確認するか、発信者の言語に従うかを制御できます。 すべての設定フィールドについてはエージェントを参照してください。最小限の設定は次のとおりです。

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

返された id を保存します。ステップ 2 で必要です。

2. 電話番号を取得する#

発信先として使用する番号だけが必要な場合は、ThunderPhone のプールから ThunderPhone 番号を取得します。

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

レスポンスには id と E.164 形式の number が含まれます。ThunderPhone 番号は status="provisioning" で開始し、数秒以内に active になります。必要に応じて GET /v1/phone-numbers/{id} をポーリングして状態遷移を確認してください。

3. エージェントを割り当てる#

ステップ 1 のエージェントを、その番号の受信方向に関連付けます。

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

これで完了です。番号は有効になります。組織での発信通話が承認された後は、同じ PATCH で outbound_agent_id も設定できます。それまでは、API はその割り当てを 400 で拒否します。

固定の inbound_agent_id ではなく設定Webhookを介して着信通話をルーティングする場合、そのWebhookは agent_id と variables に加えて、通話ごとの timezone を返せるようになりました。

4. 通話を受ける#

電話からその番号にダイヤルします。エージェントが応答し、プロンプトに従って自己紹介して、 会話が始まります。

通話中は、 GET /v1/calls に status="in_progress" として表示されます。通話が終了すると、レコードは end_reason、duration_seconds、billable_minutes、および（最終的に） 録音 URL と AI 評価で更新されます。

着信通話は、組織の 同時通話数の上限にカウントされます（デフォルトでは進行中の通話は20件で、発信通話、Web通話、テスト通話と共有されます）。上限に達している状態で着信した通話は、エージェントが応答する前に拒否されて切断され、課金されず、終了理由が concurrent_call_limit_reached の失敗した通話として記録されます。より高い上限が必要な場合は、support@thunderphone.com にメールでお問い合わせください。

5. 結果を確認する#

最近の通話一覧を取得します。

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

文字起こしを取得します。

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

録音 URL（短時間有効な署名付き URL）を取得します。

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

telephony.complete webhookを購読している場合は、同じデータが POST としてサーバーに送信されます。詳細はcall.completeを参照してください。

エージェントに抽出フィールドが設定されている場合、完了した通話のペイロードには構造化された抽出データも含まれます。

次のステップ#