---
title: "إجراء مكالمات صادرة (API)"
description: "فعِّل مكالمة صادرة يقودها الذكاء الاصطناعي من تعليماتك البرمجية — لاستطلاعات الرأي أو المتابعة أو مسارات التأكيد."
---

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

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

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

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

<Steps>
  <Step title="اختر رقماً مفعّلاً للمكالمات الصادرة">
    استخدم رقماً تملكه عبر
    [اتصال VoIP](/api-reference/voip-connections)، أو اطلب الإذن
    لاستخدام أرقام ThunderPhone الخاصة بك للمكالمات الصادرة من صفحة أرقام
    الهاتف. تبدأ أرقام ThunderPhone مخصصة للمكالمات الواردة فقط. تراجع ThunderPhone كل
    طلب يدوياً؛ وبعد الموافقة، يمكن لتلك الأرقام إجراء مكالمات حتى الحد اليومي
    المعتمد (يُعاد ضبطه عند 00:00 UTC) وتشغيل الحملات، ويمكنك
    طلب حد أعلى. لا تملك أرقام VoIP الخاصة بالعملاء حداً يومياً، لذا نوصي
    بها للمكالمات الصادرة. راجع
    [استخدم أرقامك الخاصة](/ar/guides/bring-your-own-numbers).
  </Step>
  <Step title="أنشئ وكيلاً">
    يميل موجّه مخصص للمكالمات الصادرة إلى البدء بتعريف الوكيل
    بنفسه والغرض منه — "مرحباً، هذه Acme تتصل لتأكيد
    موعدك غداً الساعة 3 مساءً…" عيّن
    `outbound_speak_order` إلى `agent_first` (الإعداد الافتراضي).
  </Step>
  <Step title="حافظ على رصيد موجب">
    تُرجع المكالمات الصادرة `402 Payment Required` إذا كان الرصيد ≤
    `$0.00`. أضف رصيداً أو فعّل إعادة التعبئة التلقائية ضمن
    **المؤسسة ← إعدادات الفوترة** في لوحة التحكم. يمكن لمفتاح `sk_live_`
    الخاص بك التحقق من الرصيد باستخدام
    [`GET /v1/billing`](/api-reference/billing#get-billing-account)، لكنه
    لا يمكنه إضافة رصيد أو تغيير إعادة التعبئة التلقائية.
  </Step>
</Steps>

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

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

```bash
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":   "+14155552671",
    "agent_id":    12
  }'
```

الاستجابة:

```json
{ "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
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":   "+14155552671",
    "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` ورابط التسجيل
بعد انتهاء المكالمة.

إذا كان وكيلك مُعدًّا لاستخراج بيانات منظّمة بعد المكالمة،
تُسلَّم تلك البيانات بشكل منفصل بعد اكتمال الإنهاء.

### تمرير متغيرات لكل مكالمة إلى وكيل محفوظ

يمكن للوكلاء المحفوظين استخدام عناصر نائبة مثل `{{name}}` أو `{{name|there}}` في
نص الموجّه. عند إجراء مكالمة صادرة باستخدام `agent_id`، مرّر
`variables` بالقيم الخاصة بتلك المكالمة:

```json
{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}
```

استخدم قيماً نصية بمفاتيح تحمل أسماء العناصر النائبة. تنطبق هذه المتغيرات على
الوكلاء المحفوظين؛ ولا يستخدم مثال `config` المضمّن في هذا الدليل هذه المتغيرات.

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

| الخطأ | الحل |
|-------|-----|
| `402 Payment Required` | اشحن الرصيد أو فعّل إعادة الشحن التلقائية |
| `400` مع `code: destination_not_allowed` | لا يتصل ThunderPhone بهذا الرقم: أرقام غير صالحة، أو أرقام طوارئ، أو أرقام برسوم إضافية، أو رموز قصيرة، أو بلدان خاضعة للعقوبات. من أرقام ThunderPhone، يُسمح فقط بالأرقام العادية في الولايات المتحدة وكندا، دون أرقام برسوم إضافية. يوضح `reason` أيّها ينطبق؛ راجع [الوجهات المحظورة](/api-reference/outbound-calls#blocked-destinations) |
| `409` مع `retryable: false` لرقم ThunderPhone | اتبع `code`: اطلب تفعيل الاتصال الصادر في صفحة أرقام الهاتف، أو انتظر مراجعة معلّقة، أو استخدم رقمًا آخر مؤهلًا |
| `429` مع `code: platform_outbound_daily_limit_reached` | استخدمت المؤسسة مكالمات اليوم الصادرة من أرقام ThunderPhone. انتظر `resets_at` (00:00 UTC)، أو اطلب حدًا أعلى في صفحة أرقام الهاتف، أو اتصل من رقم على اتصال VoIP الخاص بك |
| `429` مع `code: concurrent_call_limit_reached` | لدى المؤسسة عدد مكالمات جارية يساوي [حد المكالمات المتزامنة](/api-reference/introduction#call-limits) لديها (20 افتراضيًا، بما في ذلك المكالمات الواردة والصادرة ومكالمات الويب والاختبار). أعد المحاولة بعد عدد الثواني الوارد في ترويسة `Retry-After` أو عند انتهاء مكالمة؛ أرسل بريدًا إلكترونيًا إلى support@thunderphone.com لرفع الحد |
| `429` مع `code: same_number_too_soon` | اتصلت بالرقم نفسه `to_number` قبل أقل من 10 ثوانٍ. أعد المحاولة بعد عدد الثواني الوارد في ترويسة `Retry-After` |
| `409` مع `retryable: false` لرقم VoIP تابع لعميل | صحح الحالة التي يحددها `code`؛ عند فشل التحقق، نفّذ [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| تعارض التكرار `409` | أعد استخدام المفتاح فقط مع الطلب الأصلي بعد توحيده، أو أرسل مفتاحًا جديدًا |
| `404 from_number is not registered to this organization` | تأكد من أن `from_number` يطابق رقم هاتف نشطًا في مؤسستك. يعيد الرقم الذي يجري تجهيزه بالفعل، أو الذي فشل، أو الذي يجري إصداره، أو الذي صدر أيضًا هذه الاستجابة |
| `500` مع حقل `detail` فقط | لم يتم إعداد مسار صادر. تواصل مع الدعم؛ هذه ليست مشكلة في حالة الرقم يمكنك تصحيحها |
| `502 Bad Gateway` | فشل عابر في SIP / LiveKit؛ يمكن إعادة المحاولة بأمان |

راجع [مرجع المكالمات الصادرة](/api-reference/outbound-calls#error-responses)
للاطلاع على القائمة الكاملة المستقرة لرموز الأهلية وكلا شكلي استجابة `409`.
إذا أصبح رقم نشط غير مؤهل بعد قبول الطلب وقبل
إجراء المكالمة، يعيد الفحص النهائي حمولة `409` غير القابلة لإعادة المحاولة.

## التحكم في وقت الانتظار

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

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "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>