# منصة WhatsApp Business: واجهة Cloud API والقوالب

> ترسل منصة WhatsApp Business الرسائل عبر Cloud API (المستضافة لدى Meta) أو عبر On-Premises API القديمة. يجب أن تستخدم الرسائل التي تبادر بها الشركة قوالب مُعتمَدة مسبقًا ضمن فئة (تسويق أو مرافق أو مصادقة)؛ ولا يُسمح برسائل الجلسة الحرّة إلا داخل نافذة خدمة عملاء مدّتها 24 ساعة تفتحها آخر رسالة للمستخدم. والموافقة المسبقة إلزامية.

- الرابط الأساسي: https://www.broadnet.me/ar/reference/whatsapp-business-cloud-api
- اللغة: ar
- آخر تحديث: 2026-07-18
- الناشر: BroadNet (https://www.broadnet.me)

كيف تعمل منصة WhatsApp Business: Cloud API مقابل On-Premises API، ورسائل القوالب (HSM) مقابل رسائل الجلسة، ونافذة خدمة العملاء ذات الـ 24 ساعة، وفئات التسويق/المرافق/المصادقة، وwebhooks، ومستويات جودة رقم الهاتف، والموافقة المسبقة.

## Cloud API مقابل On-Premises API

تعرض منصة WhatsApp Business واجهتَي برمجة لهما نموذج المراسلة نفسه لكن باستضافة مختلفة. Cloud API مُستضافة لدى Meta: تستدعي الشركة (أو مزوّد الحلول التابع لها) نقطة نهاية REST بأسلوب Graph مُرتكزة على معرّف رقم الهاتف، دون عميل محلّي يجب تشغيله. أما On-Premises API فهي عميل محتوى في حاوية تستضيفه الشركة بنفسها، وكان يُستخدم تاريخيًا لأسباب توطين البيانات أو الكمون؛ وقد خصّصته Meta للإيقاف لصالح Cloud API. وتخضع الواجهتان للقواعد نفسها — القوالب ونافذة الـ 24 ساعة والفئات والجودة والموافقة — فيكون الاختيار تشغيليًا (من يستضيف) لا وظيفيًا.

*Cloud API مقابل On-Premises API*

| الخاصية | Cloud API | On-Premises API |
|---|---|---|
| الاستضافة | مستضاف لدى Meta، لا حاجة لتشغيل عميل | عميل ضمن حاويات تستضيفه الشركة |
| نقطة النهاية | Graph REST على معرّف رقم الهاتف | نقطة نهاية REST للعميل المحلي |
| الترقيات | تتم إدارتها بواسطة Meta | تتولى الشركة صيانة إصدارات العميل |
| الحالة | موصى به، قيد التطوير النشط | مُحدَّد للإيقاف التدريجي |
| القواعد (القوالب/النافذة/الجودة) | متطابق | متطابق |

## رسائل القوالب (HSM) مقابل رسائل الجلسة

يفصل WhatsApp بين اتجاهَي المراسلة التجارية. لا تستطيع الشركة مراسلة مستخدم ابتداءً بمحتوى حرّ: فأي رسالة تبادر بها الشركة يجب أن تكون قالب رسالة — كان يُسمّى تاريخيًا رسالة عالية البنية (HSM) — قُدِّم إلى WhatsApp واعتُمِد سلفًا، بعناصر متغيّرة مُسمّاة وفئة مُعلَنة. وبمجرّد أن يردّ المستخدم، تُفتح نافذة خدمة عملاء مدّتها 24 ساعة يجوز فيها للشركة إرسال رسائل جلسة حرّة (نصّ أو وسائط أو تفاعلية) دون قالب. وخارج تلك النافذة، على الشركة أن تبدأ مجددًا بقالب مُعتمَد. وهذه القاعدة القائمة على القالب أولًا هي القيد الجوهري للمنصّة.

*Cloud API: إرسال قالب مرافق مُعتمَد*

```json
POST https://graph.facebook.com/v20.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "en_US" },
    "components": [
      { "type": "body",
        "parameters": [ { "type": "text", "text": "4021" } ] }
    ]
  }
}
```

## نافذة خدمة العملاء ذات الـ 24 ساعة

نافذة الـ 24 ساعة هي الآلية التي تحكم المراسلة الحرّة. تُفتح (أو يُعاد فتحها) كلما أرسل المستخدم رسالة إلى الشركة، وتدوم 24 ساعة من تلك الرسالة الأخيرة للمستخدم. وداخل النافذة يجوز للشركة الردّ بأي نوع رسالة مسموح — نصّ عادي أو وسائط أو أزرار أو قوائم تفاعلية — دون استخدام قالب. وعند إغلاق النافذة، تُرفض عمليات الإرسال الحرّة وعلى الشركة إعادة التواصل بقالب مُعتمَد (خاضع للفئة، وللتسويق حدود لكل مستخدم). ويرتكز كلٌّ من تسعير الجلسة والتسعير الأحدث لكل رسالة على ما إذا كان الإرسال يقع داخل هذه النافذة أو خارجها.

## فئات الرسائل: تسويق، مرافق، مصادقة

يُسنَد إلى كل قالب فئة تحكم كيفية استخدامه وتسعيره. تتعلّق قوالب المرافق بمعاملة أو حدث حساب متّفق عليه ومحدّد (تحديثات الطلبات، تذكيرات المواعيد، الكشوف). وتُسلّم قوالب المصادقة رموز تحقق لمرة واحدة والتحقّق، بصيغة مُقيّدة. أما قوالب التسويق فتحمل العروض الترويجية والصفقات وإعادة التفاعل، وهي الأشدّ حوكمةً — خاضعة لموافقة المستخدم وإشارات الجودة وحدود التكرار. ويراجع WhatsApp محتوى القالب مقابل الفئة المُعلَنة عند الاعتماد وقد يُعيد تصنيفه؛ وإرسال محتوى تسويقي تحت مسمّى مرافق سبب شائع للرفض أو الإضرار بالجودة.

*فئات قوالب WhatsApp*

| الفئة | الغرض | ملاحظات |
|---|---|---|
| الأداة | تحديثات المعاملات/الحساب التي يتوقعها المستخدم | مرتبط بإجراء أو اتفاق محدد |
| المصادقة | رموز تحقق لمرة واحدة، والتحقق | تنسيق مقيّد؛ يركّز على OTP |
| التسويق | العروض الترويجية، والعروض الخاصة، وإعادة التواصل | حوكمة صارمة للموافقة المسبقة (opt-in) والجودة والتكرار |
| الخدمة (الجلسة) | ردود حرة ضمن نافذة الـ 24 ساعة | لا يلزم قالب؛ ليست بمبادرة من الشركة |

## Webhooks: الرسائل الواردة وحالة التسليم

المنصّة غير متزامنة وقائمة على الاستدعاءات. تُهيّئ الشركة عنوان webhook يُرسل إليه WhatsApp نوعين من الأحداث: الرسائل الواردة (ردود المستخدم والوسائط ونقرات الأزرار والموقع) وإشعارات الحالة للرسائل الصادرة التي تتدرّج عبر sent وdelivered وread — وعند الفشل — failed برمز خطأ. وتظهر هنا إيصالات القراءة ودورة حياة الرسالة، ووصول حدث رسالة واردة هو تحديدًا ما يفتح نافذة الـ 24 ساعة أو يجدّدها. ويُقرّ التكامل المتين بالـ webhooks بسرعة ويوفّق بين حالة التسليم ومخزن رسائله الخاص، تمامًا كما توفّق منصّة SMS بين DLRs.

*webhook وارد: رسالة المستخدم تفتح نافذة الـ 24 ساعة*

```json
{
  "entry": [{ "changes": [{ "value": {
    "messaging_product": "whatsapp",
    "messages": [{
      "from": "15551234567", "id": "wamid.HBg...",
      "timestamp": "1752796800",
      "type": "text", "text": { "body": "Where is my order?" }
    }]
  } }] }]
}
```

## جودة رقم الهاتف والمستويات والموافقة

يحمل كل رقم هاتف تجاري تقييم جودة (يُعرض عاليًا/متوسطًا/منخفضًا، وغالبًا بألوان أخضر/أصفر/أحمر) مُشتقًّا من كيفية تفاعل المستخدمين مع رسائله — إذ تخفضه الحظورات والبلاغات. وتحكم الجودة مستوى حدّ المراسلة الذي يحدّ عدد المستخدمين الفريدين الذين يجوز للرقم بدء محادثات معهم خلال 24 ساعة متجدّدة؛ وتتصاعد المستويات (مثلًا 250 و1K و10K و100K ثم بلا حدّ) مع استمرار الجودة والحجم، وتتراجع إن انخفضت الجودة. وتحت كل ذلك تقع الموافقة المسبقة: إذ يشترط WhatsApp على الشركات الحصول على موافقة صريحة من المستخدم وتسجيلها، مجموعةً على أي قناة، قبل الإرسال. وتظهر ممارسة الموافقة الضعيفة سريعًا على شكل حظورات وجودة متدهورة ومستوى مكبوح.

*تقييم الجودة ومستويات المراسلة*

| Signal | المعنى | الأثر |
|---|---|---|
| الجودة: عالية (أخضر) | عدد قليل من عمليات الحظر/البلاغات | مؤهل للترقية إلى مستويات أعلى |
| الجودة: متوسطة (أصفر) | بعض التعليقات السلبية | قيد المراقبة؛ التوسع متوقف مؤقتًا |
| الجودة: منخفضة (أحمر) | عدد كبير من عمليات الحظر/البلاغات | خطر خفض المستوى أو الوسم |
| الفئة (250 / 1K / 10K / 100K / ∞) | المستخدمون الفريدون الذين بُدئت معهم محادثات كل 24 ساعة | يُرفع عند استدامة الجودة + الحجم |
| Opt-in | موافقة المستخدم المسجلة | مطلوب قبل أي إرسال تبدأه الشركة |

## الأسئلة الشائعة

### ما الفرق بين Cloud API وOn-Premises API؟

تستخدمان نموذج مراسلة WhatsApp نفسه، لكن Cloud API مُستضافة لدى Meta (تستدعي نقطة نهاية REST دون شيء تُشغّله)، بينما On-Premises API عميل في حاوية تستضيفه بنفسك. وقد خصّصت Meta واجهة On-Premises API للإيقاف لصالح Cloud API. وتنطبق القوالب ونافذة الـ 24 ساعة والفئات وقواعد الجودة على الواجهتين بالتساوي.

### ما هو قالب رسالة WhatsApp (HSM)؟

القالب — وهو تاريخيًا رسالة عالية البنية — محتوى مُعتمَد سلفًا بعناصر متغيّرة مُسمّاة وفئة مُعلَنة. وأي رسالة تبادر بها الشركة على WhatsApp يجب أن تكون قالبًا؛ ولا يُسمح بالمحتوى الحرّ إلا داخل نافذة خدمة العملاء ذات الـ 24 ساعة التي يفتحها ردّ المستخدم.

### ما هي نافذة خدمة العملاء ذات الـ 24 ساعة؟

هي المدّة التي تدوم 24 ساعة من آخر رسالة للمستخدم إلى الشركة، ويجوز خلالها للشركة إرسال رسائل جلسة حرّة دون قالب. وعند إغلاقها تُرفض عمليات الإرسال الحرّة وعلى الشركة إعادة التواصل بقالب مُعتمَد. وتفتح أحداث الـ webhook الواردة النافذة أو تجدّدها.

### ما هي فئات رسائل WhatsApp؟

تُصنَّف القوالب مرافق (تحديثات معاملة/حساب يتوقّعها المستخدم)، أو مصادقة (رموز تحقق لمرة واحدة وتحقّق)، أو تسويق (عروض وإعادة تفاعل، وهي الأشدّ حوكمةً). والردود الحرّة داخل النافذة رسائل خدمة. وتحكم الفئة الاستخدام المسموح والتسعير، ويراجع WhatsApp المحتوى مقابل الفئة المُعلَنة.

### ما الذي يحدّد حدّ المراسلة لرقم WhatsApp؟

يحدّ مستوى المراسلة عدد المستخدمين الفريدين الذين يستطيع الرقم بدء محادثات معهم خلال 24 ساعة متجدّدة (مثلًا 250 و1K و10K و100K ثم بلا حدّ). وترتفع المستويات مع استمرار الجودة والحجم وتنخفض إن تراجعت الجودة. والجودة تقييم عالٍ/متوسط/منخفض تحرّكه حظورات المستخدمين وبلاغاتهم.

### هل أحتاج إلى موافقة مسبقة لمراسلة المستخدمين على WhatsApp؟

نعم. يشترط WhatsApp موافقة صريحة ومسجّلة من المستخدم — يمكن جمعها على أي قناة — قبل أن تُرسل الشركة رسائل. وتظهر الموافقة الضعيفة سريعًا على شكل حظورات وبلاغات تخفض تقييم جودة الرقم وقد تكبح مستوى مراسلته أو تخفضه.

## المصادر

- [WhatsApp Business Platform — Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api)
- [WhatsApp — Message templates and categories](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)
- [WhatsApp — Per-message pricing and the 24-hour window](https://developers.facebook.com/docs/whatsapp/pricing)

## ذو صلة

- [WhatsApp Business API](https://www.broadnet.me/ar/products/whatsapp-business-api)
- [RCS vs SMS vs WhatsApp](https://www.broadnet.me/ar/reference/rcs-vs-sms-vs-whatsapp-channels)
- [بطاقات غنية ورسائل تفاعلية](https://www.broadnet.me/ar/reference/rich-cards-and-interactive-messaging)
- [التحويل الاحتياطي بين القنوات والتنسيق](https://www.broadnet.me/ar/reference/channel-fallback-and-orchestration)
- [متعدد القنوات](https://www.broadnet.me/ar/products/omnichannel)
- [المطورون](https://www.broadnet.me/ar/developers)