دليل ربط واتساب للأعمال (Cloud API) بنظام رَبْع خطوة بخطوة 2026

واتساب API أم واتساب QR؟

يربط رَبْع واتساب بطريقتين:

• واتساب للأعمال عبر Cloud API (موضوع هذا الدليل): رقم رسمي للشركة يعمل من خوادم Meta، يستقبل عدداً غير محدود من المحادثات، ويرسل الحملات بقوالب معتمدة، ولا ينقطع إن أُغلق جوال. يحتاج إعداداً لمرة واحدة يستغرق عادة ساعة إلى ساعتين من العمل، إضافة إلى يوم أو يومين لمراجعات Meta.
• واتساب QR: يربط رقماً شخصياً لموظف بمسح رمز من الجوال خلال دقيقة. مناسب لرقم موظف واحد، لكنه يعتمد على بقاء الجوال متصلاً، ولا يصلح للحملات الكبيرة.

إن كان الرقم سيمثّل شركتك أمام العملاء فاختر Cloud API.

1. قبل أن تبدأ: جهّز هذه الأشياء

1. رقم جوال مخصص للشركة يستقبل رسالة نصية أو مكالمة لاستلام رمز التحقق. يجب ألا يكون مسجلاً على تطبيق واتساب أو واتساب للأعمال. إن كان مسجلاً فاحذف حساب واتساب منه أولاً من الجوال: الإعدادات ← الحساب ← حذف الحساب. حذف التطبيق وحده لا يكفي.
2. حساب فيسبوك شخصي لصاحب الشركة أو المسؤول التقني، مفعّل عليه التحقق بخطوتين، ليكون مسؤولاً عن حافظة الأعمال.
3. بيانات السجل التجاري: الاسم القانوني كما في السجل، ورقم السجل، والعنوان، وصورة السجل بصيغة PDF أو صورة واضحة.
4. بريد إلكتروني على نطاق موقع الشركة (مثل info@اسم-شركتك.com) إن أمكن؛ يسهّل التوثيق.
5. موقع إلكتروني فيه صفحة سياسة خصوصية؛ رابطها مطلوب لنشر التطبيق.
6. بطاقة دفع تقبل الدفع الدولي.
7. حساب في رَبْع بصلاحية مدير؛ ربط المصادر متاح للمدير فقط.

2. أنشئ حافظة الأعمال (Business Portfolio)

حافظة الأعمال هي الحاوية التي يجتمع فيها كل ما يخص شركتك عند Meta: التطبيق، وحساب واتساب للأعمال، والأرقام، والمستخدمون، ووسائل الدفع. إن كانت لشركتك حافظة يُدار منها إعلانات فيسبوك وإنستجرام فاستخدمها نفسها ولا تنشئ أخرى.

1. افتح business.facebook.com وسجّل الدخول بحسابك الشخصي.
2. من قائمة الحافظات أعلى يسار الصفحة اختر Create a business portfolio.
3. اكتب اسم الشركة كما يعرفه العملاء، واسمك، وبريد العمل، ثم اضغط Create.
4. افتح بريد العمل وأكّد العنوان من الرسالة التي تصلك من Meta.
5. ادخل Settings (إعدادات الأعمال) ثم Business info، وأكمل الاسم القانوني والعنوان والهاتف والموقع الإلكتروني مطابقة حرفياً للسجل التجاري؛ أي اختلاف يرفض التوثيق لاحقاً.

3. وثّق النشاط التجاري (Business Verification)

يمكنك البدء بدون توثيق، لكن الحافظة غير الموثقة تبدأ بحدّين ضيقين: رقمان فقط، ومراسلة 250 عميلاً مختلفاً كل 24 ساعة بالرسائل التي تبدأها الشركة. التوثيق يرفع الحدين إلى 20 رقماً و2,000 عميل، وهو شرط عملي لأي حملة.

1. من إعدادات الأعمال افتح Security Center واضغط Start verification. (قد يظهر الزر أيضاً في Business info.)
2. اختر الدولة: المملكة العربية السعودية، ثم اكتب الاسم القانوني ورقم السجل التجاري.
3. أكّد العنوان والهاتف والموقع الإلكتروني، ثم ارفع صورة السجل التجاري.
4. اختر طريقة تأكيد التواصل: رسالة على بريد النطاق، أو رسالة نصية، أو مكالمة، أو نطاق الموقع، وأدخل الرمز الذي يصلك.
5. أرسل الطلب. تستغرق المراجعة عادة يوماً إلى يومين عمل، وتصلك النتيجة في الإشعارات وعلى البريد.

لا تنتظر التوثيق؛ أكمل بقية الخطوات أثناء المراجعة.

4. أنشئ تطبيق Meta وأضف إليه واتساب

التطبيق هو «الهوية التقنية» التي تمرّ عبرها الرسائل بين Meta ورَبْع، وهو الذي يحمل رابط الـ Webhook.

1. افتح developers.facebook.com بالحساب نفسه. إن كانت أول مرة فاضغط Get Started وأكمل تسجيل المطوّر (رقم جوال للتأكيد).
2. من My Apps اضغط Create App.
3. اكتب اسماً للتطبيق (مثل: «واتساب الشركة — رَبْع») وبريد التواصل.
4. في شاشة حالة الاستخدام اختر Connect with customers through WhatsApp. (في الواجهة الأقدم: نوع التطبيق Business ثم أضف منتج WhatsApp بزر Set up.)
5. اختر حافظة الأعمال التي أنشأتها في الخطوة 2، ثم Create app.
6. ستنقلك Meta إلى صفحة API Setup وتطلب اختيار حساب واتساب للأعمال (WABA) أو إنشاءه. أنشئ حساباً جديداً باسم شركتك إن لم يكن لديك واحد.

تعرض صفحة API Setup «رقم اختبار» و«مفتاحاً مؤقتاً». هما للتجربة فقط: المفتاح المؤقت ينتهي خلال 24 ساعة، ورقم الاختبار لا يراسل إلا خمسة أرقام تضيفها يدوياً. لا تستخدمهما في رَبْع.

5. أضف رقم الشركة واختر الاسم الظاهر

1. في API Setup انزل إلى الخطوة الخاصة بإضافة رقم واضغط Add phone number.
2. املأ ملف واتساب للأعمال: الاسم الظاهر (Display name)، والفئة (مثل Real Estate)، والمنطقة الزمنية، ووصفاً مختصراً.
3. أدخل الرقم بمفتاح الدولة (+966) واختر طريقة استلام الرمز: رسالة نصية أو مكالمة.
4. أدخل الرمز المكوّن من ستة أرقام الذي يصلك. تظهر الآن حالة الرقم في WhatsApp Manager.

قواعد الاسم الظاهر

• يجب أن يرتبط باسم نشاطك كما في السجل أو الموقع؛ اسم عام مثل «عقارات» أو اسم شخص يُرفض.
• تجنب الرموز التعبيرية والحروف الكبيرة المتكررة وكلمات مثل «رسمي» أو «واتساب».
• تراجع Meta الاسم، والرسائل تعمل أثناء المراجعة. يمكن تغييره عشر مرات كحد أقصى في 30 يوماً، وبعد اعتماد اسم جديد يجب تسجيل الرقم من جديد خلال 14 يوماً (الخطوة 12).

6. أضف وسيلة الدفع

هذه الخطوة صارت إلزامية لكل حساب يتلقى رسائل كثيرة: منذ 1 أكتوبر 2026 تحتسب Meta رسائل خدمة العملاء بعد أول 1,000 رسالة مجانية شهرياً لكل رقم، وتتوقف هذه الرسائل عن الوصول إن لم توجد وسيلة دفع. ورسائل القوالب (التسويقية والخدمية والتحقق) مدفوعة دائماً.

1. افتح WhatsApp Manager من إعدادات الأعمال: Accounts ← WhatsApp accounts ← اختر الحساب ← WhatsApp Manager.
2. من القائمة افتح Billing (أو Payment settings) ثم Add payment method.
3. اختر الدولة والعملة بعناية؛ العملة لا تتغير بعد الحفظ.
4. أدخل بيانات البطاقة واحفظ.
5. تأكد أن البطاقة ظهرت فعلاً تحت Payment methods مرتبطة بحساب واتساب للأعمال، لا في حساب الإعلانات فقط.

7. أنشئ المفتاح الدائم من مستخدم النظام (System User)

رَبْع يتحدث مع Meta بمفتاح وصول (Access Token). المفتاح الذي يظهر في صفحة API Setup مؤقت وينتهي خلال يوم، فيتوقف الربط فجأة. المفتاح الصحيح يصدر عن مستخدم نظام: حساب تقني داخل الحافظة لا يرتبط بموظف، فلا يتعطل إن غادر الموظف الشركة أو غيّر كلمة مروره.

أ. أنشئ مستخدم النظام

1. افتح business.facebook.com ← Settings (إعدادات الأعمال).
2. من القائمة الجانبية: Users ← System users.
3. اضغط Add. إن ظهرت رسالة لقبول شروط مستخدمي النظام فاقبلها.
4. اكتب اسماً واضحاً، مثل raba-whatsapp، واختر الدور Admin، ثم Create system user.

ب. أسند إليه التطبيق وحساب الواتساب

هذه الخطوة يُنسى نصفها كثيراً، فيعمل المفتاح في بعض الطلبات ويفشل في غيرها.

1. اختر مستخدم النظام الذي أنشأته، ثم اضغط Assign assets.
2. اختر نوع الأصل Apps، وحدد تطبيقك من الخطوة 4، وفعّل Full control (أو Manage app)، ثم احفظ.
3. اضغط Assign assets مرة ثانية، واختر WhatsApp accounts، وحدد حساب واتساب للأعمال، وفعّل Full control (أو Manage WhatsApp Business accounts)، ثم احفظ.
4. تأكد أن الأصلين ظهرا معاً في صفحة مستخدم النظام تحت Assigned assets.

ج. ولّد المفتاح

1. في صفحة مستخدم النظام اضغط Generate new token (أو Generate token).
2. اختر التطبيق نفسه من القائمة.
3. في مدة الصلاحية اختر Never (لا ينتهي أبداً). إن اخترت 60 يوماً سيتوقف الربط بعد شهرين.
4. حدد هذه الصلاحيات الثلاث بالضبط:
   • whatsapp_business_messaging: لإرسال الرسائل واستقبالها.
   • whatsapp_business_management: للقوالب والأرقام وربط الحساب بالتطبيق.
   • business_management: لقراءة بيانات الحافظة.
5. اضغط Generate token.
6. انسخ المفتاح فوراً واحفظه في مدير كلمات مرور. Meta تعرضه مرة واحدة، وإن أغلقت النافذة قبل نسخه فولّد مفتاحاً جديداً. شكله سلسلة طويلة تبدأ عادة بـ EAA.

لا ترسل المفتاح في محادثة أو بريد أو لقطة شاشة، ولا تضغط Revoke عليه إلا إن أردت إيقاف الربط؛ الإلغاء فوري ولا يُتراجع عنه.

8. انسخ المعرّفين: Phone Number ID وWABA ID

المعرّفان أرقام طويلة، وليسا سرّين. ستحتاجهما مع المفتاح في رَبْع.

• Phone Number ID: من developers.facebook.com ← تطبيقك ← WhatsApp ← API Setup: اختر رقمك في خانة From، فيظهر تحته Phone number ID. انتبه: هذا ليس رقم الجوال نفسه.
• WhatsApp Business Account ID (WABA ID): في الصفحة نفسها تحت WhatsApp Business Account ID، أو من إعدادات الأعمال ← Accounts ← WhatsApp accounts، حيث يظهر المعرّف تحت اسم الحساب.

9. انشر التطبيق (Live)

التطبيق في وضع التطوير لا تصله بعض إشعارات Meta، فلا تصل رسائل العملاء إلى رَبْع.

1. من لوحة التطبيق افتح App settings ← Basic.
2. أدخل Privacy Policy URL (رابط سياسة الخصوصية في موقعك)، وTerms of Service URL إن وُجد، واختر الفئة، ثم Save changes.
3. بدّل App Mode أعلى اللوحة من Development إلى Live. في الواجهة الأحدث تجد ذلك في قسم Publish.

لا يحتاج تطبيقك إلى «مراجعة التطبيق» (App Review) ما دام يخدم حساب شركتك نفسها.

10. أضف المصدر في رَبْع والصق البيانات

أ. أنشئ مصدر واتساب

1. ادخل رَبْع بحساب مدير، وافتح مصادر العملاء: من القائمة التسويق والإعلان ← إعدادات مصادر التسويق ← بطاقة ربط الحسابات ← رابط «مصادر العملاء».
2. اضغط إضافة مصدر.
3. في نوع المصدر اختر واتساب (Cloud API)، واكتب الاسم الظاهر للمصدر داخل رَبْع (مثل «واتساب الشركة الرئيسي»).
4. اختر المسارات التي تظهر فيها محادثات هذا الرقم (المبيعات، خدمة العملاء، …)، والموظف الافتراضي، ومن يحق له رؤية محادثاته، ثم احفظ.

ب. اربطه بـ Meta

1. في بطاقة المصدر الجديد اضغط ربط API.
2. املأ الحقول:
   • Phone Number ID من الخطوة 8.
   • Permanent Access Token: المفتاح الذي نسخته في الخطوة 7.
   • WhatsApp Business Account ID من الخطوة 8.
   • Verify Token: كلمة سرية خاصة بشركتك، بالإنجليزية وبلا مسافات. اضغط توليد رمز عشوائي تحت الحقل ليكتبها رَبْع لك، ولا تنسخ مثالاً من أي دليل. احتفظ بها؛ ستكتبها في Meta في الخطوة التالية.
3. انسخ Webhook URL الظاهر في الصندوق الأصفر. شكله: https://اسم-شركتك.rabacrm.com/api/whatsapp/webhook.
4. اضغط حفظ الربط.

عند الحفظ يربط رَبْع حساب واتساب للأعمال بتطبيقك تلقائياً (الإجراء الذي تسميه Meta subscribed_apps). بدون هذا الإجراء تقبل Meta رابط الـ Webhook، ثم لا ترسل إليه أي رسالة؛ وهو أشهر سبب لعبارة «الربط ناجح لكن الرسائل لا تصل». ستظهر رسالة تؤكد الربط، أو تشرح سبب تعذّره.

11. أعدّ الـ Webhook في Meta

الـ Webhook هو العنوان الذي تُرسل إليه Meta كل رسالة يكتبها عميلك.

1. في developers.facebook.com افتح تطبيقك ← WhatsApp ← Configuration. (في التطبيقات المنشأة بحالة الاستخدام: Use cases ← Customize ← Configuration.)
2. في قسم Webhook اضغط Edit.
3. في Callback URL الصق رابط الـ Webhook من رَبْع.
4. في Verify token اكتب الكلمة السرية نفسها التي أدخلتها في رَبْع، حرفاً بحرف.
5. اضغط Verify and save. إن قبلت Meta الرابط فالخطوة نجحت؛ وإن ظهر خطأ فراجع تطابق الكلمة السرية وأنك حفظت الربط في رَبْع أولاً.
6. في قسم Webhook fields اضغط Manage، وفعّل Subscribe أمام الحقل messages، ثم Done. هذا الحقل يحمل رسائل العملاء، ويحمل أيضاً حالات التسليم والقراءة التي تعرضها تقارير الحملات.

12. سجّل الرقم برمز التحقق بخطوتين (إن لزم)

تشترط Meta تسجيل الرقم لاستخدامه مع Cloud API، وتطلب التسجيل مرة أخرى بعد اعتماد أي اسم ظاهر جديد. تعرف أنك تحتاجها إن لم تكن حالة الرقم Connected في WhatsApp Manager ← Phone numbers، أو إن أظهر اختبار الاتصال في رَبْع «الرقم مسجّل ومتصل» باللون الأحمر.

1. في رَبْع، داخل نافذة ربط API، اضغط اختبار الاتصال. إن احتاج الرقم تسجيلاً يظهر صندوق تسجيل الرقم في Cloud API.
2. أدخل رمز التحقق بخطوتين (6 أرقام). إن لم يكن للرقم رمز بعد، فالرمز الذي تكتبه يصبح رمزه، فاحفظه.
3. اضغط تسجيل الرقم. يعيد رَبْع الاختبار تلقائياً بعد النجاح.

تسمح Meta بعشر محاولات تسجيل كل 72 ساعة لكل رقم. إن نسيت الرمز فغيّره من WhatsApp Manager ← Phone numbers ← الرقم ← Settings ← Two-step verification.

13. اختبر الاتصال واقرأ قائمة الفحص

زر اختبار الاتصال في نافذة الربط يسأل Meta عن الرقم، ويعرض قائمة من تسع خطوات بلون لكل منها وما يجب فعله إن لم تكتمل:

14. أرسل أول رسالة وزامن القوالب

1. من جوال آخر أرسل «مرحبا» إلى رقم الشركة.
2. خلال ثوانٍ تظهر المحادثة في الصندوق الموحد بالمسار والموظف الذي حددته للمصدر. ردّ عليها من هناك وتأكد أن الرد وصل الجوال.
3. لإرسال الحملات: أنشئ القوالب في WhatsApp Manager ← Message templates ← Create template، وانتظر اعتمادها، ثم افتح صفحة الإرسال الجماعي في رَبْع واضغط مزامنة القوالب من Meta.

قاعدة الـ 24 ساعة: بعد آخر رسالة من العميل لديك 24 ساعة ترد فيها برسائل حرة. بعدها لا تُقبل إلا رسالة بقالب معتمد، وهذا ما تفعله الحملات تلقائياً.

15. حدود الإرسال والتكلفة

• الحد اليومي يُحسب بعدد العملاء المختلفين الذين تبدأ الشركة مراسلتهم بقالب خلال 24 ساعة، ويُشترك فيه على مستوى الحافظة كلها: 250 في البداية، ثم 2,000 بعد التوثيق أو بعد 2,000 رسالة مسلّمة بجودة عالية خلال 30 يوماً. بعدها يرتفع تلقائياً إلى 10,000 ثم 100,000 ثم بلا حد، ما دامت الجودة عالية واستخدمت نصف حدك خلال الأيام السبعة الماضية.
• الردود على العملاء داخل نافذة الـ 24 ساعة لا تخضع لهذا الحد.
• التكلفة لكل رسالة تُسلَّم، بحسب فئة القالب (تسويقي، خدمي، تحقق) ومفتاح دولة المستلم. رسائل خدمة العملاء مجانية حتى 1,000 رسالة شهرياً لكل رقم، ثم مدفوعة منذ 1 أكتوبر 2026. الأسعار الحالية في صفحة الأسعار لدى Meta، وتتغير دورياً.
• الرسائل الواردة من العملاء مجانية دائماً.

16. مشكلات شائعة وحلولها

17. حماية المفتاح

• رَبْع يحفظ المفتاح مشفّراً (AES-256)، ولا يعرضه مرة أخرى بعد الحفظ؛ لتغييره الصق مفتاحاً جديداً في «ربط API».
• اجعل مستخدم النظام خاصاً بهذا الربط وحده، فإن احتجت إيقافه ألغيت مفتاحه دون التأثير على غيره.
• عند مغادرة المسؤول التقني الشركة لا تحتاج تغيير شيء؛ المفتاح مرتبط بمستخدم النظام لا بشخص. لكن تأكد أن في الحافظة مسؤولاً آخر على الأقل.
• إن كان رقمك يعمل مع نظام آخر (مثل منصة محادثات)، يمكنك تشغيل الاثنين معاً: في نافذة «ربط API» الصق رابط النظام الآخر في «تمرير الرسائل لنظام آخر»، فيستقبل رَبْع الرسائل ويمرّر نسخة منها إليه.