Developer cookbook

अपने नंबर इस्तेमाल करें (VoIP, API)

Twilio या Telnyx — या किसी भी SIP ट्रंक — को कनेक्ट करें, आपके पास पहले से मौजूद फोन नंबर इंपोर्ट करें, और ThunderPhone एजेंट्स को उन पर कॉल का जवाब देने और कॉल करने दें।

डेमो नंबर प्रोटोटाइपिंग के लिए ठीक हैं, लेकिन प्रोडक्शन ट्रैफ़िक में आपके अपने VoIP प्रोवाइडर के माध्यम से आपके स्वामित्व वाले नंबर इस्तेमाल होने चाहिए। यह गाइड आपको तीन-स्टेप फ़्लो से ले जाती है: क्रेडेंशियल टेस्ट करें → कनेक्शन बनाएं → नंबर इंपोर्ट करें → वेरिफ़ाई करें।

समर्थित प्रोवाइडर#

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 allowlist, आउटबाउंड ऑथराइज़ेशन) ठीक करें और फिर से प्रयास करें।

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. एजेंट असाइन करें और कॉल लें#

नंबर वेरिफ़ाई हो जाने के बाद, इनबाउंड / आउटबाउंड एजेंट उसी तरह असाइन करें जैसे डेमो नंबर के लिए करते हैं। देखें इनबाउंड कॉल हैंडल करें और आउटबाउंड कॉल करें।

क्रेडेंशियल रोटेट करना#

जब कोई प्रोवाइडर key रोटेट हो, तो टेस्ट-फिर-अपडेट फ्लो दोबारा चलाएँ:

# 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"
  }'

कनेक्शन यथावत रहता है — नंबर दोबारा इंपोर्ट करने की ज़रूरत नहीं है।

अगले चरण#