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

# الطوابير

> وجّه المتّصلين إلى الوكلاء عبر طوابير مركز الاتّصال، وأدِر من سجّل دخوله.

حين يصل مسار المكالمة إلى أمر [`<Enqueue>`](/ar/voice/waveml#enqueue)، ينتظر المتّصل
في طابور مُسمّى ويرنّ عند الوكلاء **المسجَّل دخولهم إليه**. تُنشَأ الطوابير عند الطلب —
لا شيء لتهيئته. تُسجِّل هذه الواجهة دخول الوكلاء وخروجهم وتُظهِر لك من ينتظر.

<Note>
  يستخدم التحكّم بالطوابير مفتاح **production** (`sk_live_`) ونطاقَي `queues:write` /
  `queues:read`. لا تستطيع مفاتيح sandbox إدارة الطوابير.
</Note>

## تسجيل دخول وكيل

`POST /v1/queues/agents/login` — يبدأ الوكيل بالرنين لمكالمات ذلك الطابور.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wave.sa/v1/queues/agents/login \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "agent": "agent_001", "queue": "support" }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.wave.sa/v1/queues/agents/login", {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent: "agent_001", queue: "support" }),
  });
  ```
</CodeGroup>

| الحقل   | النوع | مطلوب   | ملاحظات                                          |
| ------- | ----- | ------- | ------------------------------------------------ |
| `agent` | نصّ   | **نعم** | `A–Z a–z 0–9 _ -`، ≤64 حرفًا.                    |
| `queue` | نصّ   | **نعم** | المحارف نفسها، ≤64 حرفًا. يطابق اسم `<Enqueue>`. |

```json theme={null}
{ "agent": "agent_001", "queue": "support", "status": "logged_in" }
```

## تسجيل خروج وكيل

`POST /v1/queues/agents/logout` يسجّل خروج الوكيل من **جميع** الطوابير.

```bash cURL theme={null}
curl -X POST https://api.wave.sa/v1/queues/agents/logout \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "agent_001" }'
```

```json theme={null}
{ "agent": "agent_001", "queue": null, "status": "logged_out" }
```

## من ينتظر

`GET /v1/queues/members?queue=support` يُعيد لقطة حيّة للمتّصلين في الطابور.

```json theme={null}
{
  "queue": "support",
  "count": 2,
  "members": [
    {
      "position": 1,
      "channel_uuid": "27d6dd39-…",
      "src_number": "+966501112222",
      "state": "waiting",
      "wait_seconds": 45,
      "agent": null
    }
  ]
}
```

| الحقل          | المعنى                                              |
| -------------- | --------------------------------------------------- |
| `position`     | المكان في الصفّ (1 = التالي).                       |
| `state`        | `waiting` أو `talking`.                             |
| `wait_seconds` | كم انتظر هذا المتّصل.                               |
| `agent`        | الوكيل الذي يخدم المتّصل، أو `null` أثناء الانتظار. |

<Warning>
  يتحدّث التحكّم بالطوابير إلى المحرّك الصوتيّ الحيّ. إن تعذّر الوصول إليه ستحصل على
  `QUEUE_SERVICE_UNAVAILABLE` (503) أو `QUEUE_CONTROL_FAILED` (502) — أعِد المحاولة مع
  تراجُع تدريجيّ.
</Warning>

## الجمع بينها

<Steps>
  <Step title="يضع مسارك المتّصل في الطابور">
    يُسمّي أمر [`<Enqueue>`](/ar/voice/waveml#enqueue) الطابور، مثل `support`.
  </Step>

  <Step title="يسجّل الوكلاء دخولهم">
    استدعِ endpoint تسجيل الدخول لكلّ وكيل متاح على `support`.
  </Step>

  <Step title="يرنّ المتّصلون عند الوكلاء المسجَّلين">
    يرنّهم Wave حسب استراتيجيّة طابورك (`ring-all` أو `round-robin`).
  </Step>

  <Step title="تراقب الطابور">
    استعلِم `GET /v1/queues/members` لعرض حيّ؛ كما تسير أحداث مؤشّرات أداء الطابور على
    [تدفّق الأحداث](/ar/voice/overview#الأحداث-التي-يمكنك-الاشتراك-بها) الخاصّ بك.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="WaveML: Enqueue" icon="code" href="/ar/voice/waveml#enqueue">
    الأمر الذي يضع المتّصل في طابور.
  </Card>

  <Card title="كيف يعمل الصوت" icon="phone-volume" href="/ar/voice/overview">
    أين تقع الطوابير في دورة حياة المكالمة.
  </Card>
</CardGroup>