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

# واتساب

> إرسال رسائل واتساب، وإدارة القوالب، واستقبال أحداث حالة التسليم.

تعمل مراسلة واتساب عبر نفس طبقة القنوات المستخدمة في أسطح مراسلة Wave الأخرى. تُرسل رسالة، وتحصل فورًا على تأكيد `queued`، وتصل النتيجة الفعليّة (`delivered` أو `read` أو `failed`) لاحقًا كحدث [webhook](/ar/webhooks).

<Note>
  الإرسال (نص، قالب، ووسائط) فعليّ الآن — تصل الرسائل إلى هواتف حقيقية. أحداث الـ webhook الخاصّة بحالة التسليم والرسائل الواردة (`message.delivered`، `message.read`، `message.received`) قيد الإنجاز على جانب المزوّد؛ إلى حين اكتمالها، قد تستمرّ الرسائل المُرسَلة بالظهور بحالة `queued` في لوحة التحكّم حتى بعد وصولها فعليًّا.
</Note>

## إرسال رسالة

`POST /v1/messages`

| الحقل             | مطلوب | الوصف                                                                            |
| ----------------- | ----- | -------------------------------------------------------------------------------- |
| `channel`         | ✅     | `whatsapp` (يقبل أيضًا `sms` و`webchat` و`email` — تلك القنوات غير مفعَّلة بعد). |
| `to`              | ✅     | رقم واتساب المستلم بصيغة E.164 (`+9665XXXXXXXX`).                                |
| `content`         | ✅     | أحد أنواع المحتوى الثلاثة أدناه.                                                 |
| `conversation_id` | —     | يجمع الرسائل المرتبطة في محادثة واحدة. تُنشأ محادثة جديدة لكلّ رسالة افتراضيًّا. |
| `metadata`        | —     | كائن مفتاح/قيمة، يُعاد إرساله في الـ webhooks.                                   |

يُعيد `202` مع `message_id` و`provider_message_id` و`status: "queued"`.

### أنواع المحتوى

**نص** — رسالة عادية. مسموحة فقط ضمن نافذة 24 ساعة من آخر رسالة أرسلها العميل؛ خارج هذه النافذة استخدم قالبًا.

```json theme={null}
{ "channel": "whatsapp", "to": "+9665XXXXXXXX", "content": { "kind": "text", "body": "تم شحن طلبك!" } }
```

**قالب** — رسالة معتمدة مسبقًا للتواصل مع عميل خارج نافذة الـ 24 ساعة (راجع [القوالب](#القوالب) أدناه).

```json theme={null}
{
  "channel": "whatsapp",
  "to": "+9665XXXXXXXX",
  "content": { "kind": "template", "name": "order_update", "language": "ar", "variables": { "1": "12345" } }
}
```

**وسائط** — صورة أو مستند أو مقطع صوتي أو فيديو.

```json theme={null}
{
  "channel": "whatsapp",
  "to": "+9665XXXXXXXX",
  "content": {
    "kind": "media",
    "mediaType": "image",
    "url": "https://your-cdn.example/receipt.png",
    "contentType": "image/png",
    "sizeBytes": 84213,
    "filename": "receipt.png"
  }
}
```

<Info>
  الحقلان `contentType` و`sizeBytes` مطلوبان لإرسال الوسائط فعليًّا — يحتاج مزوّد واتساب الخاصّ بـ Wave كليهما معروفَين مسبقًا ولا يمكنه استنتاجهما من الرابط وحده. اجلب ترويسات الملفّ بنفسك (طلب `HEAD`) إن لم يكن نظامك يعرفهما مسبقًا.
</Info>

## القوالب

تُراجَع القوالب وتُعتمَد قبل استخدامها لبدء محادثة مع عميل.

**`GET /v1/messages/templates`** — سرد قوالبك وحالة اعتمادها (`pending` / `approved` / `rejected`).

**`POST /v1/messages/templates`** — إرسال قالب جديد.

| الحقل       | مطلوب                          | الوصف                                                                                                        |
| ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `name`      | ✅                              | اسم فريد للقالب.                                                                                             |
| `language`  | ✅                              | رمز اللغة التي كُتب بها القالب (`en`، `ar`، …).                                                              |
| `category`  | ✅                              | `UTILITY` أو `MARKETING` أو `AUTHENTICATION` — يؤثّر هذا في قواعد الاعتماد والتسعير معًا.                    |
| `body`      | مطلوب لـ `UTILITY`/`MARKETING` | نص القالب. استخدم `{{1}}`، `{{2}}`، … للمتغيّرات. يُتجاهل لفئة `AUTHENTICATION` — راجع أدناه.                |
| `variables` | —                              | قيم نموذجية لكلّ متغيّر، تُستخدم أثناء مراجعة الاعتماد. لا تُستخدم لفئة `AUTHENTICATION`.                    |
| `header`    | —                              | سطر رأس نصّي فقط. يُتجاهل لفئة `AUTHENTICATION`. رأس الوسائط (صورة/فيديو/مستند) غير مدعوم بعد.               |
| `footer`    | —                              | سطر تذييل نصّي فقط. يُتجاهل لفئة `AUTHENTICATION`.                                                           |
| `buttons`   | —                              | حتى 3 أزرار — راجع [الأزرار](#الأزرار) أدناه. تُتجاهل لفئة `AUTHENTICATION` (استخدم `otpButton` بدلًا منها). |
| `otpButton` | —                              | لقوالب `AUTHENTICATION` فقط — يضيف زرّ "نسخ الرمز" بلمسة واحدة.                                              |

<Note>
  لا يوجد نص مخصّص إطلاقًا لقالب `AUTHENTICATION` — تملك Meta صياغة رمز التحقق بالكامل، لذا يُتجاهل `body`/`variables`/`header`/`footer`/`buttons` لهذه الفئة. يضيف `otpButton` زرّ "نسخ الرمز" بلمسة واحدة دون أي نص لتخصيصه (تولّده Meta تلقائيًا).
</Note>

### الأزرار

كلّ عنصر في `buttons` هو أحد الأنواع الثلاثة التالية:

```json theme={null}
{ "type": "QUICK_REPLY", "text": "تتبّع الطلب" }
{ "type": "URL", "text": "عرض التفاصيل", "url": "https://your-site.example/orders/1" }
{ "type": "PHONE_NUMBER", "text": "اتصل بنا", "phoneNumber": "+9665XXXXXXXX" }
```

### عرض القالب وتعديله وحذفه

**`GET /v1/messages/templates/:name?language=en`** — التفاصيل الكاملة لقالب واحد (النص والرأس والتذييل والأزرار) — معامل الاستعلام `language` مطلوب لأنّ نفس الاسم يمكن أن يوجد بأكثر من لغة.

**`PUT /v1/messages/templates/:name?language=en`** — تحديث قالب موجود. يأخذ نفس نص الإنشاء؛ تعديل القالب يعيد إرساله للاعتماد، فتعود حالته إلى `pending`.

**`DELETE /v1/messages/templates/:name?language=en`** — حذف قالب نهائيًّا.

## أحداث حالة التسليم

اشترك فيها عبر [الـ webhooks](/ar/webhooks) بنفس طريقة أحداث المكالمات. يُدرَج `message.sent` للتوثيق الكامل لكنّه **لا** يُرسَل إلى الـ webhook الخاصّ بك — إنّه حدث الفوترة الداخليّ الخاصّ بـ Wave، يُنشأ لحظة قبول الإرسال.

| الحدث               | المعنى                                    | يُرسَل إلى الـ webhook؟    |
| ------------------- | ----------------------------------------- | -------------------------- |
| `message.sent`      | قُبلت للتسليم.                            | لا — حدث فوترة داخليّ فقط. |
| `message.received`  | ردّ عميل عليك.                            | نعم                        |
| `message.delivered` | وصلت الرسالة إلى جهاز العميل.             | نعم                        |
| `message.read`      | فتحها العميل.                             | نعم                        |
| `message.failed`    | فشل التسليم — راجع حقل `reason` في الحدث. | نعم                        |

```
queued ──▶ sent ──▶ delivered ──▶ read
                 └─▶ failed
```

## سجلّ الرسائل

تُسجَّل كلّ رسالة واتساب واردة وصادرة. اعرضها في صفحة **الرسائل** في لوحة التحكّم، أو استرجعها عبر **`GET /v1/messages`** (مُقسَّمة بالصفحات باستخدام cursor، بنفس شكل [سجلّات المكالمات](/ar/web-callback)).