---
title: "معالجة المكالمات الواردة (API)"
description: "من البداية إلى النهاية: هيّئ وكيلاً صوتياً، وعيّنه لرقم هاتف، وتلقَّ مكالمة، وافحص النص المفرغ."
---

<Note>
  هل تنشئ وكيلك الأول يدويًا؟ ترشدك لوحة التحكم خلال هذا التدفق بالضبط — أنشئ الوكيل، وأضف رقمًا، وحاكي، وراجع — باستخدام معالج إرشادي. ابدأ من
  [البدء السريع في لوحة التحكم](/ar/quickstart-dashboard).
</Note>

التدفق القياسي لـ «الرد على هاتف بالذكاء الاصطناعي» من طرفيتك.
ستقوم بما يلي:

1. إنشاء وكيل باستخدام موجّه وصوت.
2. توفير رقم هاتف (أو إحضار رقمك) وتعيين الوكيل كمعالج للمكالمات الواردة.
3. الاتصال بالرقم. راقب سجل المكالمات، والنص المفرغ، والتسجيل.

إجمالي استدعاءات API: أربعة. الوقت الإجمالي: أقل من خمس دقائق.

## 1. أنشئ وكيلًا

يجمع الوكيل بين الموجّه والصوت ومستوى المنتج الذي سيدير
المكالمة. يمكنك أيضًا ضبط حدود المكالمات، مثل `max_call_duration_seconds`
و`ring_duration_seconds`، على الوكيل. يدعم الوكلاء كذلك `intro_clip`
و`intro_ring_count` لتشغيل مقدمة مسجلة مسبقًا وما يصل إلى رنتين قبل أن
يتحدث الوكيل. تحتاج الوكلاء الجديدة أيضًا إلى منطقة زمنية. إذا كان وكيلك
متعدد اللغات، يمكنك ضبط `language_switching` للتحكم في ما إذا كان يسأل قبل
تبديل اللغات أو يتبع لغة المتصل.
راجع [الوكلاء](/api-reference/agents) للاطلاع على كل حقل إعداد؛ والحد
الأدنى هو:

```bash
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'
```

احفظ قيمة `id` المعادة — ستحتاج إليها في الخطوة 2.

<Tip>
  اختر `spark` للأسئلة والأجوبة البسيطة بأقل تكلفة، و`bolt` عندما تكون السرعة
  هي الأهم. رقِّ إلى `storm-base-with-ack` عندما يحتاج موجّهك
  إلى استدلال أعمق ويمكنه تحمّل حشو لمدة نصف ثانية بينما
  يفكر النموذج. راجع
  [مستويات المنتج](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. احصل على رقم هاتف

إذا كنت تحتاج فقط إلى رقم للاتصال به، فاحصل على رقم ThunderPhone
من مجموعة أرقام ThunderPhone:

```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
```

تتضمن الاستجابة `id` و`number` بتنسيق E.164. تبدأ أرقام ThunderPhone
بالحالة `status="provisioning"` وتصبح `active` خلال بضع
ثوانٍ — استعلم دوريًا عن
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
لمراقبة الانتقال إذا كان ذلك يهمك.

<Note>
  تبدأ أرقام ThunderPhone للوارد فقط. يمكن لمسؤول المؤسسة طلب
  الاتصال الصادر من صفحة أرقام الهاتف. تراجع ThunderPhone كل
  طلب يدويًا؛ وبمجرد الموافقة، يمكن للأرقام إجراء المكالمات وتشغيل
  الحملات. لا تتغير أرقام VoIP الخاصة بالعملاء.
</Note>

## 3. عيّن الوكيل

اربط الوكيل من الخطوة 1 باتجاه المكالمات الواردة للرقم:

```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
```

هذا كل شيء — الرقم نشط. بعد الموافقة على الاتصال الصادر لمؤسستك،
يمكنك أيضًا ضبط `outbound_agent_id` في طلب PATCH نفسه. وحتى
ذلك الحين، ترفض واجهة API هذا التعيين بالرمز `400`.

إذا وجّهت المكالمات الواردة عبر خطاف ويب للإعدادات بدلاً من `inbound_agent_id` ثابت، يمكن لخطاف الويب هذا الآن إرجاع `timezone` لكل مكالمة إلى جانب `agent_id` و`variables`.

## 4. استقبل مكالمة

اتصل بالرقم من هاتفك. يرد الوكيل، ويعرّف بنفسه
وفقًا لموجّهك، وتبدأ المحادثة.

أثناء سير المكالمة، تظهر في
[`GET /v1/calls`](/api-reference/calls#list-calls) مع
`status="in_progress"`. وعند انتهائها، يُحدَّث السجل بقيم
`end_reason` و`duration_seconds` و`billable_minutes`، و(في النهاية)
رابط تسجيل ودرجة من الذكاء الاصطناعي.

تُحتسب المكالمات الواردة ضمن
[حد المكالمات المتزامنة](/api-reference/introduction#call-limits) لمؤسستك (20
مكالمة قيد التنفيذ افتراضيًا، مشتركة مع المكالمات الصادرة ومكالمات الويب والاختبار).
يُرفض أي اتصال يصل عند بلوغ الحد قبل أن يجيب الموجّه، ثم يُنهى، ولا تُفرض عليه رسوم،
ويُسجَّل كمكالمة فاشلة بسبب إنهاء `concurrent_call_limit_reached`. أرسل بريدًا إلكترونيًا إلى support@thunderphone.com إذا كنت
تحتاج إلى حد أعلى.

## 5. افحص النتائج

اجلب قائمة المكالمات الأخيرة:

```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

اجلب النص المفرغ:

```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

ورابط التسجيل (موقّع وقصير العمر):

```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

إذا اشتركت في
[خطاف الويب `telephony.complete`](/ar/webhooks/events)
فستتلقى البيانات نفسها كطلب POST إلى خادمك — راجع
[call.complete](/ar/webhooks/call-complete).

إذا كان وكيلك يضم حقول استخراج مُعدّة، فقد تتضمن حمولة المكالمة المكتملة
أيضًا بيانات مستخرجة ومنظَّمة.

---

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

<CardGroup cols={2}>
  <Card title="إعداد ديناميكي لكل مكالمة" icon="bolt" href="/ar/guides/dynamic-call-config">
    اختر وكيلًا مختلفًا لكل متصل بناءً على رقم الهاتف أو
    منطق مخصص في خطاف ويب.
  </Card>
  <Card title="إضافة تكاملات الأدوات" icon="screwdriver-wrench" href="/ar/guides/build-tool-integration">
    اسمح للوكيل باستدعاء واجهات برمجة التطبيقات الخاصة بك أثناء المحادثة.
  </Card>
  <Card title="تحويل المكالمات" icon="phone-arrow-right" href="/ar/guides/call-transfers">
    وجّه المتصلين مباشرةً أو تحقّق من الوجهة قبل توصيلهم.
  </Card>
  <Card title="تلقي خطافات ويب call.complete" icon="bolt" href="/ar/webhooks/call-complete">
    أرسل كل مكالمة مكتملة بشكل متدفق إلى منظومة إدارة علاقات العملاء / التحليلات لديك.
  </Card>
  <Card title="التقييم بالذكاء الاصطناعي وتقارير المشكلات" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    قيّم كل مكالمة تلقائيًا ووجّه المكالمات المُعلَّمة للمراجعة.
  </Card>
</CardGroup>