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

# الأرقام الافتراضيّة

> امنح كلّ مستخدم رقمه السعوديّ الخاصّ الذي يردّ بتعليماته.

**الرقم الافتراضيّ** هو رقم سعوديّ (DID) مخصّص لأحد *مستخدميك*. حين يتّصل به أحدهم،
يردّ Wave ويشغّل **تعليمات ذلك المستخدم** — رمز بوّابة، ملاحظات تسليم، تحيّة — أو يحوّل
المكالمة إلى رقمه الحقيقيّ دون كشفه. لا يحتاج مستخدمك لنشر رقمه الشخصيّ أبدًا.

<Note>
  تستخدم الأرقام الافتراضيّة مفتاح **production** (`sk_live_`) ونطاقَي
  `virtual_numbers:write` / `virtual_numbers:read`. اطلب من جهة اتّصالك في Wave تفعيل
  الميزة لحسابك.
</Note>

## تخصيص رقم لمستخدم

`POST /v1/virtual-numbers`. عرّف المستخدم بـ **مُعرّفك أنت** (`external_user_id`) —
والطلب **idempotent** على هذا المُعرّف، فإعادة المحاولة تُعيد الرقم نفسه بدل تخصيص
رقم ثانٍ.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wave.sa/v1/virtual-numbers \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "external_user_id": "user_8842",
      "display_name": "ليلى",
      "instructions": {
        "text": "يُرجى ترك الطرد عند الباب. رمز البوّابة 4471.",
        "language": "ar",
        "forward_to": "+966541704013"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.wave.sa/v1/virtual-numbers", {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_user_id: "user_8842",
      display_name: "ليلى",
      instructions: {
        text: "يُرجى ترك الطرد عند الباب. رمز البوّابة 4471.",
        language: "ar",
        forward_to: "+966541704013",
      },
    }),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

### الطلب

| الحقل                     | النوع      | مطلوب   | ملاحظات                                                         |
| ------------------------- | ---------- | ------- | --------------------------------------------------------------- |
| `external_user_id`        | نصّ        | **نعم** | مُعرّفك للمستخدم (≤128 حرفًا). مفتاح عدم التكرار (idempotency). |
| `display_name`            | نصّ        | لا      | ≤120 حرفًا.                                                     |
| `type`                    | نصّ        | لا      | `mobile`، `landline`، `tollfree`، `unified`، `shortcode`.       |
| `prefix`                  | نصّ        | لا      | البادئة الرقميّة المفضّلة.                                      |
| `instructions.text`       | نصّ        | لا      | يُنطَق للمتّصل (≤1000 حرف).                                     |
| `instructions.audio_url`  | نصّ (رابط) | لا      | يُشغَّل بدل `text` عند ضبطه.                                    |
| `instructions.language`   | نصّ        | لا      | `ar` أو `en`.                                                   |
| `instructions.forward_to` | نصّ        | لا      | رقم سعوديّ يُحوَّل إليه، مع عرض هويّة المتّصل.                  |

### الاستجابة — `201 Created` (أو `200 OK` عند إعادة المحاولة)

```json theme={null}
{
  "data": {
    "id": "8f2c…",
    "e164": "+966590007001",
    "status": "assigned",
    "external_user_id": "user_8842",
    "display_name": "ليلى",
    "contact_id": "1a9b…",
    "instructions": {
      "text": "يُرجى ترك الطرد عند الباب. رمز البوّابة 4471.",
      "audio_url": null,
      "language": "ar",
      "forward_to": "+966541704013"
    },
    "assigned_at": "2026-08-19T10:00:00.000Z"
  }
}
```

<Tip>
  يبدأ صوت `audio_url` المُسجَّل فورًا؛ أمّا `text` فيمرّ بتحويل النصّ إلى كلام. اضبط
  الاثنين ويفوز الصوت — فتبدأ بالنصّ اليوم وتترقّى لتسجيل لاحقًا دون تغيير في الشيفرة.
</Tip>

## تحديث تعليمات مستخدم

`PUT /v1/virtual-numbers/:id/instructions` — تُحرَّر في مكانها، دون إعادة تخصيص.

```bash cURL theme={null}
curl -X PUT https://api.wave.sa/v1/virtual-numbers/8f2c…/instructions \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "text": "انتقلتُ. يُرجى الاتّصال عند وصولك.", "language": "ar" }'
```

## القائمة والبحث

`GET /v1/virtual-numbers` — رشّح بـ `external_user_id`، وقسّم الصفحات بـ `limit`
(≤100) و`offset`. ويُعيد `GET /v1/virtual-numbers/:id` عنصرًا واحدًا.

```json theme={null}
{
  "data": [ { "id": "8f2c…", "e164": "+966590007001", "external_user_id": "user_8842", "…": "…" } ],
  "meta": { "limit": 50, "offset": 0 }
}
```

## تحرير رقم

`DELETE /v1/virtual-numbers/:id` يُعيد الرقم إلى المجمّع ويحرّر المستخدم لتخصيص رقم
آخر لاحقًا.

```json theme={null}
{ "id": "8f2c…", "status": "released" }
```

<Warning>
  التعليمات **بيانات شخصيّة** لمستخدميك — رمز بوّابة، عنوان، رقم هاتف حقيقيّ. لا يسجّل
  Wave محتواها أبدًا. تعامَل مع ما تخزّنه من أرقام وتعليمات بالعناية نفسها.
</Warning>

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

<CardGroup cols={2}>
  <Card title="كيف يعمل الصوت" icon="phone-volume" href="/ar/voice/overview">
    دورة حياة المكالمة خلف الرقم الافتراضيّ.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/ar/webhooks">
    اطّلع على إشعار عند طلب رقم افتراضيّ.
  </Card>
</CardGroup>