واتساب

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

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

إرسال رسالة

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 ساعة من آخر رسالة أرسلها العميل؛ خارج هذه النافذة استخدم قالبًا.

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

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

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

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

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

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

القوالب

تُراجَع القوالب وتُعتمَد قبل استخدامها لبدء محادثة مع عميل. 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` فقط — يضيف زرّ “نسخ الرمز” بلمسة واحدة.

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

الأزرار

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

{ "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 بنفس طريقة أحداث المكالمات. يُدرَج 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، بنفس شكل سجلّات المكالمات).

البدء

الصوت

Web Callback

المرجع

واتساب

إرسال رسالة

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

القوالب

الأزرار

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

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

سجلّ الرسائل

​إرسال رسالة

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

​القوالب

​الأزرار

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

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

​سجلّ الرسائل

إرسال رسالة

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

القوالب

الأزرار

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

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

سجلّ الرسائل