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

اربط Twilio أو Telnyx — أو أي خط SIP رئيسي — واستورد أرقام الهاتف التي تملكها بالفعل، ودع وكلاء ThunderPhone يجيبون عن المكالمات ويُجرونها باستخدامها.

أرقام العرض مناسبة لإنشاء النماذج الأولية، لكن حركة الإنتاج يجب أن تستخدم أرقامًا تملكها من خلال مزود VoIP الخاص بك. يرشدك هذا الدليل خلال التدفق المؤلف من ثلاث خطوات: اختبار بيانات الاعتماد → إنشاء الاتصال → استيراد الأرقام → التحقق.

مقدمو الخدمة المدعومون

مقدم الخدمة	معرّف `provider`	ملاحظات
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" }
  }'

Response

{
  "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 مع دليل التحقق الجديد.

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". عند الفشل، يوضّح الرد ما الذي أخفق — أصلحه (غالبًا ما يكون تعيين trunk مفقودًا في لوحة تحكم المزوّد) ثم استدعِه مرة أخرى.

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

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

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

مرجع اتصالات VoIP

كل حقل في استجابات الاتصال والأدلة والاستيراد.

مرجع أرقام الهاتف

عيّن الوكلاء، وانقل بين المؤسسات، وحرّر الأرقام.

إجراء مكالمات صادرة

الآن بعد أن أصبحت تملك الرقم، ابدأ بإجراء مكالمات صادرة.