> ## 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.

# إجراء مكالمات صادرة (API)

> شغّل مكالمة صادرة مدعومة بالذكاء الاصطناعي من شفرتك البرمجية — لاستطلاعات الرأي أو المتابعة أو مسارات التأكيد.

تتيح لك المكالمات الصادرة تمرير رقم وجهة وإعداد وكيل إلى ThunderPhone ليجري الذكاء الاصطناعي المكالمة نيابةً عنك. حالات الاستخدام المعتادة:

* تأكيدات المواعيد
* معاودة الاتصال للاستبيانات
* متابعات «المحاولة الثانية» بعد مكالمة فائتة
* إشعارات بأسلوب الإرسال

<Note>
  هل تتصل بقائمة كاملة؟ تتيح ميزة
  [**الحملات**](/ar/guides/outbound-campaigns) في لوحة التحكم
  (`/dashboard/campaigns`) تحميل ملف CSV لجهات الاتصال، وتتولى نوافذ
  الاتصال المراعية للمنطقة الزمنية، والتزامن، وسياسة إعادة المحاولة
  نيابةً عنك. يغطي هذا الدليل المكالمات البرمجية الفردية.
</Note>

## المتطلبات الأساسية

<Steps>
  <Step title="أحضر رقم VoIP">
    تتطلب المكالمات الصادرة أن تمتلك `from_number` عبر
    [اتصال VoIP](/api-reference/voip-connections). أرقام العرض التوضيحي
    مخصصة للمكالمات الواردة فقط. راجع
    [أحضر أرقامك الخاصة](/ar/guides/bring-your-own-numbers).
  </Step>

  <Step title="أنشئ وكيلاً">
    يميل الموجّه المخصص للمكالمات الصادرة إلى البدء بتعريف الوكيل بنفسه
    وبغرضه — «مرحباً، معك Acme للاتصال لتأكيد موعدك غداً الساعة
    3 مساءً…». اضبط `outbound_speak_order` على `agent_first`
    (القيمة الافتراضية).
  </Step>

  <Step title="حافظ على رصيد موجب">
    تُرجع المكالمات الصادرة `402 Payment Required` إذا كان الرصيد ≤
    `$0.00`. اشحن الرصيد عبر
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    أو فعّل [إعادة الشحن التلقائي](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## أجرِ مكالمة باستخدام وكيل محفوظ

أبسط طريقة — الإشارة إلى وكيل عبر معرّفه:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'
```

الاستجابة:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  يعني `status: "initiated"` فقط أنه تم قبول الطلب — المكالمة
  **لم تتصل بعد**. استعلم دورياً عن
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  للحصول على الحالة المباشرة (`in_progress` → `completed` / `failed`).
</Warning>

## أجرِ مكالمة بإعداد مضمن

إذا أردت موجّهاً لمرة واحدة لا يستحق الحفظ كوكيل،
فمرر `config` بدلاً من ذلك. يتطابق الشكل مع مخطط الاستجابة لخطاف الويب
[`call.incoming`](/ar/webhooks/call-incoming):

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## تابع المكالمة

بالتوازي، اشترك في خطاف الويب
[`telephony.complete`](/ar/webhooks/events) —
وهو أسرع طريقة لمعرفة انتهاء المكالمة. إذا لم تتمكن من استقبال خطافات
الويب الواردة، فاستعلم دورياً عن `GET /v1/calls/{call_id}` كل بضع ثوانٍ؛
يتضمن السجل `end_reason` و`duration_seconds` ورابط التسجيل عند انتهاء المكالمة.

## حالات الفشل التي تستحق المعالجة

| الخطأ                                                    | الحل                                                                                                        |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | اشحن الرصيد أو فعّل إعادة الشحن التلقائي                                                                    |
| تم حظر المكالمات الصادرة `403` (رقم عرض توضيحي)          | أحضر رقم VoIP بدلاً من ذلك                                                                                  |
| تم حظر المكالمات الصادرة `403` (رقم VoIP غير متحقق منه)  | نفّذ [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | تأكد من أن `from_number` يطابق رقم هاتف تملكه                                                               |
| `502 Bad Gateway`                                        | فشل عابر في SIP / LiveKit؛ من الآمن إعادة المحاولة                                                          |

## التحكم في مدة الانتظار

يمكن تحديد حد أقصى للمكالمات الصادرة التي تطول لأن الطرف المتصل به بطيء في الاستجابة
(قوائم IVR، قوائم الانتظار) باستخدام `max_hold_seconds`:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

ينهي الوكيل المكالمة إذا لم يتم تلقي أي صوت بشري خلال آخر
N ثانية. القيمة الافتراضية هي 900 (15 دقيقة).

***

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

<CardGroup cols={2}>
  <Card title="مرجع المكالمات الصادرة" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    كل حقول الطلبات ورموز الأخطاء.
  </Card>

  <Card title="استقبال call.complete" icon="bolt" href="/ar/webhooks/call-complete">
    أرسل المكالمات الصادرة المكتملة إلى نظامك بشكل متدفق.
  </Card>

  <Card title="الفوترة" icon="credit-card" href="/api-reference/billing">
    إعادة الشحن تلقائيًا حتى لا تفشل المكالمات الصادرة بسبب الرصيد.
  </Card>

  <Card title="اختبار الوكلاء الصادرين" icon="flask" href="/ar/guides/test-agents">
    نفّذ تشغيلًا تجريبيًا لوكيلك الصادر قبل الإنتاج.
  </Card>
</CardGroup>