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

# مرجع WaveML

> الأوامر التي يتحدّث بها مسار مكالمة Wave — نظير Wave لـ TwiML.

**WaveML** هي لغة XML صغيرة تصف ما يحدث في المكالمة: تشغيل رسالة، جمع رقم، التحويل
إلى وكيل، التسجيل، أو التسليم لوكيل صوتيّ بالذكاء الاصطناعيّ. إن كنت تعرف
[TwiML](https://www.twilio.com/docs/voice/twiml) فستجد WaveML مألوفة.

<Note>
  **كيف تُؤلَّف المسارات اليوم.** WaveML هي ما ينفّذه محرّك Wave الصوتيّ. حاليًّا
  تُهيَّأ مسارات المكالمة لحسابك (لوحة التحكّم + جهة اتّصالك في Wave) لا عبر API عامّ —
  وواجهة تأليف المسارات على خارطة الطريق. هذه الصفحة هي **مرجع** اللغة نفسها لتعرف
  بدقّة ما يستطيع المسار فعله.
</Note>

## غلاف الاستجابة

حين تحتاج المكالمة إلى تعليمات، يُرسِل المحرّك طلبًا إلى مسارك وينتظر مستند WaveML
ردًّا. تُنفَّذ الأوامر من الأعلى للأسفل؛ وتنتهي المكالمة عند `<Hangup>` أو
`<Response>` فارغ.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response wave_tenant="acme" wave_tenant_cc="20">
  <Say node_id="n1">أهلاً بك في أكمي.</Say>
  <Hangup node_id="n2"/>
</Response>
```

في **أوّل** ردّ للمكالمة، اضبط `wave_tenant` وحدّ التزامنه `wave_tenant_cc` على جذر
`<Response>`. يحمل كلّ أمر `node_id` — وهو مؤشّر يُعيده المحرّك في طلبه التالي ليعرف
مسارك أين وصلت المكالمة. راجِع [كيف يعمل الصوت](/ar/voice/overview) للحلقة الكاملة.

***

## Play

تشغيل ملفّ صوتيّ (WAV/MP3 عبر HTTPS).

```xml theme={null}
<Play node_id="n1">https://cdn.example.com/welcome.wav</Play>
```

| الخاصّيّة | الوصف                    | الافتراضيّ |
| --------- | ------------------------ | ---------- |
| `node_id` | مُعرّف فريد لهذه الخطوة. | —          |
| `loop`    | عدد مرّات التكرار.       | `1`        |
| `digit`   | رقم DTMF يقطع التشغيل.   | —          |

## Say

نطق نصّ عبر تحويل النصّ إلى كلام. العربيّة والإنجليزيّة مدعومتان.

```xml theme={null}
<Say node_id="n1" language="ar">أهلاً بك في أكمي</Say>
```

| الخاصّيّة  | الوصف                             | الافتراضيّ |
| ---------- | --------------------------------- | ---------- |
| `node_id`  | مُعرّف فريد لهذه الخطوة.          | —          |
| `voice`    | تلميح الصوت للنطق.                | —          |
| `language` | وسم لغة BCP-47، مثل `ar` أو `en`. | —          |

<Tip>
  يبدأ صوت `<Play>` المُسجَّل فورًا؛ أمّا `<Say>` فيمرّ بتحويل النصّ إلى كلام. للرسائل
  الثابتة، فضّل `<Play>`.
</Tip>

## Gather

جمع مُدخَل DTMF (لوحة المفاتيح). ضع `<Say>` أو `<Play>` بداخله كرسالة؛ وتصل الأرقام
التي يضغطها المتّصل في الطلب التالي عبر `dtmf`.

```xml theme={null}
<Gather node_id="menu" numDigits="1" timeout="8">
  <Say>للمبيعات اضغط 1، وللدعم اضغط 2.</Say>
</Gather>
```

| الخاصّيّة     | الوصف                               | الافتراضيّ |
| ------------- | ----------------------------------- | ---------- |
| `node_id`     | مُعرّف فريد لهذه الخطوة.            | —          |
| `numDigits`   | كم رقمًا يُجمَع.                    | —          |
| `timeout`     | ثوانٍ انتظار المُدخَل.              | —          |
| `finishOnKey` | مفتاح ينهي الجمع مبكّرًا (مثل `#`). | —          |
| `tries`       | محاولات إعادة الطلب.                | —          |

## Dial

تحويل المكالمة إلى رقم آخر أو مستخدم SIP. يرى الطرف المطلوب `callerId`.

```xml theme={null}
<Dial node_id="n1" callerId="0115209300" record="true">920012345</Dial>
```

| الخاصّيّة   | الوصف                         | الافتراضيّ |
| ----------- | ----------------------------- | ---------- |
| `node_id`   | مُعرّف فريد لهذه الخطوة.      | —          |
| `callerId`  | الرقم المعروض للطرف المطلوب.  | —          |
| `timeout`   | ثوانٍ انتظار الردّ.           | —          |
| `timeLimit` | أقصى مدّة للمكالمة بالثواني.  | —          |
| `dialMusic` | رابط نغمة الانتظار.           | —          |
| `record`    | `true` يسجّل الطرف المُحوَّل. | `false`    |

## Enqueue

وضع المتّصل في طابور مركز اتّصال. يرنّ الوكلاء المسجَّل دخولهم — تُدار إدارتهم عبر
[واجهة الطوابير](/ar/voice/queues). اسم الطابور هو نصّ العنصر؛ وتُنشَأ الطوابير عند
الطلب.

```xml theme={null}
<Enqueue node_id="n1" strategy="ring-all" moh="https://cdn.example.com/hold.wav">support</Enqueue>
```

| الخاصّيّة  | الوصف                        | الافتراضيّ |
| ---------- | ---------------------------- | ---------- |
| `node_id`  | مُعرّف فريد لهذه الخطوة.     | —          |
| `strategy` | `ring-all` أو `round-robin`. | `ring-all` |
| `moh`      | رابط موسيقى الانتظار.        | —          |

## Record

تسجيل المكالمة. بما أنّ `<Enqueue>`/`<Say>` لا يملكان خاصّيّة تسجيل مضمّنة، فإنّ
`<Record background="true"/>` المستقلّ يُفعِّل التسجيل لمكالمة تتدفّق بعدها إلى أوامر
أخرى.

```xml theme={null}
<Response wave_tenant="acme">
  <Record node_id="rec" background="true"/>
  <Enqueue node_id="n1">support</Enqueue>
</Response>
```

| الخاصّيّة    | الوصف                                          | الافتراضيّ |
| ------------ | ---------------------------------------------- | ---------- |
| `node_id`    | مُعرّف فريد لهذه الخطوة.                       | —          |
| `background` | `true` يسجّل في الخلفيّة ويُكمِل المسار فورًا. | `false`    |

## AIAgent

تسليم المكالمة لوكيل صوتيّ بالذكاء الاصطناعيّ في الزمن الحقيقيّ. يعمل تحويل الكلام
إلى نصّ، ونموذج لغويّ، وتحويل النصّ إلى كلام بشكل حيّ، مع إمكان المقاطعة. نصّ العنصر
هو موجِّه شخصيّة الوكيل.

```xml theme={null}
<AIAgent node_id="n2">
  You are Noura, a friendly outreach voice for Alfa Electric.
  If the customer asks for a human, end with the outcome word "transfer".
  If they ask never to be contacted, end with the outcome word "dnc".
</AIAgent>
```

`<AIAgent>` **ليس أمرًا نهائيًّا**. عند انتهاء المحادثة، يعود المحرّك إلى مسارك بـ
`node_id` هذا الأمر وكلمة نتيجة `aiagent_result` — `completed` أو `transfer` أو `dnc`
أو أيّ كلمة يعرّفها موجِّهك — ويقرّر مسارك ما يحدث تاليًا:

```xml theme={null}
<!-- aiagent_result=transfer -> وصّل بموظّف بشريّ -->
<Response>
  <Dial node_id="n3" callerId="0115209300">920012345</Dial>
  <Hangup node_id="n4"/>
</Response>
```

| الخاصّيّة | الوصف                    | الافتراضيّ |
| --------- | ------------------------ | ---------- |
| `node_id` | مُعرّف فريد لهذه الخطوة. | —          |
| `voice`   | تلميح الصوت لنطق الوكيل. | —          |

<Warning>
  عالِج دائمًا أيّ `aiagent_result` غير معروف بحلّ احتياطيّ آمن — ومعاملته كـ
  `completed` وإنهاء المكالمة خيار افتراضيّ جيّد.
</Warning>

## Pause

انتظار صامت.

```xml theme={null}
<Pause node_id="n1" length="2"/>
```

| الخاصّيّة | الوصف                    | الافتراضيّ |
| --------- | ------------------------ | ---------- |
| `node_id` | مُعرّف فريد لهذه الخطوة. | —          |
| `length`  | ثوانٍ الانتظار.          | `1`        |

## Hangup

إنهاء المكالمة.

```xml theme={null}
<Hangup node_id="n1"/>
```

***

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

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

  <Card title="الطوابير" icon="users-line" href="/ar/voice/queues">
    سجّل دخول الوكلاء وخروجهم من طوابير `<Enqueue>`.
  </Card>
</CardGroup>