رسالة واجهة برمجة التطبيقات (API) لم تصل: الأسباب بالترتيب
الرسالة التي تقبلها WhatsApp API ليست رسالة مُسلَّمة بعد: تُبلغ Meta بنتيجتها لاحقًا في خطاف الويب (webhook) لحالة الرسالة، وهي sent أو delivered أو read أو failed، مع رمز خطأ. تحقق بالترتيب: حالة failed ورمزها، ونافذة الـ24 ساعة (131047)، وطريقة الدفع (131042)، والقالب (132001، 132015)، والمستلم (131026، 131049، 131050)، ثم حدود الرقم واتصاله.
يراقب easyCoexistence كل رقم متصل على مدار الساعة، ويرسل إليك بريدًا إلكترونيًا عندما تتوقف Meta عن التسليم، أو يُفصل الربط، أو تنخفض الجودة، ويعيد توجيه إشعارات حالة Meta كما هي إلى نظامك.
sent (علامة صح واحدة)، delivered (علامتان)، read (علامتان زرقاوان) و failed (مثلث خطأ أحمر)، كما تُبلغ بها إشعارات الحالة.
مرّت أكثر من 24 ساعة منذ آخر رد من المستلم، وتنصح Meta بإرسال قالب بدلًا من ذلك.
تعذّر التسليم: الرقم ليس على WhatsApp، أو لم يقبل المستلم الشروط الجديدة، أو يستخدم نسخة قديمة من WhatsApp.
المدة الافتراضية التي يعيد فيها WhatsApp محاولة تسليم قالب المنفعة أو التسويق غير المسلَّم قبل إسقاطه، ومدة قوالب المصادقة الافتراضية 10 دقائق.
سعة إرسال ثابتة لرقم يُستخدم في تطبيق WhatsApp Business وفي Cloud API معًا.
لماذا لا تصل رسالة قُبلت؟
لأن ردّ الواجهة والتسليم حدثان منفصلان. عند الإرسال، تعيد Meta معرّف الرسالة فور قبول الطلب، أما وصولها إلى هاتف العميل فيأتي لاحقًا في webhook على حقل messages. تعني sent أنها غادرت خوادم Meta (علامة صح واحدة)، وتعني delivered أنها وصلت إلى الجهاز (علامتان)، وتعني read أنها فُتحت (علامتان زرقاوان)، وتعني failed أنها تعذّر إرسالها أو تسليمها، ويظهر ذلك لك في مصفوفة errors: الرمز والعنوان وerror_data.details. لذلك لا تخمّن أبدًا: ابحث عن حالة failed لمعرّف الرسالة واقرأ رمزها. إن لم تكن لديك وجهة لـ webhook فلا يُسجَّل شيء.
ما الأسباب بالترتيب الذي تفحصها به؟
من الأكثر شيوعًا على رقم متصل حديثًا إلى الأندر. كل سطر يذكر رمز Meta، فتعرف من حالة failed في أي حالة أنت:
- نافذة مغلقة: 131047، أي أكثر من 24 ساعة منذ آخر رسالة كتبها العميل. الرسائل الحرة تحتاج نافذة مفتوحة، فأرسل قالبًا.
- الدفع: 131042، أو إسقاط القوالب بصمت. منذ 1 أكتوبر 2026 تتوقف أيضًا رسائل الخدمة بعد استخدام 1,000 رسالة شهريًا دون طريقة دفع.
- القالب: 132001 غير معتمد أو بلغة خاطئة، 132000 عدد متغيرات خاطئ، 132012 تنسيق خاطئ، 132015 متوقف مؤقتًا، 132016 معطّل.
- المستلم: 131026 ليس على WhatsApp أو يستخدم نسخة قديمة أو لم يقبل الشروط؛ 131050 أوقف رسائل التسويق؛ 131049 حُجزت للحفاظ على تفاعل صحي؛ قوالب التسويق إلى أرقام الولايات المتحدة لا تُسلَّم.
- الحدود: 131048 مقيّد بسبب إشارات الرسائل المزعجة، 131056 رسائل كثيرة إلى شخص واحد، 130429 معدل الإرسال، و20 رسالة في الثانية على رقم Coexistence.
- الحساب: 131031 أو 368، حساب WhatsApp Business مقيّد أو معطّل بسبب مخالفة للسياسات.
- الربط: الرقم لم يعد مرتبطًا، مثلًا بعد 14 يومًا دون فتح تطبيق WhatsApp Business.
كيف تتعامل مع الرموز المتعلقة بالمستلم؟
بشكل مختلف، لأن بعضها يستحق إعادة المحاولة وبعضها لا يستحقها أبدًا. يعني 131050 أن الشخص اختار إيقاف رسائل التسويق منك: تنصح Meta بعدم إعادة المحاولة، ويخبرك webhook من نوع user_preferences عندما يتوقفون أو يستأنفون. أما 131049 فهو حجب من Meta لرسالة تسويق للحفاظ على تفاعل صحي، غالبًا بسبب حد لكل مستخدم على قوالب التسويق: تنصح Meta بالانتظار 24 ساعة على الأقل قبل إعادة الإرسال، لأن الإرسال المبكر يعيد الخطأ نفسه فقط. ويغطي 131026 الأرقام غير المسجلة على WhatsApp، والمستخدمين الذين لم يقبلوا شروط WhatsApp الحالية، والنسخ القديمة جدًا من التطبيق: تحقق أولًا من تنسيق الرقم ورمز الدولة، ثم تواصل مع العميل عبر قناة أخرى.
إلى متى يحاول WhatsApp التسليم؟
طوال مدة صلاحية الرسالة (time to live). عندما يكون الهاتف مطفأً أو خارج التغطية، يعيد WhatsApp المحاولة بدلًا من الفشل فورًا: افتراضيًا لمدة 30 يومًا لقوالب المنفعة والتسويق، و10 دقائق لقوالب المصادقة. ويمكن للنشاط التجاري تقصيرها لكل قالب عبر message_send_ttl_seconds، من 30 ثانية إلى 12 ساعة لقوالب المنفعة، ومن 30 ثانية إلى 15 دقيقة لقوالب المصادقة. الرسالة التي لا تُسلَّم خلال مدة صلاحيتها تُسقَط. لذلك فالرسالة ذات الحالة sent دون delivered بعد ساعات تكون غالبًا بانتظار هاتف العميل لا مفقودة، فاضبط مدة قصيرة على رموز التحقق والتنبيهات الحساسة للوقت حتى لا يربك التسليم المتأخر أحدًا.
ماذا يعني هذا للردود الآلية والأتمتة؟
اقرأ التشغيل أولًا، ثم الحالة. في علامة التبويب Runs، يعني تشغيل «متخطى» أنه لم يرسل شيئًا ويذكر السبب: «أكثر من 24 ساعة منذ آخر رسالة من العميل»، أو «رددت على هذه المحادثة من هاتفك مؤخرًا»، أو «بلغ حد الردود بالذكاء الاصطناعي لهذه المحادثة في هذه الساعة». ويعني تشغيل «مكتمل» أن Meta قبلت كل رد، وهذا ليس دليلًا على التسليم. لا يخزّن easyCoexistence حالات الرسائل: مع تفعيل الأتمتة تصل إلى عنوان URL لإعادة التوجيه الذي تحدده، وفي الوضع المباشر تذهب مباشرة إلى نقطة النهاية (endpoint) الخاصة بك. ومن ChatGPT أو Claude، اطلب من ذكائك الاصطناعي تشغيل get_number_health، فهو يُعيد الحالة المباشرة وتصنيف الجودة وآخر 15 حدث مراقبة، بما في ذلك كتلة sending التي تتضمن رمز الخطأ الصادر عن Meta.
كيفية إعداده
- Find the statusLook up the message id in your webhook log and read the latest status: delivered, read, sent only, or failed with an error code.
- Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
- Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
- Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
- Check the numberAsk your AI to run get_number_health, or open the number in the dashboard, to see the connection and any sending block.
الأخطاء الشائعة
- إعادة المحاولة عند 131050. الشخص أوقف رسائل التسويق منك، والمحاولات الإضافية لا تُسلَّم أبدًا، وقد تضيف إشارات سلبية فقط.
- اعتبار معرّف الرسالة دليلًا على التسليم. تقبل Meta الطلب أولًا وتُبلغ بالفشل لاحقًا، فسير العمل الذي يتوقف عند المعرّف يفوّت كل رسالة رُفضت.
- إرسال رد حر بعد يوم. بعد 24 ساعة دون رسالة من العميل تُقبل القوالب فقط.
- التشغيل دون وجهة لـ webhook. تصل حالات الفشل عبر webhook فقط، فبدونها يضيع سبب عدم وصول الرسالة.
يمكن لذكائك الاصطناعي فحص الرقم من ChatGPT أو Claude عبر get_number_health. من US$ 9 إلى US$ 0.75 للرقم الواحد شهريًا، ويتناقص السعر كلما أضفت أرقامًا، مع فترة تجريبية مجانية لأول 3 أيام.
الأسئلة الشائعة
لماذا ظلت الرسالة تظهر علامة صح واحدة لساعات؟
علامة الصح الواحدة تعني حالة sent: أرسلتها Meta، لكن الهاتف لم يستلمها، غالبًا لأنه مطفأ أو غير متصل. يواصل WhatsApp المحاولة حتى تنتهي مدة صلاحية القالب، وهي 30 يومًا افتراضيًا لقوالب المنفعة والتسويق.
لماذا تصل الردود بينما لا تصل القوالب؟
غالبًا تكون المشكلة في طريقة الدفع على حساب WhatsApp Business. تُسلّم Meta رسائل الخدمة ضمن الشريحة المجانية الشهرية للرقم دون طريقة دفع، لكنها لا تُسلّم القوالب. أضف بطاقة من صفحة «Billing & payments».
هل يمكنني رؤية الرسائل الفاشلة في تطبيق WhatsApp Business؟
ليس بشكل موثوق. على رقم Coexistence تظهر الرسائل المرسلة عبر API في خيط المحادثة داخل التطبيق، لكن سبب فشل الرسالة يأتي فقط في رمز الخطأ ضمن إشعار الحالة عبر webhook.
هل تفرض Meta رسومًا على الرسائل التي لم تُسلَّم؟
لا. تفرض Meta رسومًا على الرسائل المُسلَّمة فقط، ولا تُحتسب كذلك محاولات القالب الموقوف مؤقتًا.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في