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

# 独自の電話番号を利用（VoIP、API）

> Twilio、Telnyx、または任意のSIPトランクに接続し、既存のアカウントから電話番号をインポートします。

デモ番号はプロトタイピングには適していますが、本番トラフィックには独自のVoIPプロバイダーを通じて所有する番号を使用してください。このガイドでは、3ステップのフローを説明します: **認証情報をテスト → 接続を作成 → 番号をインポート → 検証**。

<Note>
  ダッシュボードの **接続 → VoIP** (`/dashboard/voip-connections`) には、このフロー全体のガイド付きバージョンがあります。アカウント作成とAPIキーを案内するTelnyxガイド付きセットアップ、既存アカウントの接続パス、AIセットアップガイド生成機能を備えた手動SIPフォームが含まれます。
</Note>

## 対応プロバイダー

| プロバイダー     | `provider` ID | 備考                                                      |
| ---------- | ------------- | ------------------------------------------------------- |
| Twilio     | `twilio`      | APIキー + シークレット                                          |
| Telnyx     | `telnyx`      | APIキー。ガイド付きオンボーディングを利用可能（`setup_method: guided_telnyx`） |
| SignalWire | `signalwire`  | **近日対応** — 現在は手動SIPで接続                                  |
| Vonage     | `vonage`      | **近日対応** — 現在は手動SIPで接続                                  |
| 手動SIP      | `manual`      | 任意のSIPトランク — 独自の設定を使用                                   |

## 1. 認証情報をテスト

永続的なVoIP接続を作成する前に、プロバイダーの認証情報をテストして動作を確認します。これにより、作成ステップに渡す`verification_evidence_id`が返され、テストのために認証情報が二重課金されることを防ぎます。

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'
```

```json Response theme={null}
{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}
```

いずれかのチェックに失敗した場合、レスポンスの`status`は`fail`となり、`checks`に失敗したステップが表示されます。プロバイダー側の設定（トランク割り当て、IP許可リスト、発信認可）を修正して、再試行してください。

## 2. 接続を作成

取得した`verification_evidence_id`を渡します。

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'
```

レスポンスは、`status="connected"`の[VoIP接続オブジェクト](/api-reference/voip-connections#connection-object)です。認証情報はサーバー側に保存され、後続のGETで平文として返されることはありません。ローテーションするには、新しい`test`を実行し、新しいエビデンスを使用してPATCHします。

## 3. 番号を一覧表示してインポート

認証情報で参照でき、まだThunderPhone組織に存在しない番号を確認します。

```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

次に、必要な番号をインポートします。

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'
```

各インポートは、組織内で`source="voip"`および`status="provisioning"`を持つ[電話番号リソース](/api-reference/phone-numbers)になります。

## 4. インポートした各番号を検証する

インポートすると番号は*利用可能*として登録されますが、実際にその番号で通話をルーティングするには、往復の検証（着信ダイヤルイン確認 +
発信認可プローブ）が必要です。

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

成功すると、`voip_verification_status` が `verified` に切り替わり、番号は
`status="active"` になります。失敗した場合、レスポンスには失敗内容が示されます。修正後（多くの場合はプロバイダーダッシュボードでのトランク割り当て漏れ）、再度呼び出してください。

## 5. エージェントを割り当てて通話する

番号を検証したら、デモ番号と同じ方法で着信 / 発信エージェントを
割り当てます。[着信通話を処理する](/ja/guides/handle-inbound-calls)および
[発信通話を行う](/ja/guides/place-outbound-calls)を参照してください。

## 認証情報のローテーション

プロバイダーキーがローテーションされた場合は、テストしてから更新するフローを再実行します。

```bash theme={null}
# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...

# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'
```

接続は維持されるため、番号を再インポートする必要はありません。

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="VoIP接続リファレンス" icon="phone-volume" href="/api-reference/voip-connections">
    接続、エビデンス、インポートのレスポンスに含まれるすべてのフィールド。
  </Card>

  <Card title="電話番号リファレンス" icon="phone" href="/api-reference/phone-numbers">
    エージェントの割り当て、組織間の転送、番号の解放。
  </Card>

  <Card title="発信通話を行う" icon="arrow-up-right" href="/ja/guides/place-outbound-calls">
    番号を所有したら、発信を開始できます。
  </Card>
</CardGroup>