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

# Web Callback

> كيف يعمل الاتصال بنقرة واحدة، ودورة حياة المكالمة، وقراءة سجلّات المكالمات.

يُجري Web Callback اتصالًا بنقرة واحدة من الـ backend الخاصّ بك: تحدّد وجهة، فتطلبها Wave عبر الـ telephony backend الخاصّ بها وتجسر المكالمة.

## إجراء مكالمة

`POST /v1/callback` مع رقم `to` على الأقلّ. راجع البدء السريع ومرجع الـ API.

| الحقل              | مطلوب | الوصف                                          |
| ------------------ | ----- | ---------------------------------------------- |
| `to`               | ✅     | رقم وجهة سعوديّ بصيغة E.164 (`+9665XXXXXXXX`). |
| `caller_id_name`   | —     | اسم معرّف المتّصل المعروض للمستقبِل.           |
| `caller_id_number` | —     | رقم معرّف المتّصل.                             |
| `from_queue`       | —     | التحويلة/الطابور المصدر.                       |
| `metadata`         | —     | كائن مفتاح/قيمة يُعاد إرساله في الـ webhooks.  |

## دورة حياة المكالمة

يُنشأ الـ callback بالحالة `status: "initiated"` ويُعيد `202` فورًا.

ثمّ تتقدّم المكالمة عبر دورة حياتها حسبما يُبلغ الـ telephony backend — `answered` (مع `answered_at`)، ثمّ `ended` (مع `duration`). ويُطلق كلّ انتقال الـ [webhook](/ar/webhooks) المقابل (`call.answered` و`call.ended`)، وتُكتب الحالة النهائيّة والمدّة في سجلّ المكالمة.

```
initiated  ──▶  answered  ──▶  ended
```

<Note>
  عامِل الرمز `202` بوصفه "مقبولًا"، لا "مكتملًا". اشترِك في الـ
  [webhooks](/ar/webhooks) — أو استعلِم عن `GET /v1/calls` — لتتابع المكالمة حتّى
  `answered` / `ended`.
</Note>

## سجلّات المكالمات

يُسجَّل كلّ callback. استرجِعها عبر `GET /v1/calls` — مُقسَّمة بالصفحات باستخدام cursor (`cursor`، و`limit` حتّى 100)، والأرقام مُقنَّعة — أو اعرِضها في صفحة Call Logs في لوحة التحكّم. راجع مرجع الـ API للاطّلاع على الطلب/الاستجابة الكاملين.

## إلغاء مكالمة مفردة / استرجاعها

الـ `GET /v1/callbacks/:id` و`DELETE /v1/callbacks/:id` قادمان قريبًا — وهما غير فعّالين بعد. وستوثّقهما هذه الصفحة عند إطلاقهما.