أحضر أرقامك الخاصة (VoIP، API)

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

تحتوي لوحة التحكم على نسخة إرشادية من هذا التدفق بالكامل ضمن الاتصالات → VoIP (/dashboard/voip-connections): إعداد إرشادي لـ Telnyx يشرح إنشاء الحساب ومفاتيح API، ومسارًا لربط حساب قائم، ونموذج SIP يدوي مع مولّد دليل إعداد بالذكاء الاصطناعي.

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

مزود الخدمة	معرّف `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

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

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

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

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

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

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

أحضر أرقامك الخاصة (VoIP، API)

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

1. اختبار بيانات الاعتماد

2. إنشاء الاتصال

3. سرد الأرقام واستيرادها

4. تحقّق من كل رقم مستورد

5. عيّن الوكلاء واستقبل مكالمة

تدوير بيانات الاعتماد

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

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

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

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

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

​1. اختبار بيانات الاعتماد

​2. إنشاء الاتصال

​3. سرد الأرقام واستيرادها

​4. تحقّق من كل رقم مستورد

​5. عيّن الوكلاء واستقبل مكالمة

​تدوير بيانات الاعتماد

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

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

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

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

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

1. اختبار بيانات الاعتماد

2. إنشاء الاتصال

3. سرد الأرقام واستيرادها

4. تحقّق من كل رقم مستورد

5. عيّن الوكلاء واستقبل مكالمة

تدوير بيانات الاعتماد

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