خطاف الويب (webhook) user_preferences في WhatsApp: متى يوقف العميل رسائل التسويق أو يستأنفها
يُخبر webhook user_preferences النشاط التجاري بأن مستخدم WhatsApp أوقف رسائله التسويقية أو استأنفها عبر إعداد العروض والإعلانات. يحمل كل حدث الفئة marketing_messages، وقيمة stop أو resume، وجملة تفصيلية، وwa_id وBSUID، وطابعًا زمنيًا من نوع Unix. ولا تُطلقه ملاحظات «مهتم» و«غير مهتم» في الإعداد نفسه.
تربط easyCoexistence رقم تطبيق WhatsApp Business الخاص بك بواجهة Meta Cloud API عبر Coexistence، فيعمل الذكاء الاصطناعي والأتمتة على الرقم الذي تحتفظ به في التطبيق.
القيم التي يمكن أن يأخذها التفضيل: stop وresume، وكلاهما ضمن الفئة marketing_messages.
رمز حالة الفشل لقالب تسويقي أُرسل إلى مستخدم أوقف رسائلك التسويقية.
وجهة إرسال Meta لحدث user_preferences: هو حقل لا يستطيع حساب WhatsApp Business أو الرقم تجاوز وجهته.
الإذن الذي يحتاجه التطبيق لأي webhook غير messages وcalls، ومن ضمنها user_preferences.
متى يُرسَل حدث user_preferences إلى النشاط التجاري؟
عندما يفتح العميل «العروض والإعلانات» في WhatsApp ويختار إيقاف رسائل التسويق من نشاطك التجاري، أو استئنافها لاحقًا. هذان الإجراءان هما المحفزان الوحيدان. ويتيح الإعداد نفسه للعميل وضع «مهتم» أو «غير مهتم»، ولا ترسل هذه الملاحظات أي webhook، مع أن «غير مهتم» قد تخفض حد التسويق لكل مستخدم بينك وبين ذلك العميل، وتفتح شاشة ثانية تعرض إيقاف رسائل التسويق نهائيًا. لا يُفعَّل user_preferences إلا إذا ضغط العميل على الإيقاف بعد ذلك.
ماذا تحتوي الحمولة؟
مصفوفة user_preferences بجانب مصفوفة contacts، تحت اسم الحقل user_preferences. الطابع الزمني هنا عدد صحيح، بينما ترسله webhooks الحالة كسلسلة نصية. يُحذف wa_id عندما يستخدم العميل اسم مستخدم ولا يمكن مشاركة رقم هاتفه، ويُحذف user_id عندما لا تكون معرّفات المستخدمين المحددة بالنشاط مفعّلة لنشاطك التجاري، ويُحذف parent_user_id ما لم تكن معرّفات BSUID الأصلية مفعّلة. هذا مثال Meta على الاستئناف:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}ماذا ينبغي أن يفعل نظامك عند الإيقاف؟
سجّله على العميل، وأبقِه خارج كل إرسال تسويقي حتى يصل استئناف. يقرأ الحقل detail إحدى العبارتين "User requested to stop marketing messages" أو "User requested to resume marketing messages"، لكن الكود ينبغي أن يقرأ value.
- خزّن التفضيل بواسطة BSUID وبرقم الهاتف، لأن أيًّا منهما قد يغيب في حدث معيّن.
- استبعد العميل من إرسال قوالب التسويق؛ فـ Meta سترفضها على أي حال بالخطأ 131050.
- طبّق التفضيل على كل عميل على حدة فقط: لا تطبّقه Meta أبدًا على مستوى BSUID الأب.
- عند الاستئناف ارفع الاستبعاد، واحتفظ بسجل الموافقة الخاص بك كما تقتضي سياسة الاشتراك في Meta.
ماذا لو لم يصل user_preferences إلى خادمك أبدًا؟
تفرض Meta الإيقاف على أي حال، لذا يكلفك الحدث المفقود إرسالًا فاشلًا، لا خرقًا لسياسة. عندما ترسل قالبًا تسويقيًا إلى شخص أوقف الرسائل، تقبل واجهة برمجة التطبيقات (API) الطلب ولا ترسل الرسالة، وتطلق webhook حالة بالقيمة failed والرمز 131050 والعنوان "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business". عامل هذا الفشل تمامًا كحدث إيقاف: سجّله، واستبعد العميل من أي إرسال تسويقي لاحق.
ماذا يحدث للرقم المتصل عبر easyCoexistence مع هذه الأحداث؟
user_preferences ليس من الحقول التي تسمح Meta بتجاوز وجهتها، فيُسلَّم فقط إلى رد الاتصال الافتراضي (callback) للتطبيق المشترك في الحساب. بالنسبة إلى رقم متصل عبر easyCoexistence، فذلك التطبيق هو تطبيق easyCoexistence، وهو لا يشترك في user_preferences اليوم، لذا لا يصل الحدث إلى وجهة مباشرة ولا إلى Forward URL المُعدّ لك. أما حالة الفشل 131050 فتصل، لأنها تسلك حقل messages ذاته.
إذا كان ذكاؤك الاصطناعي يرسل قوالب تسويقية عبر send_template، فاحتفظ بقائمة الإيقاف في نظامك وتحقق منها أولًا، إذ لا تحتفظ easyCoexistence بواحدة.
الأخطاء الشائعة
- اعتبار «غير مهتم» إيقافًا. فهي لا ترسل أي webhook ولا توقف التسليم، لكنها قد تخفض حد التسويق لكل مستخدم لهذا العميل.
- حفظ التفضيلات بـ wa_id وحده. فهو يغيب عن العملاء الذين لهم اسم مستخدم ولا يمكن مشاركة رقمهم، فاحفظ BSUID أيضًا.
- تطبيق الإيقاف على الجميع تحت BSUID أب. فـ Meta تطبق التفضيلات لكل مستخدم، لا على المستوى الأب أبدًا.
- إعادة المحاولة بعد 131050 بدل تسجيله كإيقاف. كل محاولة تفشل بالطريقة نفسها.
تُرسل قوالب التسويق عبرها من حساب WhatsApp Business الخاص بك، وتصل حالات الفشل التي تُبلغ عن عميل متوقف إلى خادمك مباشرة أو عبر إعادة توجيه موقّعة. من US$ 9 إلى US$ 0.75 لكل رقم شهريًا، ويقل السعر كلما أضفت أرقامًا، مع فترة تجريبية مجانية لمدة 3 أيام.
الأسئلة الشائعة
هل يوقف الإيقاف الردود على رسائل العميل نفسه؟
تصف وثائق Meta الإيقاف بأنه يشمل رسائل التسويق، والخطأ الذي تعيده يذكر رسائل التسويق صراحةً. الردود على عميل كتب إليك هي رسائل خدمة، وهي فئة مختلفة.
هل يؤدي حظر النشاط التجاري إلى تفعيل user_preferences نفسه؟
لا. يُطلق الـ webhook فقط عند الإيقاف والاستئناف في إعداد العروض والإعلانات. الحظر إجراء منفصل ولا يُبلغ عنه في هذا الحقل.
هل يُحسب الاستئناف موافقة على الاشتراك؟
يعني أن العميل اختار استقبال رسائل التسويق منك مجددًا. ما زالت التزاماتك بالموافقة وفق سياسة Meta قائمة، لذا احتفظ بسجل كيف ومتى وافق هذا العميل على تلقي رسائلك.
أي حقل webhook أشترك فيه؟
user_preferences، في App Dashboard ضمن WhatsApp > Configuration، على التطبيق المشترك في حساب WhatsApp Business. وهو حقل منفصل عن messages ويتطلب الإذن whatsapp_business_management نفسه.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في