WhatsApp Catalog API: صمّم سير العمل بعد نقرة المنتج

تستطيع واجهة WhatsApp Catalog API إدخال منتج إلى المحادثة، لكنها لا تنشئ بمفردها عملية طلب موثوقة. يبدأ السؤال المفيد بعد أن ينقر العميل على المنتج: أي معرّف يرافقه؟ من يملك الاستفسار؟ متى يُفحص المخزون؟ ما الذي يحوّل الطلب الوارد إلى مهمة تنفيذ؟ وكيف يتعافى الفريق عندما يختلف الواقع عن الكتالوج؟

يجيب هذا الدليل عن السؤال التشغيلي. فهو يستخدم كائنات رسائل الكتالوج والـ webhook الحالية لدى Meta كحدود تقنية، ثم يحولها إلى سير عمل عملي يمكن لفريق التجارة اختباره. القاعدة الأساسية بسيطة: تعامل مع الكتالوج كسطح لاكتشاف المنتجات، ومع كل webhook كدليل على نية العميل، لا كإثبات على حجز المخزون أو اكتمال الدفع أو بدء التنفيذ.

ما الذي توفره WhatsApp Catalog API فعلياً؟

توثق مجموعة Meta الرسمية شكلين مفيدين من الرسائل التفاعلية. تستخدم رسالة المنتج الواحد type: interactive والنوع الفرعي product ومعرّفي catalog_id وproduct_retailer_id. أما رسالة المنتجات المتعددة فتستخدم النوع الفرعي product_list وcatalog_id واحداً وأقساماً تحتوي عناصر تُعرّف بواسطة product_retailer_id (طلب المنتج الواحد، طلب المنتجات المتعددة).

توثق Meta أيضاً قوالب كتالوج تحتوي زر CATALOG. تفتح هذه القوالب كتالوج المنشأة داخل WhatsApp، لكنها لا تستبدل أنظمة المنتجات أو المخزون أو إدارة الطلبات أو الدفع (طلب قالب الكتالوج). اختر نوع الرسالة وفق مهمة العميل، لا وفق الشكل الأكثر لفتاً للنظر.

الجانب الوارد مهم بالقدر نفسه. قد يصل استفسار منتج عندما يرد الشخص على رسالة منتج أو يستخدم «مراسلة النشاط التجاري» من صفحة تفاصيله. وقد يتضمن سياق webhook القيمتين referred_product.catalog_id وreferred_product.product_retailer_id (webhook استفسار المنتج). ويمكن أن يحتوي كائن الطلب catalog_id وproduct_items والكمية وسعر العنصر والعملة وproduct_retailer_id لكل عنصر (مرجع كائن الرسائل). تحدد هذه الحقول ما اختاره العميل، لكن أنظمتك تظل مسؤولة عن تحديد الوعد والخطوة التالية.

أنشئ عقد تشغيل واحداً من الكتالوج إلى الطلب

يبدأ سير العمل الموثوق بعقد مكتوب واحد بين التسويق وخدمة العملاء وعمليات التجارة والهندسة. يجب أن يحدد معنى خمسة سجلات ومالك كل منها:

• العميل — wa_id أو الهاتف أو contact_uuid الداخلي: ربط الهوية بسجل المحادثة
• الكتالوج — catalog_id: تحديد مصدر المنتج المستخدم في الرسالة
• المنتج — product_retailer_id: ربط عنصر WhatsApp برمز SKU ثابت لدى التاجر
• التفاعل — معرّف الرسالة الصادرة ومعرّف webhook الوارد: إعادة بناء التسلسل ومنع تكرار الحدث
• مهمة العمل — معرّف الاستفسار أو الطلب مع الحالة والمالك: نقل النية عبر التحقق والاسترداد والإكمال

لا تحمّل حالة واحدة معاني متعددة. يجب ألا يعني «تم استلام الطلب» أيضاً «تم الدفع» أو «تم الحجز» أو «تم الشحن». نموذج أدنى مفيد هو received → validating → reserved → confirmed → fulfilled مع مخارج صريحة مثل needs_customer وout_of_stock وcancelled وfailed. إذا كان نظام تجارة آخر يملك الدفع أو التنفيذ، فاحفظ مرجعه بجوار سجل المراسلة بدلاً من اعتبار WhatsApp نظام السجل.

استخدم سيراً من سبع مراحل بعد نقرة المنتج

1. افحص الأهلية قبل الإرسال. تأكد من أن جهة الاتصال مؤهلة للرسالة المقصودة، وأن المنتج نشط، وأن معرّف التاجر يحل إلى SKU حالي واحد، وأن نوع الرسالة يلائم المهمة. يكون المنتج الواحد أوضح عادة عندما حددت المحادثة عنصراً بعينه. وتفيد المنتجات المتعددة عند مقارنة مجموعة صغيرة ذات صلة. أما قالب الكتالوج فيلائم إعادة فتح الاكتشاف فقط عندما يكون القالب والمتلقي مؤهلين.

2. سجّل ما أُرسل. خزّن العميل وcatalog_id وكل product_retailer_id ومعرّف الرسالة واللغة ولقطة السعر عند الحاجة ومصدر الحملة أو سير العمل. هذا هو سجل التدقيق لأسئلة لاحقة مثل: أي سعر رآه العميل؟ ولماذا عُرض عليه هذا المنتج؟

3. صنّف الرد من دون فقدان السياق. يجب أن يدخل استفسار المنتج إلى طابور مرفقاً به الكتالوج والمنتج المشار إليهما. حتى الرد الحر يحتاج سياق الرسالة الأصلية حين يتوفر. لا تجعل الوكيل يطلب من العميل تعريف منتج سبق أن حدده webhook.

4. تحقّق قبل تقديم الوعد. طابق معرّف التاجر مع نظام المنتجات الحالي. افحص صلاحية البيع والسعر والعملة والمخزون أو الطاقة وقواعد التوصيل أو الاستلام وأي خيار لم تلتقطه الرسالة. هنا يتحول الكتالوج القديم إلى استثناء مضبوط بدلاً من وعد مكسور.

5. احجز وأكّد عمداً. إذا كانت المنشأة تحجز المخزون، فأنشئ الحجز في النظام الذي يملكه وحدد انتهاءً له. بعد ذلك فقط أخبر العميل بما تم الاحتفاظ به، ومدة الاحتفاظ، والإجراء الذي يكمل الشراء. إذا تعذر الحجز، صرّح بذلك وتجنب لغة توحي باليقين.

6. اعتبر webhook الطلب طلباً للمعالجة. تحقق من كل عنصر وكمية وعملة وإجمالي حالي، وامنع تكرار الحدث، ثم أنشئ الطلب أو حدّثه في نظام التجارة. أرسل حالات عدم التطابق إلى طابور استثناء يملكه إنسان. حمولة الطلب وحدها ليست دليلاً على تسوية الدفع أو التنفيذ الفعلي.

7. أغلق الحلقة. اكتب النتيجة النهائية في مخطط المحادثة: مؤكّد أو مستبدل أو ملغى أو مستلم أو مشحون أو فاشل. أخطر العميل عبر مسار رسالة مؤهل، واحتفظ بالمالك المسؤول، وسجّل سبب أي استبدال أو إلغاء.

مثال واقعي: استلام من مركز نباتات

لنفترض أن عميلاً يسأل عن نبتة إكليل الجبل بحجم لترين. يرسل الفريق رسالة منتج واحد يرتبط فيها product_retailer_id بالرمز herb-rosemary-2l. وعندما يرد العميل، يحدد webhook الاستفسار المنتج نفسه. يربط سير العمل المحادثة بجهة الاتصال الصحيحة ويوجهها إلى طابور الاستلام.

قبل أن يعد أي شخص بالاستلام، تفحص خدمة المخزون SKU نفسه في الفرع المطلوب. إذا كان متوفراً، ينشئ النظام حجزاً لمدة 90 دقيقة ويؤكد الوكيل الفرع والكمية والسعر وموعد الانتهاء. وإذا أرسل العميل عربة من الكتالوج، يعيد معالج الطلب التحقق من العنصر ويمنع تكرار webhook ويفتح مهمة استلام. لا يكتمل الاستلام إلا عندما يسجل نظام المتجر التشغيلي التسليم الفعلي.

إذا كان الكتالوج قديماً ولم تتوفر النبتة بالحجم المطلوب، فلا يستبدلها سير العمل سراً بأصيص أصغر. بل يضع الحالة out_of_stock ويقترح بديلاً محدداً بعد التحقق منه فقط، مع إبقاء الاختيار الأصلي ظاهراً في المحادثة. قيمة هذا التصميم ليست مزيداً من الأتمتة، بل وعداً واضحاً قابلاً للاسترداد.

اختر نوع الرسالة وفق تكلفة القرار

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

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

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

صمّم ضوابط الفشل قبل الإطلاق

أعلى المخاطر هو product_retailer_id غير المستقر. عامله كمفتاح تكامل دائم، لا كتسمية عرض. إذا غيّر التاجر رموز SKU الداخلية، فاستخدم ربطاً أو ترحيلاً صريحاً؛ ولا تعِد استخدام معرّف قديم لمنتج مختلف.

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

صمّم أيضاً لحدود نافذة المحادثة. توضح صفحة مطوري DripTell الحالية أن إرسال المنتجات قد يعيد استجابة 422 عندما تكون نافذة خدمة العملاء ذات 24 ساعة مغلقة (واجهة مطوري DripTell). لذلك يحتاج سير الإنتاج إلى قالب مؤهل أو قرار بشري بدلاً من إعادة المحاولة العمياء.

وأخيراً افصل نجاح النقل عن نجاح الأعمال. قد تصل الرسالة ولا تنتج استفساراً. وقد يفشل حدث الطلب في التحقق من المخزون. وقد يفوت العميل موعد الاستلام بعد التأكيد. يجب أن تحافظ لوحات القياس والتنبيهات على هذه الفروق.

قِس المسار لا حجم الرسائل فقط

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

لا تضع معياراً عشوائياً قبل مراقبة خط أساس نظيف. أثبت أولاً أن الأحداث مكتملة وغير مكررة، ثم افحص أين تضيع النية المؤهلة. قد تكون نسبة الاستفسار الأقل مقبولة إذا أنتجت رسالة دقيقة لمنتج واحد طلبات أقل ولكن أفضل تطابقاً. وعدد الطلبات المرتفع ليس صحياً إذا ارتفعت معه الاستبدالات والإلغاءات والحجوزات غير المستلمة.

اربط سير العمل بـ DripTell

تشمل إمكانات WhatsApp المنشورة لدى DripTell كتالوجات التجارة ورسائل المنتجات وصندوقاً مشتركاً والتوجيه وسياق العميل والملاحظات ومسارات المتابعة (قناة WhatsApp). وتعرض وثائق API المسار /api/v1/send/product لإرسال منتج واحد أو عدة منتجات باستخدام catalog_id وproduct_retailer_id أو products مع phone أو contact_uuid، كما توثق طلبات عربة الكتالوج في سجل تجارة WhatsApp (واجهة المطورين).

ينتج عن ذلك مسار عملي: احتفظ بمفتاح المنتج الثابت في نظام التجارة المصدر، وأرسل رسالة الكتالوج المناسبة، واحتفظ بسياق الرسالة على جهة الاتصال، ووجّه الرد إلى الصندوق المشترك، واستخدم الأتمتة فقط للخطوات ذات المدخلات وحالات الفشل الصريحة. يجب أن يملك شخص حالات تطابق المنتج الغامض وتعارض المخزون وتغير السعر والاستبدال واستثناء التنفيذ.

أطلق بمجموعة إثبات من عشر حالات

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

يجب أن يعتمد قرار الإطلاق على قدرة الفريق على شرح كل حالة والتعافي منها، لا على لمعان المسار السعيد. إذا أردت اختبار رحلة كتالوج حقيقية مقابل حدود المراسلة والصندوق والأتمتة في DripTell، احجز عرضاً لسير العمل مع خريطة SKU ومالكي الاستثناءات ونظام التنفيذ أمامك.