اپنے نمبرز استعمال کریں (VoIP، API)

Twilio یا Telnyx — یا کسی بھی SIP ٹرنک — کو منسلک کریں، اپنے موجودہ فون نمبرز امپورٹ کریں، اور ThunderPhone ایجنٹس کو ان پر کالز وصول کرنے اور کرنے دیں۔

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 الاؤ لسٹ، آؤٹ باؤنڈ اجازت) اور دوبارہ کوشش کریں۔

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

جواب میں ایک VoipConnection آبجیکٹ ہوتا ہے جس کا status="connected" ہوتا ہے۔ اسناد سرور پر محفوظ کی جاتی ہیں اور بعد کی GET درخواستوں میں کبھی سادہ متن میں واپس نہیں کی جاتیں — تبدیل کرنے کے لیے نیا test چلائیں اور نئے ثبوت کے ساتھ PATCH کریں۔

Twilio ذیلی اکاؤنٹس#

Twilio کنکشن اسی ایک Twilio اکاؤنٹ سے منسلک ہوتا ہے جس کا Account SID اور Auth Token اس میں موجود ہو۔ Twilio فون نمبرز اور SIP ٹرنکس کو ہر ذیلی اکاؤنٹ کے اندر رکھتا ہے، اس لیے پیرنٹ اکاؤنٹ کے ذریعے بنایا گیا کنکشن صرف پیرنٹ کے اپنے نمبرز دیکھتا ہے، اور موجودہ کنکشن کو بعد میں کسی دوسرے ذیلی اکاؤنٹ پر تبدیل نہیں کیا جا سکتا (اپ ڈیٹ مسترد ہو جاتی ہے کیونکہ کنکشن کا 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..."]}'

جواب میں ہر ذیلی اکاؤنٹ کے لیے ایک قطار ہوتی ہے، جس کا status created، skipped (پہلے سے کنیکٹ شدہ) یا failed ہوتا ہے، اور اس کے ساتھ ایک error ہوتی ہے جس پر آپ کارروائی کر سکتے ہیں۔ قطاریں خود مختار ہوتی ہیں، اس لیے ایک ذیلی اکاؤنٹ کی ناکامی دوسرے اکاؤنٹس کو کبھی نہیں روکتی، اور discovery_id 30 منٹ تک درست رہتی ہے، لہٰذا ناکام قطار کو آسانی سے دوبارہ آزمایا جا سکتا ہے۔ ذیلی اکاؤنٹ ٹوکنز دریافت کے وقت Twilio سے پڑھے جاتے ہیں اور نئے کنکشن میں محفوظ کیے جاتے ہیں؛ انہیں API کبھی واپس نہیں کرتی۔ پھر ہر نیا کنکشن بالکل اسی طرح نمبرز درآمد اور تصدیق کرتا ہے جیسے ہاتھ سے بنایا گیا کنکشن کرتا ہے۔

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. ہر درآمد کردہ نمبر کی تصدیق کریں#

درآمد کرنے سے نمبر دستیاب کے طور پر رجسٹر ہو جاتا ہے؛ اس کے ذریعے کالز کو حقیقتاً روٹ کرنے کے لیے تصدیق درکار ہوتی ہے۔ فراہم کنندہ کنکشنز (Twilio، Telnyx) کے لیے یہ فراہم کنندہ کی اسناد اور SIP رسائی پذیری کو دوبارہ چیک کرتا ہے۔ دستی 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" میں داخل ہو جاتا ہے۔ ناکامی پر، جواب واضح کرتا ہے کہ کیا ناکام ہوا — دستی ٹرنک کے لیے یہ کیریئر کا SIP جواب ہوتا ہے، مثلاً "ThunderPhone کی اسناد مسترد کر دیں (SIP 401)" یا "کال روٹ نہیں ہو سکی (SIP 404)" — اسے درست کریں (اسناد، منظور شدہ سورس 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"
  }'

کنکشن برقرار رہتا ہے — نمبرز کو دوبارہ درآمد کرنے کی ضرورت نہیں۔

اگلے مراحل#