عندما لا تصل رسالة واتساب، لا تبدأ بإعادة الإرسال. حدّد أولًا آخر حالة مؤكدة ومصدرها: في الطابور (queued) تعني أن منصتك لم تُكمل المحاولة، ومُرسلة (sent) أن خادم واتساب استلمها، ومُسلّمة (delivered) أنها وصلت إلى المستلم، ومقروءة (read) أن إشعار القراءة وصل، وفاشلة (failed) أن ميتا أبلغت بفشل. اربطها بمعرّف الرسالة وخطاف الويب قبل اختيار الحل.
الملخص التنفيذي
افصل حالة الطابور المحلية عن حالات ميتا الواردة عبر خطاف الويب.
احتفظ بمعرّف wamid من رد الإرسال واستخدمه لمطابقة كل تحديث لاحق.
شخّص من رمز الخطأ والتفاصيل الفعلية، لا من تخمين الموظف أو صمت العميل.
لا تعِد أخطاء السياسة أو القالب أو الصلاحيات قبل تصحيح السبب.
احمِ كل إعادة محاولة بمفتاح تطابق وسجل إرسال حتى لا تصل نسخة مكررة.
ماذا تعني queued وsent وdelivered وread وfailed؟
تسرد مرجعية ميتا الرسمية لحمولة خطاف الويب حالات sent وdelivered وread وfailed، وتربط كل تحديث بمعرّف الرسالة والمستلم والوقت. أما queued فليست حالة في هذه القائمة؛ إنها حالة داخلية تستخدمها المنصة أو عامل الحملة قبل أن تؤكد ميتا قبول الرسالة.
الحالة | مصدرها | ما الذي تثبته؟ | الإجراء التالي |
|---|---|---|---|
queued | المنصة أو طابور العمل | المهمة تنتظر أو تُجهّز | افحص العامل والحجز ولا تنشئ نسخة جديدة |
sent | خطاف ويب من ميتا | خادم واتساب استلم الرسالة | انتظر تحديث delivered أو failed |
delivered | خطاف ويب من ميتا | الرسالة سُلّمت للمستلم | لا تعِد الإرسال بسبب غياب read |
read | خطاف ويب من ميتا | وصل تحديث بأن الرسالة قُرئت | استخدمه كمؤشر تفاعل لا كشرط نجاح |
failed | خطاف ويب أو رد خطأ | فشل مؤكد مع بيانات خطأ | صنّف السبب ثم قرر التصحيح أو الإعادة |
توثّق إشعارات تحديث حالة الرسالة لدى ميتا أن ترتيب وصول الإشعارات إلى تطبيقك قد لا يعكس ترتيب وقوعها، ولذلك يجب قراءة timestamp وعدم السماح لتحديث sent متأخر بأن يخفض رسالة مسجلة بالفعل كـdelivered.
هل نجاح طلب الإرسال يعني أن العميل استلم الرسالة؟
لا. الاستجابة الناجحة من واجهة الرسائل تعيد عادة معرّفًا يبدأ بـwamid؛ هذا يثبت قبول الطلب وإنشاء معرّف للتتبع، لا التسليم إلى جهاز العميل. خزّن المعرّف مع الشركة والقناة والمستلم ومحاولة الإرسال، ثم انتظر أحداث الحالة المطابقة.
لا تعرض «وصلت» بمجرد حصولك على HTTP ناجح.
لا تنشئ رسالة محلية ثانية إذا تأخر خطاف الويب.
إذا غاب التحديث، افحص اشتراك WABA في webhooks وسجل استقبال endpoint قبل إعادة الإرسال.
إذا وصلت delivered ثم غابت read، فالتسليم نجح ولا يوجد سبب تقني لإرسال نسخة أخرى.
ما شجرة التشخيص الأسرع؟
السؤال | إذا كانت الإجابة نعم | إذا كانت الإجابة لا |
|---|---|---|
هل الحالة queued؟ | افحص عامل الطابور والحجز والمحاولة ووقت التنفيذ | انتقل إلى رد API |
هل رفض API الطلب؟ | سجّل code وtitle وdetails وصحح السبب | احفظ wamid وانتظر webhook |
هل وصل failed؟ | صنّف الخطأ المؤكد وحدد قابليته للإعادة | تحقق من مسار webhook لا من رقم العميل |
هل وصل sent فقط؟ | راقب تحديثًا لاحقًا وافحص تأخر الاستقبال | راجع هل خرج الطلب من الطابور أصلًا |
هل وصل delivered؟ | اعتبر التسليم ناجحًا | لا تدّع سببًا بلا خطأ |
هل وصل read؟ | سجّل القراءة | لا تحول غيابها إلى failed |
إذا كان الفشل يحدث قبل ميتا لكل الرسائل، راجع الاتصال والرمز والصلاحيات وهوية رقم الإرسال. وإذا كان يخص رسالة أو قالبًا بعينه، قارن الحمولة باللغة والمكونات والمتغيرات والحالة المعتمدة. وإذا كان يخص مستلمًا واحدًا، استخدم الخطأ الذي أعادته ميتا بدل اختبار احتمالات عشوائية.
ما الأخطاء التي يمكن تأكيدها دون تخمين؟
المرجع هو رد API أو مصفوفة errors داخل حالة failed. راجع دائمًا قائمة أخطاء WhatsApp Cloud API الرسمية وقت الحادث، لأن الوصف والإجراء قد يتغيران.
الدليل المؤكد | ما الذي تستطيع قوله؟ | ما الذي لا يجوز استنتاجه؟ |
|---|---|---|
131047 | الرسالة الحرة تجاوزت نافذة إعادة التفاعل | أن الحساب كله معطل |
131026 | تعذر توصيل الرسالة وفق رمز ميتا العام | أن العميل حظرك تحديدًا |
خطأ قالب صريح | الاسم أو اللغة أو المكونات أو المعلمات تحتاج تصحيحًا وفق التفاصيل | أن إعادة الطلب نفسه ستصلح المشكلة |
خطأ مصادقة أو صلاحية صريح | يجب إصلاح الرمز أو الصلاحية أو أصل ميتا المذكور | أن المشكلة مؤقتة تلقائيًا |
لا يوجد خطأ ولا webhook | لا توجد نتيجة مؤكدة بعد؛ افحص المراقبة والاشتراك | أن المستلم غير موجود أو أغلق هاتفه |
يمكنك قراءة شرح مستقل لخطأ 131047 وإغلاق نافذة واتساب. أما 131026 فابقه «تعذر التوصيل» ما لم تمنحك ميتا تفاصيل إضافية؛ حماية الخصوصية وجودة التشخيص أهم من إجابة واثقة غير مدعومة.
كيف تؤثر الموافقة والقالب ونافذة الـ24 ساعة؟
تطلب سياسة مراسلة واتساب للأعمال رقم هاتف العميل وموافقته على الرسائل اللاحقة، وتسمح بالرد دون قالب خلال 24 ساعة من آخر رسالة منه. خارج النافذة يجب استخدام قالب معتمد. هذه قواعد أهلية تسبق أي معالجة تقنية.
رسالة حرة خارج النافذة: لا تعِدها؛ انتقل إلى قالب صالح بعد التحقق من الموافقة.
قالب غير معتمد أو بلغة أو متغيرات لا تطابق الطلب: صحح الحمولة قبل أي محاولة.
طلب إيقاف أو غياب موافقة موثقة: أوقف الإرسال، ولا تصنف الحالة كعطل شبكة.
رد العميل بعد القالب: يفتح نافذة جديدة يمكن داخلها استخدام رسالة حرة مناسبة.
لرسم الحد الزمني بدقة، راجع دليل نافذة الـ24 ساعة بدل حسابها من آخر رسالة صادرة للشركة.
متى تعيد المحاولة ومتى تتوقف؟
نوع الحالة | قرار الإعادة | الضابط |
|---|---|---|
خطأ مؤقت صريح أو حد معدل | إعادة محدودة بتأخير متزايد | سقف للمحاولات ووقت انتهاء |
مهلة بعد إرسال غير محسوم | لا تعِد فورًا | صالح السجل ومعرّف الرسالة أولًا |
131047 أو نافذة مغلقة | لا تكرر الرسالة الحرة | قالب معتمد أو انتظار رسالة العميل |
قالب أو معلمات غير صحيحة | لا تعد الحمولة نفسها | صحح الاسم واللغة والقيم |
مصادقة أو صلاحيات | أوقف حتى الإصلاح | اختبر الرمز والأصل قبل استئناف الطابور |
delivered بلا read | لا إعادة | التسليم تحقق بالفعل |
131026 | لا إعادة عمياء | اتبع الإرشاد الرسمي والبيانات المتاحة |
إعادة المحاولة ليست زرًا عامًا لكل failed. يجب أن تصنف الأخطاء إلى مؤقتة ودائمة وغير محسومة، وأن تسجل سبب القرار. إعادة رسالة تسويقية غير مؤهلة عدة مرات قد تزيد الضرر ولا تقدم معلومة جديدة.
كيف تمنع التكرار باستخدام خطافات الويب والتطابق؟
خطاف الويب (webhook) هو سجل النتيجة، لكنه قد يصل متأخرًا أو بترتيب مختلف. صمم المعالجة لتكون متطابقة (idempotent): الحدث المكرر لا ينشئ رسالة أو حركة فوترة أو إشعارًا داخليًا جديدًا.
اربط كل حدث بمعرّف wamid والقناة والمستلم.
احفظ الحالة وtimestamp ورمز الخطأ والتفاصيل الخام اللازمة للتحقيق.
أنشئ مفتاحًا ثابتًا لمحاولة العمل، مثل الحملة والمستلم والقالب وإصدارها.
لا تسمح لحالة أقدم بأن تستبدل delivered أو read بحالة أقل تقدمًا.
أرسل استجابة سريعة للـwebhook ثم نفّذ المعالجة الثقيلة في طابور داخلي.
اجعل أمر الإعادة يختار السجلات القابلة للإعادة فقط، لا كل failed.
يوضح دليل خطافات الويب في تشغيل واتساب تصميم الاستقبال والمراقبة، بينما يفيد دليل ربط واتساب مع ميتا عند غياب الأحداث بسبب أصل أو اشتراك غير صحيح.
مثال تشغيلي افتراضي: حملة تحديث طلبات
هذا مثال افتراضي للتوضيح، وليس سجل عميل أو نتيجة أداء.
ينشئ متجر سعودي حملة تحديث لطلبات قائمة. تظهر دفعة من المستلمين queued في Wats؛ لا يعيد المشغل إنشاء الحملة، بل يراجع عامل الإرسال. تنتقل رسالة إلى sent ثم delivered، فتُعد ناجحة حتى لو لم تصل read. رسالة ثانية ترجع failed مع 131047 لأن مسارًا قديمًا حاول نصًا حرًا خارج النافذة؛ يوقفها الفريق ويستبدلها بقالب خدمي معتمد بعد التحقق من الموافقة.
رسالة ثالثة تعود بخطأ مؤقت صريح، فيعيدها النظام بعد تأخير وبعدد محدود. وقبل الإعادة يتحقق من سجل المحاولة حتى لا تكون ميتا قد قبلت الطلب قبل انقطاع الاتصال. النتيجة ليست «إعادة كل الأحمر»، بل قرار مختلف مبني على دليل كل رسالة.
كيف تعرض Wats هذه الحالات دون خلطها بميتا؟
في عمليات الحملات، يستخدم Wats حالات محلية مثل queued قبل الإرسال، ثم يسجل حالات sent وdelivered وread وfailed وأوقات المحاولات. كما تجمع شاشة تشخيص المستلمين أسباب الفشل في فئات تشغيلية وتتيح إعادة السجلات المصنفة قابلة للإعادة بدل إعادة كل حالات الفشل.
هذه الفئات تساعد التشغيل لكنها لا تستبدل رمز ميتا وتفاصيله الخام. عند التحقيق، ابدأ من الرسالة والمستلم والمحاولة ومعرّف Meta، ثم استخدم التصنيف لتجميع النمط لا لاختراع السبب.
الخلاصة: أثبت آخر حالة قبل اتخاذ الإجراء
الحد الأدنى الصحيح للتشخيص هو: حالة معروفة المصدر، ومعرّف رسالة، ورد API محفوظ، وخطاف ويب يعمل، وخطأ موثق عند الفشل، وقاعدة إعادة مرتبطة بنوع الخطأ. لا تحول صمت العميل إلى failed، ولا تحول sent إلى delivered، ولا تحول كل failed إلى محاولة جديدة.
ابدأ من أحدث دليل تستطيع إثباته، أصلح السبب مرة واحدة، ثم راقب الانتقال التالي. بهذه الطريقة تمنع الرسائل المكررة وتختصر التحقيق من سلسلة تخمينات إلى مسار قابل للمراجعة.
