---
title: "発信通話を行う（API）"
description: "独自のコードからAI駆動の発信通話をトリガーします。アンケート、フォローアップ、確認フローに対応。"
---

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

- 予約確認
- アンケートの折り返し
- 不在着信後の「再試行」フォローアップ
- 配車・派遣形式の通知

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

## 前提条件

<Steps>
  <Step title="発信対応の番号を選択">
    [VoIP接続](/api-reference/voip-connections)を通じて所有している番号を使用するか、Phone Numbers
    ページから ThunderPhone の番号を発信に使用する許可を申請します。ThunderPhone の番号は最初は着信専用です。ThunderPhone は各申請を手動で審査します。承認されると、それらの番号では承認済みの1日の上限まで通話を発信でき（上限は UTC 00:00 にリセット）、キャンペーンを実行できます。また、より高い上限を申請することもできます。顧客の VoIP 番号には1日の上限がないため、発信にはこちらを推奨します。
    [独自の番号を使用する](/ja/guides/bring-your-own-numbers)を参照してください。
  </Step>
  <Step title="エージェントを作成">
    発信向けのプロンプトでは、通常、エージェントが自己紹介と目的の説明から始めます。たとえば「こんにちは、Acme の者です。明日午後3時の予約確認のためにお電話しています…」のようになります。`outbound_speak_order` を `agent_first`（デフォルト）に設定します。
  </Step>
  <Step title="残高をプラスに維持">
    残高が `$0.00` 以下の場合、発信は `402 Payment Required` を返します。ダッシュボードの **組織 → 請求設定** でチャージするか、自動リロードを有効にします。`sk_live_`
    キーでは[`GET /v1/billing`](/api-reference/billing#get-billing-account)で残高を確認できますが、チャージや自動リロードの変更はできません。
  </Step>
</Steps>

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

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

```bash
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":   "+14155552671",
    "agent_id":    12
  }'
```

レスポンス:

```json
{ "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
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":   "+14155552671",
    "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が含まれます。

エージェントが通話後に構造化データを抽出するよう設定されている場合、そのデータは確定処理の完了後に別途配信されます。

### 保存済みエージェントに通話ごとの変数を渡す

保存済みエージェントでは、プロンプトテキスト内で `{{name}}` や `{{name|there}}` のようなプレースホルダーを使用できます。`agent_id` を指定して発信する場合は、その通話の値を含む `variables` を渡します。

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}
```

プレースホルダー名をキーとする文字列値を使用してください。これらの変数は保存済みエージェントに適用されます。このガイドのインライン `config` の例では使用しません。

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

| エラー | 対処法 |
|-------|-----|
| `402 Payment Required` | 残高をチャージするか、自動リロードを有効にします |
| `400`（`code: destination_not_allowed`） | ThunderPhone はその番号に発信しません。無効な番号、緊急通報番号、プレミアムレート番号、ショートコード、制裁対象国が該当します。ThunderPhone 番号からは、通常の米国およびカナダの番号にのみ発信できます（プレミアムレート番号を除く）。該当理由は `reason` に示されます。[ブロックされた発信先](/api-reference/outbound-calls#blocked-destinations)を参照してください |
| ThunderPhone 番号で `retryable: false` の `409` | `code` に従ってください。Phone Numbers ページでアウトバウンド通話をリクエストする、保留中の審査を待つ、または別の利用可能な番号を使用します |
| `429`（`code: platform_outbound_daily_limit_reached`） | 組織が ThunderPhone 番号からの当日のアウトバウンド通話上限を使用しました。`resets_at`（00:00 UTC）まで待つ、Phone Numbers ページで上限引き上げをリクエストする、または独自の VoIP 接続の番号から発信します |
| `429`（`code: concurrent_call_limit_reached`） | 組織で進行中の通話数が[同時通話上限](/api-reference/introduction#call-limits)に達しています（デフォルトは 20。着信、発信、ウェブ、テスト通話を含む）。`Retry-After` ヘッダーで指定された秒数の経過後、または通話終了後に再試行してください。上限を引き上げるには support@thunderphone.com にメールしてください |
| `429`（`code: same_number_too_soon`） | 同じ `to_number` に 10 秒未満前に発信しました。`Retry-After` ヘッダーで指定された秒数の経過後に再試行してください |
| 顧客の VoIP 番号で `retryable: false` の `409` | `code` で示された状態を修正してください。検証失敗の場合は、[`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number)を実行します |
| `409` 冪等性の競合 | 元の正規化済みリクエストに対してのみキーを再利用するか、新しいキーを送信してください |
| `404 from_number is not registered to this organization` | `from_number` が組織内の有効な電話番号と一致することを確認してください。すでにプロビジョニング中、失敗、解放中、または解放済みの番号でも、このレスポンスが返されます |
| `detail` フィールドのみを含む `500` | アウトバウンドトランクが設定されていません。サポートにお問い合わせください。これは修正可能な番号状態の問題ではありません |
| `502 Bad Gateway` | 一時的な SIP / LiveKit 障害です。安全に再試行できます |

安定版の適格性コードの完全な一覧と、両方の `409` レスポンス形式については、[発信通話リファレンス](/api-reference/outbound-calls#error-responses)を参照してください。
リクエストが受け付けられた後、通話が発信される前に有効な番号が不適格になった場合、最終チェックで再試行不可の `409` ペイロードが返されます。

## 保留時間を制御する

相手の応答が遅いことで長時間化する発信通話
（IVRツリー、キュー）は、`max_hold_seconds` で上限を設定できます。

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "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>