---
title: "独自の電話番号を使用（VoIP、API）"
description: "Twilio、Telnyx、SignalWire、Vonage、Plivo、その他のSIPトランクをSIP経由で接続し、所有済みの電話番号をインポートして、ThunderPhoneエージェントがその番号で着信応答や発信を行えるようにします。"
---

承認済みのThunderPhone番号では、発信通話の実行とキャンペーンの運用が可能です。独自のVoIPプロバイダー経由で所有番号を使用する場合は、このガイドに従って接続フローを進めます。**認証情報をテスト → 接続を作成 → 番号をインポート → 検証**。

<Note>
  ダッシュボードの **接続 → VoIP**（`/dashboard/voip-connections`）には、このフロー全体のガイド付きバージョンがあります。まず既存の接続を行う手順（Twilio と Telnyx は API キー、それ以外の SignalWire、Vonage、Plivo、およびその他のトランクは、プロバイダー固有の手順と AI セットアップガイド生成機能を備えた手動 SIP フォームを使用）を案内し、次に新しい Telnyx アカウントを開設するガイド付きセットアップを案内します。
</Note>

## 対応プロバイダー

| プロバイダー | `provider` ID | 注記 |
|----------|---------------|-------|
| Twilio | `twilio` | アカウント SID + Auth Token。Twilio アカウントまたはサブアカウントごとに1接続（[Twilio サブアカウント](#twilio-subaccounts)を参照） |
| Telnyx | `telnyx` | API キー。ガイド付きオンボーディングを利用可能（`setup_method: guided_telnyx`） |
| SignalWire | `signalwire` | ネイティブのプロバイダー接続はありません。SignalWire SIP プリセットで `manual` として接続します |
| Vonage | `vonage` | ネイティブのプロバイダー接続はありません。Vonage SIP プリセットで `manual` として接続します |
| 手動 SIP | `manual` | SignalWire、Vonage、Plivo を含む任意の SIP トランク。ダッシュボードでこれらのプロバイダータイルのいずれかから開始した場合も、接続は `manual` となり、選択内容は `sip_config.preset` に保存されます（`signalwire`、`vonage`、または `plivo`） |

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

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

```bash
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
{
  "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
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"` の[VoipConnection オブジェクト](/api-reference/voip-connections#connection-object)です。認証情報やその他の機密性の高い接続値はサーバー側に保存され、後続の GET でプレーンテキストとして返されることはありません。ローテーションするには、新たに `test` を実行し、新しいエビデンスで PATCH してください。

### Twilio サブアカウント

Twilio 接続は、保持している Account SID と Auth Token に対応する単一の Twilio アカウントに紐付けられます。Twilio は電話番号と SIP トランクを各サブアカウント内に保持するため、親アカウントで作成した接続からは親アカウント自身の番号しか確認できず、既存の接続を後から別のサブアカウントに切り替えることはできません。

サブアカウントに保持されている番号にアクセスするには、サブアカウントごとに接続を作成します。ダッシュボードではこれを自動で行えます。アクティブなサブアカウントを持つ親
アカウントを接続すると、設定ダイアログにサブアカウントの一覧が表示されます。必要なものを選択すると、ThunderPhone が各サブアカウントに接続（および
SIP トランク）を作成します。同じフローは API でも利用できます。

```bash
# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'
```

```json Response
{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}
```

```bash
# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'
```

レスポンスにはサブアカウントごとに1行が含まれ、`status` は
`created`、`skipped`（すでに接続済み）、`failed` のいずれかとなり、対応可能な
`error` も含まれます。行は互いに独立しているため、あるサブアカウントで失敗しても
他のサブアカウントはブロックされません。また、`discovery_id` は30分間有効なため、失敗した行は
そのまま再試行できます。サブアカウントのトークンは検出時にTwilioから読み取られ、新しい接続に保存されます。
APIから返されることはありません。各新規接続では、手動で作成した接続とまったく同じように
番号がインポートおよび検証されます。各新規接続のSIPトランクでも通話転送を有効にするには、
`"enable_transfers": true` を追加します。この処理に失敗した場合は、その接続の
`test_result.transfer_enable_error` に報告され、行自体は失敗になりません。

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

認証情報から表示でき、まだ ThunderPhone 組織に含まれていない番号を確認します。

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

続いて、必要な番号をインポートします。

```bash
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"]}'
```

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

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

インポートすると、その番号は*利用可能*として登録されます。実際にその番号経由で通話をルーティングするには、検証が必要です。プロバイダー接続（Twilio、
Telnyx）の場合は、プロバイダーの認証情報とSIP到達可能性を再確認します。
**手動SIP**接続の場合は、まずループバック自己通話を試行します。
ThunderPhoneは、その番号*から*、SIP
トランク*を経由して*、*同じ番号に戻る*短いテスト通話を発信します。これで着信経路を検証できない場合は、その番号*から*、SIPトランク*を経由して*、
ThunderPhone番号*へ*短いテスト通話を発信します。これらのテストでは、トランクのユーザー名、
パスワード、トランスポート、発信ルーティング、着信配信を確認します。これらの通話は通常の通話と同様に通信事業者から課金されます。

```bash
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"` になります。自身の Telnyx アカウントにある番号は、テスト通話に失敗した場合やアウトバウンドがまだ設定されていない場合でも着信を受け続けます。この場合、`voip_verification_status` が
`unverified` に設定された `status="active"` となり、レスポンスで理由が示されます。失敗した場合、レスポンスには
何が失敗したかが明記されます。手動トランクの場合は通信事業者からの SIP 応答です。たとえば *"ThunderPhone の認証情報が拒否されました（SIP 401）"* や *"通話をルーティングできませんでした（SIP 404）"* です。問題を修正し（認証情報、許可された送信元 IP、プロバイダーダッシュボードで不足しているトランク割り当て）、再度呼び出してください。

許可リストに登録された手動SIP接続では、Allowed Source IPsによって実際の着信通話がブロックされる場合、着信通話テストも失敗します。

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

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

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

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

```bash
# 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>