> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> اربط Twilio أو Telnyx — أو أي خط SIP رئيسي — واستورد أرقام الهاتف من حسابك الحالي.

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

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

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

| مزود الخدمة | معرّف `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` تمرره إلى خطوة الإنشاء كي لا
تُحتسب رسوم اختبار بيانات الاعتماد مرتين.

```bash theme={null}
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" }
  }'
```

```json Response theme={null}
{
  "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` الذي حصلت عليه للتو:

```bash theme={null}
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](/api-reference/voip-connections#connection-object)
بحالة `status="connected"`. تُخزَّن بيانات الاعتماد على الخادم ولا
تُعاد بنص واضح في طلبات GET اللاحقة — للتدوير، نفّذ `test`
جديدًا واستخدم PATCH مع دليل التحقق الجديد.

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

افحص الأرقام الظاهرة لبيانات اعتمادك والتي لا توجد بالفعل
في مؤسسة ThunderPhone:

```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

ثم استورد الأرقام التي تريدها:

```bash theme={null}
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"]}'
```

يتحول كل استيراد إلى [مورد رقم هاتف](/api-reference/phone-numbers)
في مؤسستك مع `source="voip"` و`status="provisioning"`.

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

يؤدي الاستيراد إلى تسجيل الرقم بوصفه *متاحًا*؛ أما توجيه المكالمات فعليًا
عبره فيتطلب تحققًا ذهابًا وإيابًا (فحص اتصال وارد +
اختبار تفويض صادر).

```bash theme={null}
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. عيّن الوكلاء واستقبل مكالمة

بعد التحقق من الرقم، عيّن وكلاء المكالمات الواردة / الصادرة بالطريقة
نفسها المستخدمة للرقم التجريبي. راجع
[معالجة المكالمات الواردة](/ar/guides/handle-inbound-calls) و
[إجراء المكالمات الصادرة](/ar/guides/place-outbound-calls).

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

عند تدوير مفتاح المزوّد، أعد تنفيذ مسار الاختبار ثم التحديث:

```bash theme={null}
# 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"
  }'
```

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

***

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

<CardGroup cols={2}>
  <Card title="مرجع اتصالات VoIP" icon="phone-volume" href="/api-reference/voip-connections">
    كل حقل في استجابات الاتصال والإثبات والاستيراد.
  </Card>

  <Card title="مرجع أرقام الهاتف" icon="phone" href="/api-reference/phone-numbers">
    عيّن الوكلاء، وانقل بين المؤسسات، وحرّر الأرقام.
  </Card>

  <Card title="إجراء المكالمات الصادرة" icon="arrow-up-right" href="/ar/guides/place-outbound-calls">
    الآن بعد أن أصبح الرقم ملكك، ابدأ بإجراء المكالمات الصادرة.
  </Card>
</CardGroup>