رموز أخطاء WhatsApp Cloud API: معانيها وطرق إصلاحها

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

أين تظهر أخطاء WhatsApp Cloud API؟

تظهر الأخطاء في موضعين، ويجب التقاطها في الاثنين. أخطاء الطلب تعود فورًا في استجابة الـ API، وأخطاء التسليم تصل لاحقًا في webhook الحالة.

• الأخطاء المتزامنة. يُرفض طلب الإرسال وتحتوي الاستجابة على كائن error يضم code وmessage وtype وغالبًا error_data.details. من أمثلتها الرموز المميزة المنتهية الصلاحية والمعاملات الناقصة وعدم تطابق القوالب.
• الأخطاء غير المتزامنة. ينجح طلب الإرسال ويعيد معرّف رسالة، لكن webhook لاحقًا يبلّغ بـ status: failed مع مصفوفة errors. من أمثلتها نوافذ الخدمة المغلقة والمستلمون الذين يتعذّر الوصول إليهم والحدود التسويقية.

من الأخطاء الشائعة تسجيل استجابة HTTP وحدها. فيظن الفريق أن الحملة نجحت لأن كل طلب أعاد معرّف رسالة، بينما فشلت مئات الرسائل في webhooks. لمعرفة العلاقة بين الحالات، راجع شرح حالات sent وdelivered وread وfailed.

ما أكثر رموز أخطاء WhatsApp شيوعًا؟

يعرض الجدول الرموز التي يصادفها معظم الفرق، مجمّعة بحسب الخطوة التالية. الأوصاف صياغة بتصرف لمرجع Meta.

كيف تعالج الأخطاء المسؤولة عن معظم فشل الحملات؟

عمليًا، تتسبب حفنة من الرموز في معظم حالات الفشل. ولكل منها قاعدة قرار واضحة.

131047: نافذة الخدمة مغلقة

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

131026: الرسالة غير قابلة للتسليم

ابدأ بسلامة الأرقام: الصيغة الدولية، ورمز الدولة الصحيح، ودون صفر بادئ بعد الرمز. ثم تقبّل أن بعض الأرقام ببساطة ليست على WhatsApp، أو تعمل بإصدار قديم من التطبيق. وللرسائل الحساسة للوقت مثل OTP، انتقل إلى SMS. راجع WhatsApp مقابل SMS مقابل RCS.

131049 و131050: الحدود التسويقية وإلغاء الاشتراك

يؤثر الاثنان في الرسائل التسويقية. الرمز 131050 هو اختيار المستخدم الصريح بإيقاف الرسائل التسويقية؛ فاستبعده من الإرسال التسويقي واشترك في webhook تفضيلات المستخدم لدى Meta. أما 131049 فيعني أن Meta قررت عدم التسليم حمايةً لتفاعل المستخدمين؛ وتنصح Meta بالانتظار 24 ساعة على الأقل، وغالبًا ما تفشل المحاولات الأسرع من ذلك مجددًا. خفّض التكرار وحسّن الصلة بدلًا من إعادة الإرسال.

130429 و131048 و131056: الإرسال بسرعة أو بكمية أكبر من اللازم

الرمز 130429 يتعلق بسعة الإرسال: ضع الرسائل في قائمة انتظار وطبّق التراجع. و131056 على مستوى الزوج: أنت تراسل شخصًا واحدًا بكثرة. و131048 إشارة جودة على رقم المرسِل وتحتاج إلى إصلاح في المحتوى والاستهداف لا إلى إعادة محاولة. راجع حدود المراسلة وتقييم الجودة.

132000 و132001 و132012: عدم تطابق القوالب

هذه في الغالب أخطاء في التكامل. يجب أن يطابق اسم القالب ورمز اللغة (مثل ar مقابل en_US) وعدد المتغيرات ما اعتُمد تمامًا. ابنِ اختبارًا يرسل كل قالب بقيم تجريبية كلما عدّلته.

سياسة إعادة محاولة يمكنك تطبيقها

استخدم قائمة التحقق التالية لتصنيف كل فشل تلقائيًا.

1. سجّل الرمز والعنوان وerror_data.details ومعرّف الرسالة والمستلم واسم القالب.
2. لا تعد المحاولة أبدًا في 131050 و131021 و132016 و368 و131031. وأبلغ المسؤول فورًا بالرمزين 368 و131031.
3. أصلح ثم أعد المحاولة في أخطاء المصادقة (0 و190 و10) والمعاملات (131008 و131009 و135000) والقوالب (من 132000 إلى 132015) والفوترة (131042). ونبّه الفريق المسؤول.
4. تراجع ثم أعد المحاولة في 130429 و4 و80007 و131016 و131057 باستخدام تراجع أسّي بسقف أعلى.
5. غيّر القناة أو نوع الرسالة في 131047 (قالب) و131026 (SMS أو البريد الإلكتروني).
6. انتظر 24 ساعة أو أكثر في 131049 وراجع تكرار الحملات.
7. أبلغ عن حالات الفشل بحسب الرمز في تقارير الحملات، لا كإجمالي واحد لـ "failed".

مثال تطبيقي: حملة ترويجية فاشلة لمتجر في الرياض

هذا مثال افتراضي. ترسل "Najd Home" قالبًا تسويقيًا إلى 20,000 عميل وافقوا على تلقي الرسائل. يقبل الـ API كل الطلبات، لكن webhooks الحالة تُظهر نحو 1,400 حالة فشل.

بعد التجميع بحسب الرمز تتضح الصورة. أكبر مجموعة هي 131049، فيستبعد الفريق هؤلاء المستخدمين من الإرسالين التاليين ويخفّض التكرار الأسبوعي. مجموعة أصغر هي 131026؛ ويُظهر التحليل أن كثيرًا من الأرقام مخزّنة بصفر محلي في البداية، ويحلّ ذلك إصلاح للتوحيد القياسي للأرقام. ويُستبعد عدة مستخدمين من فئة 131050 من الإرسال التسويقي بشكل دائم. أما أخطاء 130429 القليلة فجاءت من دفعة الإرسال الأولى، فيُوزَّع الإرسال الآن عبر قائمة انتظار.

أخطاء شائعة وحدود صريحة

• معاملة كل فشل على أنه قابل لإعادة المحاولة. يهدر الإنفاق وقد يخفض الجودة.
• تثبيت نصوص Meta برمجيًا. تحدّث Meta العناوين والأوصاف؛ ابنِ المنطق على الرمز الرقمي واحتفظ بجدول مرجعي قابل للتحديث.
• تجاهل error_data.details. فهو كثيرًا ما يسمّي المعامل المعيب بدقة.
• ليس لكل فشل حل. بعض المستلمين لا يمكن الوصول إليهم عبر WhatsApp، ولا تشرح Meta كل قرار 131049. خطّط لقناة بديلة.

كيف تساعدك OmniChannels.ai

توفّر OmniChannels.ai، المدعومة من BroadNet Technologies، تقارير تسليم بعرضين موجز ومتقدم، مع عوامل تصفية وتصدير CSV، لتحليل الرسائل الفاشلة بحسب الحملة. ويمكن للتحويل بين القنوات إعادة الإرسال عبر RCS أو SMS عند فشل WhatsApp، وتُعاين القوالب على نموذج هاتف وتُتتبَّع حتى الاعتماد، مما يقلل أخطاء عدم التطابق. وتُبلغ webhooks عن حالتي FAILED وREJECTED بصيغة موحّدة واحدة، وتتضمن وثائق المطورين العامة مرجعًا لـ الأخطاء والحدود.