Your AI Connector Docs

إسناد إعلانات “النقر للواتساب” (Click-to-WhatsApp)

إذا كنت تشغل إعلانات “النقر إلى واتساب” (Click to WhatsApp) على منصة Meta (فيسبوك/إنستغرام)، يمكن لـ Your AI Connector إخبارك بالإعلان الذي جاء منه كل عميل محتمل عبر واتساب — وتزويدك بمعرف نقرة Meta الذي تحتاجه للإبلاغ عن التحويلات الحقيقية إلى Meta. يتيح لك هذا تحسين حملاتك الإعلانية لتحقيق مبيعات وحجوزات فعلية، وليس فقط “للأشخاص الذين بدأوا محادثة”.

ما الذي يتم التقاطه

عندما ينقر شخص ما على إعلان “النقر إلى واتساب” ويرسل رسالة إلى نشاطك التجاري، تقوم Meta بإرفاق معلومات إحالة مخفية بتلك الرسالة الأولى. يقوم Your AI Connector بقراءتها تلقائياً وتخزينها في جهة الاتصال. لا حاجة لإعداد أو تهيئة — يحدث الأمر ببساطة.

يتم تخزين المعلومات التي تم التقاطها في جهة الاتصال كـ ad_referral وتحتوي على:

الحقل ما هو
ctwa_clid معرف نقرة Meta. هذه هي القيمة التي ترسلها إلى واجهة برمجة تطبيقات التحويلات (Conversions API) الخاصة بـ Meta لإسناد تحويل لاحق إلى نقرة الإعلان المحددة. يكون فارغاً لإحالات المنشورات العضوية (انظر أدناه).
source_id معرف الإعلان (أو المنشور) الذي نقر عليه الشخص.
source_type إما ad (إعلان “نقر للواتساب” مدفوع) أو post (منشور فيسبوك/إنستغرام عضوي).
source_url الرابط المرتبط بمحتوى الإعلان.
headline نص عنوان الإعلان.
body نص جسم الإعلان.
channel القناة التي وصلت منها الإحالة (حالياً دائماً whatsapp).
captured_at وقت تسجيل الإحالة لأول مرة في جهة الاتصال.

يمكنك رؤية هذا في لوحة العرض السريع الخاصة بجهة الاتصال إذا قمت بتهيئة حقل مخصص له، أو قراءته مباشرة من خلال خطافات الويب (webhooks) وواجهة برمجة التطبيقات (API) (انظر أدناه) — فهو لا يظهر كحقل مستقل يحمل تسمية خاصة به في جدول جهات الاتصال.

أمر واحد لا تخبرك به الحمولة (payload): أي من أرقامك وردت عليه المحادثة. لا يوجد معرف صفحة (page id) أو معرف حساب واتساب للأعمال (WhatsApp Business Account id) ضمنها. إذا كنت تستخدم رقماً واحداً فلا يهم ذلك؛ أما إذا كنت تدير عدة أرقام على صفحات فيسبوك مختلفة، فستحتاج إلى تعيين ذلك من جانبك.

الاتصال الذي يعمل عليه هذا

يعمل هذا على اتصال واجهة برمجة تطبيقات واتساب الرسمية فقط. لا تقدم Meta معلومات الإحالة المنظمة (بما في ذلك ctwa_clid) إلا من خلال واجهة برمجة تطبيقات واتساب للأعمال الرسمية. اتصال واتساب (الويب) غير الرسمي لا يتلقى هذه المعلومات — لا تتوفر بيانات نقرات الإعلانات في هذا الاتصال، وذلك بحكم تصميمه.

لذا، إذا كان إسناد الإعلانات ذو الحلقة المغلقة مهماً بالنسبة لك، فقم بتشغيل حملات “النقر للواتساب” الخاصة بك من خلال رقم متصل عبر واجهة برمجة تطبيقات واتساب الرسمية.

سلوك اللمسة الأولى

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

إدخال البيانات إلى Meta أو إعلانات Google

يقوم Your AI Connector بالتقاط بيانات الإسناد وعرضها، ولكنه لا يقوم بدفع التحويلات إلى Meta أو Google نيابة عنك بشكل أصلي في الوقت الحالي. يمكنك إعادة توجيه البيانات باستخدام خطافات الويب (webhooks) بالإضافة إلى أداة أتمتة.

يتم تضمين كائن ad_referral في قسم contact من أحداث خطاف الويب الصادرة (على سبيل المثال: رسالة جديدة، استئناف جهة الاتصال، تحديث وسوم جهة الاتصال، وأحداث التحليلات مثل حجز موعد).

إعداد نموذجي للحلقة المغلقة:

  1. ينقر عميل محتمل على إعلان “النقر إلى واتساب” الخاص بك ويرسل لك رسالة. يسجل Your AI Connector بيانات ad_referral (بما في ذلك ctwa_clid) على جهة الاتصال.
  2. مع تقدم العميل المحتمل — حجز مكالمة، أصبح عميلاً، أو تم فقدانه — تقوم بتحديد تلك النتيجة (انظر “تتبع مرحلة القمع” أدناه).
  3. يتم إطلاق خطاف ويب (webhook) إلى أداة الأتمتة الخاصة بك (Zapier أو Make أو Pabbly) يحمل كلاً من النتيجة و ctwa_clid الخاص بجهة الاتصال.
  4. تقوم أداة الأتمتة الخاصة بك باستدعاء واجهة برمجة تطبيقات التحويلات (Conversions API) الخاصة بـ Meta (باستخدام action_source = business_messaging و ctwa_clid) أو Google Ads (استيراد التحويلات دون اتصال / التحويلات المحسنة للعملاء المحتملين) للإبلاغ عن التحويل.

بهذه الطريقة تتعرف Meta و Google على الإعلانات التي حققت نتائج حقيقية وتعمل على تحسين الأداء بناءً عليها.

نقل مرحلة القمع

للإبلاغ عن تحويل، تحتاج عادةً إلى أمرين: معرف النقرة (يتم التقاطه تلقائياً) والنتيجة (التي تقوم بتعيينها). الطريقة الأكثر موثوقية لإرفاق نتيجة هي استخدام العلامات (tags)، لأن تطبيق علامة يؤدي إلى تشغيل خطاف الويب (webhook) contact_tags_updated — وتتضمن حمولة البيانات تلك ad_referral الخاص بجهة الاتصال. (إزالة علامة لا تؤدي إلى تشغيله؛ راجع تحديث علامات جهات الاتصال.)

يمكنك تطبيق العلامات تلقائياً:

  • اسمح لوكيل الذكاء الاصطناعي الخاص بك بوسم جهة الاتصال أثناء المحادثة — قم بإعداد قواعد الوسم التلقائي في تكوين الوكيل. هذه هي الطريقة التي يعمل بها نمط “صفحة هبوط واحدة لكل إعلان ← رسالة دخول واحدة ← وسم واحد” إذا كنت ترغب في تصنيف المصدر بنفسك.
  • أو قم بالوسم يدويًا من صفحة الدردشات أو جهات الاتصال.

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

يتم تعيين رابط الويب هوك (webhook URL) على الوسم (tag) نفسه، في علامة تبويب الوسوم (Tags) الخاصة بالوكيل (أو الحملة) التي ينتمي إليها جهة الاتصال - وليس في الإعدادات. يحصل كل وسم على رابطه الخاص، ويمكن لجميعها أن تشير إلى نفس نقطة النهاية (endpoint) إذا كنت ترغب في مكان واحد لاستقبال كل شيء.

قراءة معرف نقرة (click id) فاتك بالفعل

يتم إرجاع ad_referral أيضاً بواسطة واجهة برمجة التطبيقات (API) في كل من GET /v1/contacts/{id} (بصيغة adReferral) ونقطة نهاية قائمة جهات الاتصال (بصيغة ad_referral)، لذا إذا كان جهاز الاستقبال الخاص بك معطلاً، أو كنت تقوم بالمطابقة بأثر رجعي، يمكنك قراءة معرف النقرة بدلاً من انتظار الويب هوك التالي. جهات الاتصال التي وصلت قبل تسجيل معرف النقرة عليها تحتوي على null هنا - لا يمكن التقاط القيمة إلا من الرسالة الواردة نفسها، لذا لا يوجد شيء يمكن ملؤه بأثر رجعي.

القيود

  • اتصال واجهة برمجة تطبيقات WhatsApp الرسمي فقط (وليس الاتصال غير الرسمي عبر الويب).
  • لا يوجد تكامل أصلي بضغطة زر واحدة مع Meta CAPI أو Google Ads حتى الآن — يمكنك تمرير البيانات عبر Zapier أو Make أو Pabbly. إذا كنت ترغب في تكامل أصلي، فأخبر فريق الدعم على hi@youraiconnector.com.
  • يتم التقاط الإسناد للمستقبل، بدءاً من لحظة تفعيل هذه الميزة. لا يمكن إضافته بأثر رجعي للمحادثات التي تمت من قبل.

الخطوات التالية