> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<Note>
  初めてのエージェントを手動で構築しますか。ダッシュボードでは、エージェントの構築、番号の追加、シミュレーション、確認というこのフローを、ガイド付きウィザードで案内します。まずは
  [ダッシュボードのクイックスタート](/ja/quickstart-dashboard)
  から始めてください。
</Note>

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

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

API呼び出しは合計4回です。所要時間は5分未満です。

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

エージェントには、通話を処理するプロンプト、音声、製品ティアがまとめられます。すべての設定フィールドについては[エージェント](/api-reference/agents)を参照してください。最小構成は次のとおりです。

```bash theme={null}
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で必要になります。

<Tip>
  最小コストでシンプルなQ\&Aを行う場合は `spark` を選択し、速度を最優先する場合は `bolt` を選択します。プロンプトにより深い推論が必要で、モデルの推論中に発生する0.5秒のフィラーを許容できる場合は、`storm-base-with-ack` にアップグレードしてください。
  [製品ティア](/api-reference/agents#product-tiers-at-a-glance)
  を参照してください。
</Tip>

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

発信先として使う番号だけが必要な場合は、ThunderPhoneのプールからデモ番号をプロビジョニングします。

```bash theme={null}
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"}'
```

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

<Note>
  本番環境ではデモ番号を使わず、
  [VoIP経由で独自の番号を持ち込む](/ja/guides/bring-your-own-numbers)
  を参照してください。デモ番号は着信専用で、利用量に上限があります。
</Note>

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

ステップ1で作成したエージェントを、番号の着信方向に関連付けます。

```bash theme={null}
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` も設定すれば、その番号から発信する準備も整います。

## 4. 通話を受ける

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

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

## 5. 結果を確認する

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

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

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

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

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

```bash theme={null}
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)
を参照してください。

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="通話ごとの動的設定" icon="bolt" href="/ja/guides/dynamic-call-config">
    電話番号またはWebhookのカスタムロジックに基づいて、発信者ごとに異なるエージェントを選択します。
  </Card>

  <Card title="ツール連携を追加" icon="screwdriver-wrench" href="/ja/guides/build-tool-integration">
    会話中にエージェントがAPIを呼び出せるようにします。
  </Card>

  <Card title="call.complete Webhookを受信" icon="bolt" href="/ja/webhooks/call-complete">
    完了した各通話をCRM / 分析パイプラインにストリーミングします。
  </Card>

  <Card title="AI評価と問題レポート" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    すべての通話を自動で評価し、フラグが付いた通話をレビューに回します。
  </Card>
</CardGroup>