Open in
独自の電話番号を使用（VoIP、API）
Twilio、Telnyx、SignalWire、Vonage、Plivo、その他のSIPトランクをSIP経由で接続し、所有済みの電話番号をインポートして、ThunderPhoneエージェントがその番号で着信応答や発信を行えるようにします。
承認済みのThunderPhone番号では、発信通話の実行とキャンペーンの運用が可能です。独自のVoIPプロバイダー経由で所有番号を使用する場合は、このガイドに従って接続フローを進めます。認証情報をテスト → 接続を作成 → 番号をインポート → 検証。
対応プロバイダー
| プロバイダー | provider ID | 注記 |
|---|---|---|
| Twilio | twilio | アカウント SID + Auth Token。Twilio アカウントまたはサブアカウントごとに1接続（Twilio サブアカウントを参照） |
| 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が返されるため、
テスト時に認証情報へ二重課金されません。
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" }
}'{
"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 を渡します。
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 オブジェクトです。認証情報やその他の機密性の高い接続値はサーバー側に保存され、後続の GET でプレーンテキストとして返されることはありません。ローテーションするには、新たに test を実行し、新しいエビデンスで PATCH してください。
Twilio サブアカウント
Twilio 接続は、保持している Account SID と Auth Token に対応する単一の Twilio アカウントに紐付けられます。Twilio は電話番号と SIP トランクを各サブアカウント内に保持するため、親アカウントで作成した接続からは親アカウント自身の番号しか確認できず、既存の接続を後から別のサブアカウントに切り替えることはできません。
サブアカウントに保持されている番号にアクセスするには、サブアカウントごとに接続を作成します。ダッシュボードではこれを自動で行えます。アクティブなサブアカウントを持つ親 アカウントを接続すると、設定ダイアログにサブアカウントの一覧が表示されます。必要なものを選択すると、ThunderPhone が各サブアカウントに接続（および SIP トランク）を作成します。同じフローは API でも利用できます。
# 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": "..."}}'{
"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 }
]
}# 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 組織に含まれていない番号を確認します。
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"続いて、必要な番号をインポートします。
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" を持つ電話番号リソースになります。
4. インポートした各番号を検証する
インポートすると、その番号は利用可能として登録されます。実際にその番号経由で通話をルーティングするには、検証が必要です。プロバイダー接続（Twilio、 Telnyx）の場合は、プロバイダーの認証情報とSIP到達可能性を再確認します。 手動SIP接続の場合は、まずループバック自己通話を試行します。 ThunderPhoneは、その番号から、SIP トランクを経由して、同じ番号に戻る短いテスト通話を発信します。これで着信経路を検証できない場合は、その番号から、SIPトランクを経由して、 ThunderPhone番号へ短いテスト通話を発信します。これらのテストでは、トランクのユーザー名、 パスワード、トランスポート、発信ルーティング、着信配信を確認します。これらの通話は通常の通話と同様に通信事業者から課金されます。
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 番号と同じ方法で着信/発信エージェントを割り当てます。着信通話を処理するおよび発信通話を行うを参照してください。
認証情報のローテーション
プロバイダーキーをローテーションした場合は、テストしてから更新するフローを再実行します。
# 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"
}'接続は維持されます。番号を再インポートする必要はありません。