자체 번호 사용(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"
}'연결은 그대로 유지되므로 번호를 다시 가져올 필요가 없습니다.