既存の電話番号を利用（VoIP、API）
Twilio、Telnyx、または任意のSIPトランクに接続し、所有済みの電話番号をインポートして、ThunderPhoneエージェントがその番号で着信に応答し、発信できるようにします。
プロトタイピングにはデモ番号で十分ですが、本番トラフィックには独自のVoIPプロバイダーを通じて所有する番号を使用してください。このガイドでは、認証情報をテスト → 接続を作成 → 番号をインポート → 検証の4ステップのフローを説明します。
対応プロバイダー
| プロバイダー | 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が返され、テストのために認証情報へ二重請求されることを防ぎます。
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します。
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"]}'インポートした各番号は、組織内でsource="voip"およびstatus="provisioning"を持つ電話番号リソースになります。
4. インポートした各番号を検証する
インポートにより番号は利用可能として登録されますが、実際に通話を ルーティングするには往復検証（着信ダイヤルインチェック + 発信認証プローブ）が必要です。
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. エージェントを割り当てて通話する
番号の検証後は、デモ番号と同じ方法で着信 / 発信エージェントを 割り当てます。着信通話を処理するおよび 発信通話を開始するを参照してください。
認証情報のローテーション
プロバイダーキーが更新された場合は、テストしてから更新するフローを再実行します。
# 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"
}'接続はそのまま維持されるため、番号を再インポートする必要はありません。