الدليل
اضبط رابط الاستقبال (Webhook)
رابط الاستقبال (Webhook) هو الطريقة التي تُبلغ بها Meta متجرك بما يحدث في حسابك: رسالة جديدة من عميل، أو رسالة وصلت أو قُرئت، أو قالب وافقت عليه Meta، أو تغيّر في حد الإرسال اليومي. في نهاية هذا الشرح ستصل كل هذه الأحداث إلى متجرك، وسيعرض «تشخيص الاتصال» آخر رسالة من عميل.
المزايا التي تحتاج إلى رابط الاستقبال
يمكنك إرسال الرسائل بدون رابط الاستقبال، لكن كل ما يصل من واتساب يحتاج إليه: صندوق الرسائل وإشعاراته، وعلامتا «وصلت» و«قُرئت» في تقارير الحملات، والأتمتة (لأنها تبدأ من رسالة العميل)، وكلمات الإيقاف، وضغطات العملاء على الأزرار، وتنبيهات Meta في «صحة الحساب».
انسخ رابط الاستقبال الخاص بمتجرك
يكون رابط الاستقبال لمتجرك عادةً بهذا الشكل، وفي أوله عنوان متجرك:
https://your-store.com/wp-json/almorshed-whatsapp/v1/webhookو«almorshed-whatsapp» هو الاسم التقني الأصلي للإضافة، وهي الإضافة نفسها. انسخ الرابط الدقيق من الإضافة، من أحد هذه الأماكن:
- WAPI Connect ← «لوحة التحكم»، في بطاقة «الإعداد» تحت «رابط الاستقبال (Webhook URL)»، مع زر «نسخ»
- WAPI Connect ← «الإعدادات» ← «ربط واتساب (API)»، تحت خانة «رمز التحقق لرابط الاستقبال (Verify Token)»
- «تشخيص الاتصال»، في خطوات الإعداد التي يعرضها حتى تصل أول رسالة من عميل
لا تتصل Meta إلا بروابط HTTPS. ويجب ألا تحجب أي إضافة حماية أو جدار حماية أو قاعدة في Cloudflare المسار /wp-json/. واضبط الروابط الدائمة في ووردبريس ← «الإعدادات» ← «الروابط الدائمة» (Permalinks) على أي خيار غير «عادي» (Plain). بذلك يظهر الرابط بالشكل الموضّح أعلاه، ويحتاج تطبيق صندوق الرسائل إلى هذا الضبط أيضاً.
الأسماء في هذا الشرح من شاشات Meta الإنجليزية يوم 17 أكتوبر 2026. إذا اختلف أحدها على شاشتك، فابحث عن أقرب زر إليه، فالخطوات نفسها لا تتغيّر.
خطوات ربط رابط الاستقبال
-
اختر رمز التحقق
افتح WAPI Connect ← «الإعدادات» ← «ربط واتساب (API)». في خانة «رمز التحقق لرابط الاستقبال (Verify Token)» اكتب أي كلمة سرية تختارها، مثل مزيج من الحروف والأرقام. ثم اضغط «حفظ الإعدادات» قبل أن تنتقل إلى Meta، لأن Meta تتحقق من الكلمة فوراً.
-
أضف المفتاح السري للتطبيق (App Secret) لحماية متجرك
في تطبيقك على Meta افتح «App settings» ← «Basic»، واضغط «Show» بجانب «App secret»، ثم انسخه. الصقه في خانة «App Secret» في الإضافة، واضغط «حفظ الإعدادات». عند حفظ المفتاح:
- تقبل الإضافة فقط طلبات رابط الاستقبال التي وقّعتها Meta، فلا يستطيع أحد إدخال رسائل مزيّفة إلى صندوق رسائلك
- تستطيع شاشة «المكالمات» فحص حقول Webhook في تطبيقك، وإضافة الحقل
callsنيابةً عنك - يمكنك استخدام خطوة الذكاء الاصطناعي في الأتمتة (باقة Business)، لأنها تحتاج إلى حفظ المفتاح السري للتطبيق أولاً
- يستطيع ضغط العميل على «تأكيد» أو «إلغاء» في رسالة الدفع عند الاستلام تغيير حالة الطلب، أما بدون المفتاح فلا يضيف الضغط إلا ملاحظة على الطلب
- تظهر تنبيهات Meta في «صحة الحساب» كاملة، أما بدون المفتاح فلا يبقى منها إلا ما تعرفه الإضافة، ويُكتب عليها «(لم يتم التحقق منه)»
انسخ المفتاح كما هو تماماً. إذا كان المفتاح غير صحيح، فلن تصل الرسائل ولا حالاتها، وسيعرض «تشخيص الاتصال» الرسالة «رُفضت طلبات حديثة من واتساب». ولحذف المفتاح، اكتب
-في الخانة، ثم احفظ. -
ضع رابط الاستقبال في تطبيقك على Meta
في developers.facebook.com افتح تطبيقك ← WhatsApp ← Configuration (في اللوحات الأحدث: «Use cases» ← «Customize» ← «Configuration»). ثم تحت «Webhook»:
- الصق رابط متجرك في «Callback URL»
- اكتب في «Verify token» الكلمة نفسها التي حفظتها في الإضافة
- اضغط «Verify and save»
ستتصل Meta الآن بمتجرك مرة واحدة لتتحقق من الكلمة. إذا فشل التحقق، فاطّلع على المشكلات الشائعة.
-
فعّل حقول Webhook
تحت «Webhook fields» (اضغط «Manage» إذا ظهر لك)، فعّل «Subscribe» للحقل
messages. هذا هو الحقل الوحيد الإلزامي. وفعّل أيضاً بقية الحقول في الجدول أدناه، فكل حقل منها يرسل بيانات تستخدمها الإضافة. -
اجعل حساب واتساب مشتركاً في التطبيق
لا ترسل Meta أحداث حساب واتساب إلا إلى التطبيقات المشترك فيها. ويحدث هذا الاشتراك غالباً عند إضافة رقمك، لكن ليس دائماً. افتح WAPI Connect ← «الحالة والأدوات» ← «تشخيص الاتصال»، وانظر إلى بطاقة الاشتراك:
- «الحساب مشترك في التطبيق» (باللون الأخضر): انتهيت.
- «لا ترسل Meta رسائل العملاء إلى أي تطبيق»: اضغط «الاشتراك الآن».
- «تُرسل رسائل العملاء إلى عنوان آخر»: حسابك يرسل رسائله إلى مكان آخر، مثل أداة كنت تستخدمها سابقاً. اضغط «تحويلها إلى هذا المتجر». ولكي يعمل هذا الزر، يجب أن يكون رمز التحقق محفوظاً.
-
حوّل تطبيقك إلى وضع Live
ما دام تطبيقك في وضع التطوير (Development)، قد تحجب Meta رسائل العملاء الحقيقيين، حتى لو وصلت حالات رسائلك. تأكّد أن صفحة «App settings» ← «Basic» فيها رابط سياسة الخصوصية لمتجرك في خانة «Privacy Policy URL». ثم افتح «Publish» في لوحة التطبيق (في اللوحات القديمة: غيّر «App Mode» في الأعلى من Development إلى Live). واملأ أي بيانات أخرى تطلبها Meta هناك، مثل التصنيف، أو أيقونة التطبيق، أو طريقة طلب حذف البيانات.
تطلب شروط Meta سياسة خصوصية منشورة لتطبيقك. وفي ووردبريس ← «الإعدادات» ← «الخصوصية» ← «دليل السياسة» (Policy Guide) تجد نصاً مقترحاً من الإضافة، وتجد تفاصيله في شرح الخصوصية والموافقة.
-
أرسل رسالة تجريبية
من جوال آخر، أرسل رسالة واتساب إلى رقم متجرك. ثم اضغط «إعادة الفحص» في «تشخيص الاتصال». سيعرض فحص «استقبال البيانات عبر Webhook» الآن «آخر رسالة من عميل: قبل …». وفي باقة Pro وما فوقها، تصل الرسالة أيضاً إلى تطبيق صندوق الرسائل.
كل حقول Webhook التي تستخدمها الإضافة
| الحقل | ما الذي ترسله Meta | أين تراه |
|---|---|---|
messages (إلزامي) | رسائل العملاء، وضغطات الأزرار، وحالات «أُرسلت» و«وصلت» و«قُرئت» و«فشلت» | صندوق الرسائل، وتقارير الطلبات والحملات، والأتمتة، وكلمات الإيقاف، و«تشخيص الاتصال» |
account_update | قبول حساب واتساب أو تقييده أو إيقافه، أو مخالفة لسياسات Meta | «صحة الحساب» ← «تنبيهات Meta» |
phone_number_quality_update | تصنيف رقمك بجودة منخفضة أو عودته إلى الوضع الطبيعي، وارتفاع حد الإرسال اليومي أو انخفاضه | «صحة الحساب» |
phone_number_name_update | نتيجة مراجعة الاسم الظاهر | «صحة الحساب» |
message_template_status_update | قبول قالب أو رفضه أو إيقافه مؤقتاً أو تعطيله أو إعادة تفعيله | شاشة «القوالب»، و«صحة الحساب»، والحملات (يوقفها القالب الموقوف) |
message_template_quality_update | تغيّر جودة قالب | شاشة «القوالب»، و«صحة الحساب» |
template_category_update | نقل Meta قالباً إلى فئة أخرى | شاشة «القوالب»، و«صحة الحساب» |
message_template_components_update | تغيّر نص قالب أو رأسه أو أزراره، مثلاً في WhatsApp Manager | شاشة «القوالب» |
business_capability_update | تغيّر حدود حسابك | «صحة الحساب» |
account_alerts | تنبيهات تصدرها Meta عن حسابك | «صحة الحساب» |
account_review_update | نتيجة مراجعة حسابك | «صحة الحساب» |
user_preferences | إيقاف عميل لرسائلك التسويقية أو إعادة تفعيلها من داخل واتساب | «جهات الاتصال» و«الحملات» (باقة Business): لا ترسل الحملات إلى العملاء الذين أوقفوها |
calls | مكالمات واتساب من العملاء: رنين المكالمة، وانتهاؤها، والمكالمات الفائتة | سجل المكالمات، وفقاعة المكالمة في المحادثة، وتنبيهات المكالمات الفائتة (من باقة Pro وما فوقها) |
account_settings_update (اختياري) | إعدادات المكالمات التي غيّرتها في WhatsApp Manager | تعرضها شاشة «المكالمات» فوراً |
وإذا كان أحد هذه الأحداث يستدعي انتباهك، مثل انخفاض الحد أو الجودة، أو تقييد الحساب، أو إيقاف قالب، فسيصلك أيضاً بالبريد الإلكتروني. ويصلك كذلك إشعار في تطبيق صندوق الرسائل (من باقة Pro وما فوقها). وتعرض «صحة الحساب» حقول الحساب التي تحتاج إليها تحت «طريقة استقبال تنبيهات Meta». ويفحص «تشخيص الاتصال» حقول القوالب الأربعة («تحديثات القوالب تصل»)، مع زر «تفعيلها» إذا كان تطبيقك يرسل رابط الاستقبال إلى هذا المتجر. وبالنسبة إلى المكالمات، توضّح لك شاشة WAPI Connect ← «المكالمات» هل الحقل calls مفعّل أم لا. وإذا كان المفتاح السري للتطبيق محفوظاً، وكان تطبيقك يرسل بيانات Webhook إلى هذا المتجر، فستعرض الشاشة زر «اشتراك التطبيق في «calls» نيابةً عني». تجد المزيد في شرح صحة الحساب وسجل المكالمات.
تأكّد من نجاح الخطوات
- يعرض «تشخيص الاتصال» «الحساب مشترك في التطبيق»، و«استقبال البيانات عبر Webhook» مع آخر رسالة من عميل.
- لا تظهر بطاقة «رُفضت طلبات حديثة من واتساب».
- يظهر تطبيقك بوضع Live في لوحة التطبيقات في Meta.
مشكلات شائعة وحلولها
تقول Meta إنها لم تتمكن من التحقق من Callback URL أو رمز التحقق
يجب أن تكون الكلمة في Meta مطابقة تماماً للكلمة في «رمز التحقق لرابط الاستقبال (Verify Token)»، وأن تكون محفوظة في الإضافة أولاً. ويجب أن يعمل موقعك على HTTPS، وألا يحجب أي شيء المسار /wp-json/. وتظهر كل محاولة فاشلة في «الحالة والأدوات» ← «سجل الرسائل» بهذا النص: «فشل التحقق من رابط الاستقبال (Webhook): رمز التحقق (Verify token) غير مطابق، أو الوضع (mode) غير صحيح.»
تصل حالات رسائلك، لكن رسائل العملاء لا تصل أبداً
فعّل الحقل messages، وحوّل تطبيقك إلى وضع Live. ثم أرسل رسالة تجريبية من جوال آخر.
لا يصل أي شيء
افتح «تشخيص الاتصال». غالباً يكون حساب واتساب غير مشترك في التطبيق (اضغط «الاشتراك الآن»)، أو تذهب رسائله إلى عنوان آخر (اضغط «تحويلها إلى هذا المتجر»). وإذا رأيت «رُفضت طلبات حديثة من واتساب»، فالمفتاح السري للتطبيق لا يطابق تطبيقك.
يقول «تشخيص الاتصال» إن الرسائل تصل إلى معرّف رقم هاتف (Phone Number ID) مختلف
يرسل تطبيقك إلى هذا المتجر رسائل رقم آخر. تحقّق من معرّف رقم الهاتف في «الإعدادات» ← «ربط واتساب (API)»، فيجب أن يكون معرّف الرقم الذي يستخدمه متجرك.
أداة أخرى تستخدم تطبيق Meta نفسه
للتطبيق رابط استقبال (Callback URL) واحد فقط. وزر «تحويلها إلى هذا المتجر» في «تشخيص الاتصال» يرسل إلى متجرك رسائل حساب واتساب الخاص بك فقط، ويترك رابط الاستقبال الأساسي للتطبيق كما هو. أما إذا كانت الأداة الأخرى تحتاج إلى حساب واتساب نفسه عبر التطبيق نفسه، فلن يستقبل رسائله إلا واحد منهما: متجرك أو تلك الأداة.
تقول «صحة الحساب» إنه لم يصل أي تنبيه
قد يكون هذا خبراً جيداً، وقد يعني أن الحقول غير مفعّلة. راجع القائمة أعلاه في WhatsApp ← Configuration ← Webhook fields.