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

# المكالمات والتسجيلات

> أجرِ مكالمة صادرة، اقرأ السجلّ، واجلب تسجيلًا.

## طريقتان لإجراء مكالمة

|             | `POST /v1/callback`                                                    | `POST /v1/calls`         |
| ----------- | ---------------------------------------------------------------------- | ------------------------ |
| **المنتج**  | [Web Callback](/ar/web-callback)                                       | الاتّصال البرمجيّ        |
| **الفكرة**  | «عاوِد الاتّصال بهذا العميل» — غالبًا عبر أداة أو طابور (`from_queue`) | «أجرِ هذه المكالمة الآن» |
| **Sandbox** | يدعم ترويسة `x-wave-simulate` وأرقام الاختبار                          | مكالمات حقيقيّة فقط      |

تنشأ كلتاهما من رقمك، وفي sandbox تكونان مقيّدتين برقم تسجيلك. ويزيل مفتاح
**production** هذا القيد.

```bash theme={null}
curl -X POST https://api.wave.sa/v1/calls \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000", "caller_id_name": "Acme" }'
```

```json theme={null}
{
  "call_id": "27d6dd39-…",
  "status": "initiated",
  "direction": "outbound",
  "to": "+966 50 XXX 0000",
  "from": "+966115209300",
  "sandbox": false,
  "created_at": "2026-08-19T10:00:00.000Z"
}
```

## اقرأ سجلّ المكالمات

يُعيد `GET /v1/calls` مكالماتك من الأحدث للأقدم مع تقسيم صفحات بالمؤشّر. يحتاج نطاق
`calls:read`.

```bash theme={null}
curl "https://api.wave.sa/v1/calls?limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
```

```json theme={null}
{
  "data": [
    {
      "id": "27d6dd39-…",
      "type": "outbound",
      "status": "ended",
      "from": "+966115209300",
      "to_masked": "+966 50 XXX 0000",
      "duration_seconds": 42,
      "created_at": "2026-08-19T10:00:00.000Z",
      "answered_at": "2026-08-19T10:00:05.000Z",
      "ended_at": "2026-08-19T10:00:47.000Z"
    }
  ],
  "next_cursor": "eyJ…",
  "limit": 20
}
```

مرّر `next_cursor` بصيغة `?cursor=` للتنقّل. وأرقام الوجهة مُقنّعة.

## اجلب تسجيلًا

يُعيد `GET /v1/calls/{call_id}/recording` **رابط تنزيل محدود المدّة** (صالح \~60 دقيقة).
يحتاج نطاق `recordings:read` ومفتاح **production**.

```bash theme={null}
curl https://api.wave.sa/v1/calls/27d6dd39-…/recording \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
```

```json theme={null}
{
  "call_id": "27d6dd39-…",
  "url": "https://oss.example.com/…?signature=…",
  "expires_at": "2026-08-19T11:00:00.000Z"
}
```

<Note>
  لا يوجد تسجيل إلّا إذا سُجّلت المكالمة (عبر `<Dial record>` أو
  [`<Record>`](/ar/voice/waveml#record) في الخلفيّة) **و** كان التخزين مُهيّأً لحسابك.
  قبل ذلك يُعيد `404 RECORDING_NOT_FOUND` أو `503 RECORDING_SERVICE_UNAVAILABLE`.
  وتحصل مفاتيح sandbox على `400 SANDBOX_KEY_NOT_ALLOWED`.
</Note>

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

<CardGroup cols={2}>
  <Card title="الاتّصال عبر الويب" icon="microphone" href="/ar/voice/web-calling">
    أجرِ مكالمات من المتصفّح عبر الـ SDK.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/ar/webhooks">
    استقبِل أحداث المكالمات بدل الاستعلام المتكرّر.
  </Card>
</CardGroup>