خطافات الويب (webhook) في WhatsApp: توجيه الرسائل مباشرة إلى خادمك

ماذا ترسل Meta فعليًا إلى خطاف الويب؟

الأحداث تأتي ضمن فئات، والتمييز بينها يحدد بنية نظامك.

يحمل مسار الرسائل ما يرسله العملاء، وفي رقم Coexistence يحمل أيضًا نسخًا مما يرسله فريقك من تطبيق WhatsApp Business. وهذه هي الحقول messages وsmb_message_echoes، وهي التي تحتوي على محتوى المحادثات.

يحمل المسار التشغيلي كل ما عدا ذلك: الحدث account_update عند تغيّر حالة الاتصال، والحدث phone_number_quality_update عند تغيّر الجودة أو معدل الإرسال، إضافة إلى account_alerts وaccount_review_update وbusiness_capability_update وphone_number_name_update. لا تحتوي هذه الأحداث على محتوى المحادثات، ومنها تُبنى المراقبة.

المزود الذي يضع نفسه في مسار الرسائل يستقبل المجموعة الأولى، أما من لا يفعل ذلك فلا يستقبلها.

كيف تتحقق Meta من نقطة النهاية؟

ترسل طلب GET قبل أن تبدأ تسليم أي شيء، ويُعد الفشل في هذه الخطوة السبب الأكثر شيوعًا لعدم استقبال الرسائل رغم أن الإعداد يبدو مكتملًا.

تستدعي Meta عنوان URL الخاص بك مع ضبط hub.mode على subscribe، وإرسال hub.verify_token، وقيمة hub.challenge. يجب أن تعيد نقطة النهاية قيمة challenge هذه في نص الاستجابة الخام، من دون تغليفها في JSON أو إضافة أي شيء إليها. إذا لم تفعل، فلن تبدأ Meta التسليم، ولن يظهر ذلك في أي لوحة تحكم.

يجب أن تكون نقطة النهاية HTTPS أيضًا. نقطة النهاية التي تعيد 404 صامتًا، أو الموجودة خلف طبقة مصادقة ترفض Meta، تبدو مطابقة للإعداد العامل حتى لا تصل الرسالة الأولى.

هل يمكن أن تشير الوجهة إلى خادمك؟

نعم، وهذا هو الجزء الذي يختلف بين المزودين.

تتيح Meta للتطبيق تجاوز مكان تسليم خطافات الويب الخاصة بـ WhatsApp Business Account محدد. نضبط هذا التجاوز على عنوان URL الخاص بك، فتنقل أحداث مسار الرسائل من استدعائنا إلى استدعائك. ونحتفظ بالأحداث التشغيلية، لأن لوحة التحكم والتنبيهات مبنية عليها.

والنتيجة معمارية، وليست سياسة نعلنها. لا مكان لتخزين محتوى المحادثات من جانبنا، لأنه لا يُسلّم إلينا أصلًا. أما الحساب الذي لم يُضبط له تجاوز، فيعود إلى استدعائنا الافتراضي، حيث يتجاهل المعالج تلك الأحداث من دون حفظها.

ماذا يحدث للوجهة عند إعادة اتصال رقم؟

تُزال، وهذا هو الفشل الذي لا يخطط له أحد تقريبًا.

الوجهة ليست خاصية للرقم الهاتفي، بل تجاوز ضمن اشتراك تطبيقنا في WhatsApp Business Account. عند إزالة الاتصال، سواء بسبب قاعدة Meta الخاصة بعدم النشاط لمدة أربعة عشر يومًا أو لسبب آخر، يُلغى تثبيت التطبيق من ذلك الحساب، ويزول معه التجاوز.

تعيد إعادة الاتصال الإرسال والمراقبة، لكنها لا تعيد التسليم إلى خادمك، ولا يُبلّغ عن أي خطأ، لذلك تكون أول إشارة هي قول أحد العملاء إن أحدًا لم يرد عليه. نعيد تطبيق التجاوز عند كل إعادة اتصال، لأن هذا حدث فعلًا لرقم أعاد الاتصال بنجاح ثم توقف عن إرسال أي شيء.

الأخطاء الشائعة

• إرجاع JSON من طلب GET للتحقق. تريد Meta قيمة hub.challenge الخام فقط، ولا شيء غيرها.
• استخدام عنوان URL مؤقت أو تجريبي. تواصل Meta التسليم إليه بعد توقف الأداة التي أنشأته عن الاستماع.
• افتراض بقاء الوجهة بعد إعادة الاتصال. فهي مرتبطة باشتراك تطبيق وتُلغى معه.
• وضع نقطة النهاية خلف مصادقة ترفض طلب Meta.

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

تابع القراءة