تسجيل الدخولابدأ الفترة التجريبية المجانية
Meta Tech Provider

لماذا فشلت رسالة WhatsApp؟ قراءة حالة failed والأخطاء المرتبطة بها

يعني خطاف الويب (webhook) بحالة failed أن Meta لم تتمكن من إرسال رسالة أرسلها النشاط التجاري عبر واجهة برمجة التطبيقات (API) أو من تسليمها. تصل الحالة عبر الحقل messages بقيمة status تساوي failed، ومعها مصفوفة errors تحتوي على code وtitle وmessage وerror_data.details وhref. ويحدد الرمز السبب: 131047 نافذة مغلقة، 131026 رسالة غير قابلة للتسليم، 131049 حد التسويق، 131050 توقف التسويق، 131042 مشكلة في الدفع.

يربط easyCoexistence رقم تطبيق WhatsApp Business بـCloud API من Meta عبر Coexistence، ويمرّر حالات failed إلى خادمك مباشرة، أو عبر إعادة توجيه موقّعة عند تفعيل الأتمتة.

131047

مرّت أكثر من 24 ساعة على آخر رد من المستلم، وما تقترحه Meta هو إرسال قالب بدلًا من ذلك.

131049

لم تُسلَّم حفاظًا على سلامة تفاعل المنظومة، لذا انتظر 24 ساعة على الأقل قبل إعادة إرسال قالب التسويق.

131050

اختار المستلم إيقاف رسائل التسويق من النشاط التجاري، وتقول Meta ألا تُعاد المحاولة.

No contacts

تحذف حالة failed مصفوفة contacts، لذا اربط الفشل عبر statuses.id.

Delivered

تُفرض رسوم Meta على الرسائل عند تسليمها، لا عند إرسالها.

كيف تبدو حالة failed؟

مثل أي حالة، مع إضافة errors. تغيب مصفوفة contacts، ويُحذف recipient_user_id عندما أُرسلت الرسالة إلى رقم هاتف، ولا يوجد كائن pricing. يحمل title وmessage النص نفسه، ويشرح error_data.details الخطأ في جملة، ويشير href إلى قائمة رموز الخطأ لدى Meta. هذا مثال من Meta نفسها، لقالب تسويق أُوقف بسبب الحد لكل مستخدم:

Meta's example: a message that failed with 131049
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

ما رموز الخطأ الأكثر تكرارًا، وما معناها؟

تعيد Meta الأخطاء في استجابة الإرسال، أو في حالة failed، أو في الاثنتين، لذلك قد يصلك الرمز نفسه بأي من الطريقتين، ويجب أن يقرأ معالِج الاستقبال لديك المكانين. هذه الرموز تفسّر معظم الرسائل التي لا تصل، مع سبب Meta ومع أول ما يُجرَّب، أما القائمة الكاملة فهي في مرجع رموز الخطأ لدى Meta:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

كيف ينبغي لمعالِج الاستقبال أن يتصرف مع كل نوع فشل؟

صنّف الرمز إلى الخطوة التالية قبل أي إعادة محاولة. إعادة المحاولة الشاملة تحوّل إيقاف التسويق إلى فشل متكرر وقد تطيل الحظر، بينما إسقاط الخطأ المؤقت يفقد رسالة كانت ستصل بعد دقيقة.

  • أعد المحاولة مع تأخير متزايد: 131000 غير معروف، 131016 الخدمة غير متاحة، 130429 بلغ معدل الإرسال الحد.
  • انتظر أولًا: 131049، لمدة 24 ساعة على الأقل، لأن المحاولات المبكرة قد تحجب ذلك المستخدم لمدة تصل إلى 24 ساعة إضافية.
  • بدّل الرسالة: 131047 يتطلب قالبًا معتمدًا، لأن نافذة الـ24 ساعة مغلقة.
  • أوقف الإرسال لهذا العميل: 131050، حتى يصل إشعار resume عبر user_preferences.
  • أصلح الحساب أو المحتوى: 131042 الدفع، 131031 الحساب مقيّد، 131053 الوسائط.

أي الأخطاء تظهر فقط كحالة failed؟

تلك التي تقررها Meta بعد قبول الطلب. ترجع عملية الإرسال wamid، ويأتي الرفض لاحقًا عبر هذا الـwebhook. لا تسلّم Meta قوالب التسويق إلى مستخدمي WhatsApp الذين يملكون أرقام هاتف أمريكية (+1 مع رمز منطقة أمريكي)، وقالب التسويق المرسل إلى عميل أوقف رسائل التسويق يُعالَج ثم يُبلَّغ عنه كفشل بالرمز 131050، وحد التسويق لكل مستخدم يُبلغ عن 131049 بالطريقة نفسها.

إذا لم يكن للرقم وجهة webhook، فلن تظهر هذه الإخفاقات في أي مكان يمكنك رؤيته، وتبدو الرسالة كأنها أُرسلت. للاطلاع على الترتيب الكامل للفحوص عندما لا يتلقى عميل شيئًا، راجع صفحة رسائل WhatsApp API التي لم تُسلَّم.

ما الذي يتغير على رقم Coexistence؟

أمران مهمان. أولًا، تنطبق نافذة الـ24 ساعة على API وحدها. يقول دليل Meta الخاص بـCoexistence إن الرسائل المرسلة من تطبيق WhatsApp Business لا تخضع لنافذة خدمة العملاء، لذلك بعد 131047 يستطيع المالك الرد على ذلك العميل من هاتفه، بينما يرسل نظامك قالبًا معتمدًا.

ثانيًا، معدل الإرسال ثابت. الرقم المستخدم في التطبيق وفي API معًا يرسل 20 رسالة في الثانية كحد أقصى، وتجاوز ذلك يعيد 130429. وكل ما عدا ذلك يُقرأ كما في أي رقم Cloud API: الحقل نفسه، ومصفوفة errors نفسها، والرموز نفسها.

كيف ترى الأتمتة والذكاء الاصطناعي الفشل؟

يتوقف الأمر على الوقت الذي تقول فيه Meta لا. الرفض عند الإرسال، مثل 131047، يُفشل خطوة الأتمتة: تظهر الجولة بحالة Failed مع رسالة Meta في تبويب Runs، ويتلقى المالك بريدًا إلكترونيًا ليرد على ذلك العميل بنفسه. وتتحقق الأتمتات أيضًا من النافذة قبل إرسال رد حر، فتتخطى الخطوة بالحالة window_closed بدلًا من المحاولة.

أما الفشل الذي تبلّغ عنه Meta لاحقًا، فيصل كحالة failed إلى Forward URL الخاص بك أو إلى الوجهة المباشرة، وتبقى الجولة كما هي. ويرى الذكاء الاصطناعي الذي أرسل قالبًا عبر موصل MCP الـwamid و"sent: true"؛ اطلب من نظامك حالة ذلك الـwamid، أو اطلب من المساعد تشغيل get_number_health عندما تفشل رسائل كثيرة دفعة واحدة.

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

  • إعادة المحاولة بالرمز 131050 في حلقة مستمرة. أوقف العميل رسائل التسويق، لذلك يفشل كل محاولة بالطريقة نفسها حتى يستأنف تلقي الرسائل.
  • إعادة إرسال قالب تسويق بالرمز 131049 خلال ساعات. تطلب Meta 24 ساعة على الأقل، وقد تحجب المحاولات المبكرة ذلك المستخدم لمدة تصل إلى 24 ساعة إضافية.
  • الاكتفاء بتسجيل title وحده. يحمل error_data.details السبب المحدد، لذلك خزّن code والتفاصيل معًا مع wamid.
  • العمل بلا وجهة webhook والحكم على التسليم من استجابة الإرسال، وهي تقول فقط إن Meta قبلت الرسالة.
إنجاز ذلك باستخدام EasyCoexistence

وعندما يُرفض رد أتمتة عند الإرسال، تعرض الجولة خطأ Meta ويصلك بريد إلكتروني، وتُراقب كل الأرقام على مدار 24/7 لرصد الانقطاعات وتراجع الجودة. US$ 9 إلى US$ 0.75 لكل رقم شهريًا، ويتناقص السعر كلما أضفت أرقامًا، مع فترة تجريبية مجانية مدتها 3 أيام.

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

هل تُفرض رسوم على الرسالة الفاشلة من Meta؟

تقول صفحات تسعير Meta إنها تفرض رسومًا على الرسائل المُسلَّمة، لا على الرسائل المُرسَلة فقط. لا تحمل حالة failed أي كائن pricing. تذهب الرسوم إلى حساب WhatsApp Business الخاص بالنشاط التجاري، ولا يضيف easyCoexistence إليها أي هامش أبدًا.

هل يعني الرمز 131026 أن العميل حظر النشاط التجاري؟

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

لماذا يظهر recipient_user_id في بعض حالات الفشل ولا يظهر في غيرها؟

تحذفه Meta من حالة failed عندما أُرسلت الرسالة إلى رقم هاتف. وعندما ترسل إلى BSUID الخاص بالعميل، يتضمنه الفشل، وقد يكون recipient_id هو الغائب.

هل يمكن أن تفشل رسالة بعد تسليمها؟

يصف مرجع Meta الحالة failed بأنها فشل في الإرسال أو في التسليم. بمجرد أن تصل الرسالة إلى الجهاز، فإن الحالات التالية المتوقعة هي read، أو played بالنسبة للرسائل الصوتية.

تابع القراءة

حالات خطاف الويب (webhook) في WhatsApp: مرسلة ومسلمة ومقروءة وفاشلةكيف يبلغ WhatsApp بما حدث لرسالة أرسلتها: مصفوفة statuses، وقيمة كل حالة، والحقول، والمطابقة عبر wamid وبيانات Meta الفعلية.خطاف الويب (webhook) user_preferences في WhatsApp: متى يوقف العميل رسائل التسويق أو يستأنفهايُرسل webhook user_preferences عند إيقاف العميل رسائل التسويق من نشاطك التجاري أو استئنافها. نعرض الحمولة، وما ينبغي فعله بها، وبديل الخطأ 131050.رسالة واجهة برمجة التطبيقات (API) لم تصل: الأسباب بالترتيبرسالة WhatsApp API لا تصل أبدًا؟ افحص إشعار الحالة ونافذة الـ24 ساعة والدفع والقوالب والمستلم والحدود بالترتيب الذي يكشف السبب.قالب WhatsApp متوقف أو معطّل: ما الذي تفعلهيوقف Meta قالب WhatsApp منخفض الجودة 3 ساعات ثم 6 ساعات، ثم يعطّله نهائيًا. كيف تعرف، وما الذي تغيّره، وما الخطوة التالية.خطأ WhatsApp 131049: حظر الرسالة للحفاظ على صحة المنظومةيعني الخطأ 131049 أن Meta حجبت الإرسال لحماية صحة المنظومة، لا بسبب إغلاق نافذة 24 ساعة. لماذا لا يحل القالب المشكلة.نافذة خدمة العملاء لمدة 24 ساعةما هي نافذة خدمة العملاء، ومتى تفتح وتغلق، وما الذي يمكن إرساله داخلها وخارجها، ولماذا تكون الردود داخلها مجانية؟

هل أنت مستعد للبدء؟

أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.

ابدأ الفترة التجريبية المجانية

تم التحقق في