> ## 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）

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

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

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

<Note>
  連絡先リスト全体に発信する場合は、ダッシュボードの
  [**キャンペーン**](/ja/guides/outbound-campaigns)機能
  (`/dashboard/campaigns`)を使用してください。連絡先のCSVを受け取り、
  タイムゾーン対応の発信時間帯、同時実行数、再試行ポリシーを処理します。
  このガイドでは、単一のプログラムによる発信を説明します。
</Note>

## 前提条件

<Steps>
  <Step title="VoIP番号を用意する">
    発信通話には、[VoIP接続](/api-reference/voip-connections)を通じて
    `from_number`を所有している必要があります。デモ番号は着信専用です。
    [独自の番号を持ち込む](/ja/guides/bring-your-own-numbers)を参照してください。
  </Step>

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

  <Step title="残高を正に保つ">
    残高が`$0.00`以下の場合、発信通話は`402 Payment Required`を返します。
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)でチャージするか、
    [自動リロード](/api-reference/billing#update-auto-reload)を有効にしてください。
  </Step>
</Steps>

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

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

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

レスポンス:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"`は、リクエストが受理されたことを意味するだけであり、通話は
  **まだ接続されていません**。ライブステータスを確認するには、
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  をポーリングしてください（`in_progress` → `completed` / `failed`）。
</Warning>

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

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

```bash theme={null}
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](/ja/webhooks/events)を購読してください。
これは通話の終了を最も迅速に把握する方法です。受信webhookを受け取れない場合は、
数秒ごとに`GET /v1/calls/{call_id}`をポーリングしてください。通話終了後、レコードには
`end_reason`、`duration_seconds`、録音URLが含まれます。

## 対応すべき障害モード

| エラー                                                      | 対処方法                                                                                                        |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | 残高をチャージするか、自動リロードを有効にする                                                                                     |
| `403` 発信ブロック（デモ番号）                                       | 代わりにVoIP番号を用意する                                                                                             |
| `403` 発信ブロック（未検証のVoIP）                                   | [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number)を実行する |
| `404 from_number is not registered to this organization` | `from_number`が所有する電話番号と一致していることを確認する                                                                        |
| `502 Bad Gateway`                                        | 一時的なSIP / LiveKit障害。安全に再試行可能                                                                                |

## 保留時間の制御

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

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

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

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="アウトバウンド通話リファレンス" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    すべてのリクエストフィールドとエラーコード。
  </Card>

  <Card title="call.complete を受信" icon="bolt" href="/ja/webhooks/call-complete">
    完了したアウトバウンド通話をシステムにストリーミングします。
  </Card>

  <Card title="請求" icon="credit-card" href="/api-reference/billing">
    残高不足でアウトバウンド通話が失敗しないよう自動チャージします。
  </Card>

  <Card title="アウトバウンドエージェントをテスト" icon="flask" href="/ja/guides/test-agents">
    本番環境の前にアウトバウンドエージェントをドライランします。
  </Card>
</CardGroup>