استخدم أرقامك الخاصة (VoIP، API)

اربط Twilio أو Telnyx أو SignalWire أو Vonage أو Plivo وأي خط SIP آخر عبر 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 واحد يحمل معرّف الحساب ورمز المصادقة الخاصين به. يحتفظ 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..."]}'

يتضمن الرد صفًا واحدًا لكل حساب فرعي، مع status بالقيمة created أو skipped (متصل بالفعل) أو failed، بالإضافة إلى error يمكنك اتخاذ إجراء بشأنه. الصفوف مستقلة، لذا فإن الفشل في حساب فرعي واحد لا يمنع الحسابات الأخرى مطلقًا، ويظل discovery_id صالحًا لمدة 30 دقيقة، لذا يمكن ببساطة إعادة محاولة الصف الذي فشل. تُقرأ رموز الحسابات الفرعية من Twilio وقت الاكتشاف وتُخزَّن في الاتصال الجديد؛ ولا تُعاد أبدًا عبر واجهة API. بعد ذلك، يستورد كل اتصال جديد الأرقام ويتحقق منها بالطريقة نفسها تمامًا كما لو أنشأت اتصالًا يدويًا. أضف "enable_transfers": true لتفعيل تحويلات المكالمات أيضًا على جذع SIP لكل اتصال جديد؛ ويُبلَّغ عن الفشل هناك في 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 الخاص بك استقبال المكالمات الواردة عند فشل مكالمة الاختبار أو إذا لم يتم إعداد الاتصال الصادر بعد: إذ يصبح status="active" مع ضبط voip_verification_status على unverified، ويوضح الرد السبب. عند الفشل، يحدد الرد ما الذي أخفق — وبالنسبة إلى خط اتصال يدوي، يكون ذلك رد SIP الخاص بشركة الاتصالات، مثل "تم رفض بيانات اعتماد ThunderPhone (SIP 401)" أو "تعذر توجيه مكالمة (SIP 404)" — صحح المشكلة (بيانات الاعتماد، عناوين IP المصدر المسموح بها، أو تعيين خط اتصال مفقود في لوحة تحكم المزوّد) ثم اتصل مرة أخرى.

بالنسبة إلى اتصال SIP يدوي مُدرج في قائمة السماح، يفشل اختبار المكالمات الواردة أيضًا إذا كانت عناوين IP المصدر المسموح بها تلك ستحظر مكالمة واردة فعلية.

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

يبقى الاتصال قائمًا — لا حاجة إلى إعادة استيراد الأرقام.

الخطوات التالية#