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

حالات خطاف الويب (webhook) في WhatsApp: مرسلة ومسلمة ومقروءة وفاشلة

تُبلغ webhooks الحالات بما حدث لرسالة أرسلها نشاط تجاري عبر WhatsApp Cloud API، وهي واجهة برمجة التطبيقات (API) من Meta لإرسال الرسائل. تصل على حقل messages لكن بمصفوفة statuses بدلًا من مصفوفة messages: مرسلة (علامة واحدة)، ومسلمة (علامتان)، ومقروءة (علامتان زرقاوان)، ومشغلة للرسائل الصوتية، وفاشلة مع مصفوفة errors. طابق statuses[].id مع wamid الذي أعاده طلب الإرسال.

يربط easyCoexistence رقم WhatsApp Business الذي تستخدمه أصلًا بـ Cloud API من Meta عبر Coexistence.

5

قيم الحالة التي ترسلها Meta: مرسلة، ومسلمة، ومقروءة، ومشغلة (أول تشغيل للرسائل الصوتية)، وفاشلة.

3

حالات webhook منفصلة يمكن لرسالة صادرة واحدة أن تنتجها: مرسلة، ومسلمة، ومقروءة.

v24.0

ابتداءً من إصدار Graph API هذا يُحذف كائن conversation، إلا للرسائل ضمن نافذة نقطة الدخول المجانية.

0

لا توجد واجهات API لجلب بيانات webhook السابقة، وتطلب Meta منك التقاط الحمولات وتخزينها فور وصولها.

messages

الرأس X-EC-Event على الحالة المعاد توجيهها، وتنتقل الحالات داخل أحداث messages في مسار value.statuses.

أين تصل webhooks حالات WhatsApp؟

تصل على الحقل messages نفسه الذي يحمل ما يرسله العملاء، في الكائن نفسه والغلاف نفسه المكوّن من entry و changes. الفرق يقع داخل value: الرسالة الواردة فيها مصفوفة messages، والحالة فيها مصفوفة statuses. المعالج الذي يقرأ value.messages فقط يُسقط كل حالة دون أي خطأ. يحدد metadata.phone_number_id الرقم الذي أرسل الرسالة من أرقامك، وتأتي معه مصفوفة contacts تضم اسم ملف العميل وwa_id وBSUID، إلا في الحالات الفاشلة وعلى حالة sent للرسائل المرسلة إلى المجموعات. وهذا مثال من Meta لقالب تسويقي غادر خوادمها:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

ماذا تعني كل قيمة للحالة؟

كل قيمة تطابق علامة يراها العميل في WhatsApp. لا تُحتسب حالة مقروءة إلا بعد أن تكون مسلَّمة، لكن حين يستلم العميل رسالة والمحادثة مفتوحة أصلًا، ترسل Meta حالة read دون webhook سابق لـ delivered، وذلك كتحسين داخلي. لذلك ينبغي لأي متتبع أن يقبل read حتى إن لم يصل delivered، وأن يرتب الحالات حسب رتبتها لا أن ينتظرها بترتيب ثابت.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

ما الحقول التي يحملها كائن الحالة؟

أقل من حقول الرسالة، وبعضها مشروط. هذا ما تذكره مرجعية Meta عن ظهور كل حقل:

  • id: wamid للرسالة التي أرسلتها، وهو المفتاح الذي تُطابق عليه.
  • status و timestamp: القيمة، والوقت بصيغة Unix الذي أُطلق فيه الـ webhook، كنص.
  • recipient_id: رقم الهاتف أو معرّف المجموعة، ويُحذف حين ترسل إلى BSUID ولا يكون الرقم متوفرًا.
  • recipient_user_id: BSUID الخاص بالعميل، ويُحذف في الحالة الفاشلة عند الإرسال إلى رقم هاتف.
  • recipient_type و recipient_participant_id: فقط للرسائل المرسلة إلى مجموعة.
  • biz_opaque_callback_data: فقط حين تضبطه في طلب الإرسال.
  • pricing: فقط في حالة الإرسال وإحدى حالتي التسليم أو القراءة. errors: فقط في الحالة الفاشلة.

كيف تطابق الحالة مع الرسالة التي أرسلتها؟

عبر wamid. يعيد طلب الإرسال messages[0].id، وتحمل كل حالة لتلك الرسالة القيمة نفسها في statuses[].id. احفظها بجوار سجلك عند الإرسال، ثم حدّث السجل حين تصل الحالات، واحتفظ بأعلى حالة بلغتها، حتى لا تكتب delivered متأخرة فوق read. الحالة التي لا تعرف wamid الخاص بها أُرسلت من مصدر آخر على الرقم، مثل أتمتة، ويمكن تجاهلها أو تسجيلها.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

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

تصف الحالات ما أُرسل عبر API: ردود أتمتتك، والرسائل التي يرسلها الذكاء الاصطناعي عبر موصل MCP، وأي شيء يرسله كودك. أما ما يكتبه المالك في تطبيق WhatsApp Business فيصل إلى البرمجيات بطريقة مختلفة، باسم smb_message_echoes، وهي وفق توثيق Meta مرآة للرسائل المرسلة من التطبيق. الرسائل التي جاءت عبر استيراد السجل الأولي لمرة واحدة تحمل حالتها داخل webhook الخاص بالسجل، بقيم مثل delivered وread وplayed وpending وerror داخل حقل الحالة.

تذهب الحالات إلى أي وجهة يذهب إليها حقل messages الخاص بالرقم. مع وجهة مباشرة ترسل Meta الحالات إلى نقطة النهاية (endpoint) الخاصة بك مباشرة، لأن Meta تسمح للوجهة بتجاوز حقل messages، ومع تفعيل الأتمتة وضبط Forward URL تصل تلك الحالات إلى ذلك العنوان كأحداث الرسائل.

كيف يعرف الذكاء الاصطناعي أو الأتمتة أن الرسالة سُلّمت؟

من خلال وجهتك، لا من خلال الإرسال. حين يستدعي المساعد send_template أو send_message، تحمل نتيجة الأداة الـ wamid وتقول إن Meta قبلت الرسالة. يُؤكَّد التسليم لاحقًا على جهاز العميل، ويُبلَّغ به كحالة. لا يحتفظ easyCoexistence بسجل حالات قابل للاستعلام، ولا توجد أداة MCP تقرأ الحالات، لذا فالوكيل الذي يحتاج إلى تأكيد التسليم يجب أن يرسل عبر نظامك، أو أن يقرأ الحالات التي تصل إلى Forward URL الخاص بك، وهو عنوان إعادة التوجيه.

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

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

  • البحث عن حقل statuses منفصل. تأتي الحالات ضمن messages، فالمعالج الذي يقرأ value.messages فقط يخسرها دون أي خطأ.
  • اشتراط delivered قبل read. تتخطى Meta webhook الخاص بـ delivered حين تُقرأ الرسالة لحظة وصولها.
  • اعتبار رد الإرسال تسليمًا. يعني wamid أن Meta قبلت الطلب، وقد يلحق به فشل بعد دقائق كحالة فاشلة.
  • الاعتماد على recipient_id وحده لتعريف العملاء. يُحذف الحقل حين ترسل إلى BSUID ولا يكون رقم الهاتف متوفرًا، وحقل recipient_user_id هو الذي يحمل معرّف BSUID الخاص بالعميل.
إنجاز ذلك باستخدام EasyCoexistence

تصل الحالات الخاصة بما ترسله أتمتتك أو الذكاء الاصطناعي أو كودك إلى خادمك: مباشرة من Meta في الوضع المباشر، أو تُعاد توجيهها إلى Forward URL الخاص بك وتُوقَّع بـ X-EC-Signature عند تفعيل الأتمتة، ولا تُخزَّن افتراضيًا. من US$ 9 إلى US$ 0.75 لكل رقم شهريًا، وينخفض السعر كلما أضفت أرقامًا، مع أول 3 أيام مجانًا.

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

هل تتضمن webhooks الحالات نص الرسالة؟

لا. تحمل الحالة الـ wamid والحالة والمستلم والأوقات، وعند الاقتضاء التسعير والأخطاء. احتفظ بنسختك الخاصة مما أرسلته، مفهرسة بالـ wamid، إن احتجت إلى عرضه بجوار حالته.

هل يمكن جلب الحالات السابقة من Meta لاحقًا؟

لا. يقول دليل webhooks الخاص بـ Meta إنه لا توجد واجهات API لجلب بيانات webhook التاريخية، لذا فالحالة التي لم تلتقطها نقطة النهاية الخاصة بك تضيع حين تتوقف Meta عن إعادة المحاولة، بعد 7 أيام كحد أقصى.

ما فائدة biz_opaque_callback_data؟

هو نص تضبطه عند الإرسال، مثل معرّف طلبك أو تذكرتك الخاصة. تعيده Meta ضمن statuses لتلك الرسالة، فتستطيع مطابقة الحالة مع سجلك دون البحث عن wamid أولًا.

هل يجب أن أرد على webhooks الحالات بالرمز 200؟

نعم، كما في أي طلب POST خاص بـ webhook. تعامل Meta أي استجابة أخرى كتسليم فاشل وتعيد المحاولة، وهذا أحد الأسباب التي تجعل الحالة نفسها تصلك مرتين.

تابع القراءة

لماذا فشلت رسالة WhatsApp؟ قراءة حالة failed والأخطاء المرتبطة بهاتعني حالة failed أن Meta لم تتمكن من إرسال رسالة WhatsApp أو تسليمها. اقرأ مصفوفة errors والرموز الشائعة مثل 131047 و131049 و131050 وما تفعله.كائن التسعير في webhook حالة WhatsApp: type وcategory وbillable (2026)ما يحتويه كائن التسعير في webhooks حالات WhatsApp منذ أكتوبر 2026، وكيفية احتساب الرسوم من حقلي type وcategory.إعادة محاولات webhook في WhatsApp والتكرار والترتيب: كيفية التعامل معهايعيد Meta إرسال webhooks في WhatsApp لمدة تصل إلى 7 أيام، لذا التكرار أمر طبيعي والترتيب غير مضمون. مفاتيح إزالة التكرار، ومعالج آمن، وما يجب إرجاعه.خطاف الويب (webhook) للمكالمات في WhatsApp: أحداث Calling API والمكالمات على رقم Coexistenceيصف حقل calls أحداث Calling API في WhatsApp: الاتصال وإنهاء المكالمة وحالاتها والتسجيلات. حمولات حقيقية وما يسري على أرقام Coexistence.كيف تصل رسائل WhatsApp إلى خادمك: مباشرة أو مُدارة، والتحقق من التوقيعمباشرة: تنشر Meta إلى خادمك. مُدارة: ترد الأتمتة، وتصل نسخة موقّعة إلى عنوان URL للتوجيه. الحمولة، وتوقيع X-EC-Signature في Node وPython، وإعادة المحاولة.أسماء مستخدمي WhatsApp ومعرّفات BSUID: ما يتغيّر في خطّاف الويب (webhooks) لـ Cloud APIكيف تغيّر أسماء مستخدمي WhatsApp مضمون webhooks في Cloud API: معرّف BSUID في user_id، ومتى يختفي wa_id وfrom، والرد عبر recipient، وتغييرات Coexistence.

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

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

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

تم التحقق في