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

# التعامل مع المكالمات الواردة (واجهة برمجة التطبيقات)

> من البداية إلى النهاية: اضبط وكيلاً، وعيّنه لرقم هاتف، وتلقَّ مكالمة، وافحص النص المفرغ.

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

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

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

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

## 1. إنشاء وكيل

يجمع الوكيل الموجّه والصوت ومستوى المنتج الذي سيدير
المكالمة. راجع [الوكلاء](/api-reference/agents) للاطلاع على كل حقل
إعداد؛ والحد الأدنى هو:

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

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

<Note>
  للإنتاج، تجاوز الأرقام التجريبية و
  [أحضر أرقامك الخاصة عبر VoIP](/ar/guides/bring-your-own-numbers).
  الأرقام التجريبية مخصصة للمكالمات الواردة فقط ومحدودة الحجم.
</Note>

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

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

```bash theme={null}
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 نفسه ليصبح الرقم جاهزًا لإجراء المكالمات الصادرة أيضًا.

## 4. تلقّي مكالمة

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

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

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

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

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

احصل على النص المفرغ:

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

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

```bash theme={null}
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="تلقي خطافات ويب call.complete" icon="bolt" href="/ar/webhooks/call-complete">
    مرّر كل مكالمة مكتملة إلى مسار CRM / تحليلاتك.
  </Card>

  <Card title="التقييم بالذكاء الاصطناعي وتقارير المشكلات" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    قيّم كل مكالمة تلقائيًا ووجّه المكالمات التي تم وضع علامة عليها للمراجعة.
  </Card>
</CardGroup>