---
title: "着信通話を処理する（API）"
description: "エンドツーエンドで、エージェントを設定し、電話番号に割り当て、通話を受け、文字起こしを確認します。"
---
初めてのエージェントを手作業で構築しますか？ダッシュボードでは、このフローをそのまま
ガイド付きウィザードで案内します。エージェントの構築、番号の追加、シミュレーション、確認を
行います。まずは
[ダッシュボードのクイックスタート](/ja/quickstart-dashboard)をご覧ください。
ターミナルから実行する、標準的な「AIで電話に応答する」フローです。
以下を行います。
1. プロンプトと音声を指定してエージェントを作成します。
2. 電話番号をプロビジョニング（または持ち込み）し、その受信ハンドラーとしてエージェントを割り当てます。
3. 番号に電話をかけます。通話ログ、文字起こし、録音を確認します。
API 呼び出しの合計: 4 回。所要時間: 5 分未満。
## 1. エージェントを作成する
エージェントには、通話を実行するプロンプト、音声、製品ティアがまとめられています。エージェントでは、`max_call_duration_seconds`
や `ring_duration_seconds` などの通話制限も設定できます。エージェントは `intro_clip`
と `intro_ring_count` にも対応しており、エージェントが話し始める前に録音済みのイントロと最大2回の呼び出し音を再生できます。新しいエージェントにはタイムゾーンも必要です。エージェントが多言語対応の場合は、`language_switching` を設定して、言語を切り替える前に確認するか、発信者の言語に従うかを制御できます。
すべての設定フィールドについては[エージェント](/api-reference/agents)を参照してください。最小限の設定は次のとおりです。
```bash
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 で必要です。
最低コストで単純な Q&A を行う場合は `spark` を選択し、速度を最優先する場合は `bolt` を選択します。プロンプトにより深い推論が必要で、
モデルの推論中に半秒のつなぎを許容できる場合は `storm-base-with-ack` にアップグレードします。
[プロダクトティア](/api-reference/agents#product-tiers-at-a-glance)を参照してください。
## 2. 電話番号を取得する
発信先として使用する番号だけが必要な場合は、ThunderPhone のプールから
ThunderPhone 番号を取得します。
```bash
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
をポーリングして状態遷移を確認してください。
ThunderPhone 番号は受信専用で開始します。組織管理者は、電話番号ページから
発信通話をリクエストできます。ThunderPhone は各リクエストを手動で審査します。
承認されると、番号からの発信およびキャンペーンの実行が可能になります。
顧客の VoIP 番号は変更されません。
## 3. エージェントを割り当てる
ステップ 1 のエージェントを、その番号の受信方向に関連付けます。
```bash
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`](/api-reference/calls#list-calls) に
`status="in_progress"` として表示されます。通話が終了すると、レコードは
`end_reason`、`duration_seconds`、`billable_minutes`、および（最終的に）
録音 URL と AI 評価で更新されます。
着信通話は、組織の
[同時通話数の上限](/api-reference/introduction#call-limits)にカウントされます（デフォルトでは進行中の通話は20件で、発信通話、Web通話、テスト通話と共有されます）。上限に達している状態で着信した通話は、エージェントが応答する前に拒否されて切断され、課金されず、終了理由が `concurrent_call_limit_reached` の失敗した通話として記録されます。より高い上限が必要な場合は、support@thunderphone.com にメールでお問い合わせください。
## 5. 結果を確認する
最近の通話一覧を取得します。
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
文字起こしを取得します。
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
録音 URL（短時間有効な署名付き URL）を取得します。
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
[`telephony.complete` webhook](/ja/webhooks/events)を購読している場合は、同じデータが POST としてサーバーに送信されます。詳細は[call.complete](/ja/webhooks/call-complete)を参照してください。
エージェントに抽出フィールドが設定されている場合、完了した通話のペイロードには構造化された抽出データも含まれます。
---
## 次のステップ
電話番号または webhook のカスタムロジックに基づいて、発信者ごとに異なるエージェントを選択します。
会話中にエージェントから API を呼び出せるようにします。
発信者を直接転送するか、接続前に転送先をスクリーニングします。
完了した各通話を CRM / 分析パイプラインにストリーミングします。
すべての通話を自動で評価し、フラグが付いた通話をレビューに回します。