Your AI Connector Docs

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

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

هل تشغل إعلانات تؤدي إلى صفحة على موقعك الإلكتروني تحتوي على زر WhatsApp بدلاً من ذلك؟ راجع إسناد نقرات الإعلانات لـ WhatsApp.


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

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

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

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

يمكنك رؤيته دون أي إعداد: تعرض صفحة جهة الاتصال تسمية جاء من إعلان (Came from ad) أسفل اسمها (قم بتمرير المؤشر فوقها للحصول على تفاصيل الإعلان)، كما تظهر في لوحة جهة الاتصال بجوار الدردشة، ويبدأ سجل نشاط جهة الاتصال بالنقر على الإعلان. يمكنك أيضاً قراءتها من خلال خطافات الويب (webhooks) وواجهة برمجة التطبيقات (API) (انظر أدناه). إنها ليست عموداً في جدول جهات الاتصال.

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


العملاء المحتملون الذين يصلون بدون رقم هاتف

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

اترك حقل الهاتف فارغاً في جهة الاتصال هذه. لا تكتب رقم عملك الخاص فيه: لا يمكن إرسال رسالة من رقم إلى نفسه، لذا ستفشل المتابعة التلقائية التالية وسيتم إيقاف جهة الاتصال مؤقتاً. ترفض Your AI Connector الآن حفظ أحد أرقامك المتصلة كرقم هاتف لجهة اتصال. إذا قام الشخص لاحقاً بمشاركة رقمه، أو راسلك مرة أخرى وكان الرقم مرئياً، فسيتم ملؤه تلقائياً.


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

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

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


إعلانات النقر للوصول إلى إنستغرام والنقر للوصول إلى ماسنجر

يتم تسجيل الإعلانات التي تفتح رسالة مباشرة على إنستغرام أو محادثة ماسنجر بنفس الطريقة، على صفحة فيسبوك وحساب إنستغرام اللذين ربطتهما ببطاقة Instagram & Messenger. عندما يبدأ شخص ما محادثة من أحد تلك الإعلانات، تحصل جهة الاتصال على ad_referral مع ضبط channel على instagram أو messenger، وضبط source_type على ad، وضبط source_id على معرف الإعلان. يمنحك هذا الإعلان الذي يقف وراء كل جهة اتصال، حتى تتمكن من حساب تكلفة الحجز لكل إعلان.

بعض الاختلافات عن واتساب:

  • لا يوجد ctwa_clid؛ هذا الحقل فارغ. تصدر Meta معرف النقرة هذا لـ WhatsApp فقط.
  • headline هو عنوان الإعلان عندما ترسله Meta، و source_url هو رابط صورة أو فيديو الإعلان عند وجوده. body فارغ.
  • إذا جاء جهة الاتصال في البداية من إعلان واحد ثم بدأ لاحقاً محادثة من إعلان مختلف، فإن ad_referral يعرض الإعلان الأحدث.
  • تحمل جهات اتصال إعلانات Messenger الإعلان بدءاً من 14 أكتوبر 2026 فصاعداً. جهات الاتصال التي جاءت من إعلان Messenger قبل ذلك التاريخ ليس لديها ad_referral، لأن تفاصيل الإعلان لم تكن مسجلة حينها ولا يمكن ملؤها لاحقاً.
  • محادثات Messenger التي تبدأ بالنقر على زر Get Started (بدء الاستخدام) الخاص بالصفحة لا يتم تسجيلها. قم بإزالة زر Get Started من صفحتك (Meta Business Suite، إعدادات البريد الوارد) حتى يبدأ الأشخاص المحادثة عن طريق الكتابة، وسيتم تسجيل الإعلان في رسالتهم الأولى.

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

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


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

تقوم Your AI Connector بالتقاط بيانات الإسناد وعرضها. بالنسبة للإعلانات التي توجه الأشخاص إلى موقعك الإلكتروني أولاً، يمكن لـ Your AI Connector إرسال النتائج إلى Meta نيابةً عنك عند تطبيق وسم (tag): راجع إرسال النتائج إلى Meta. بالنسبة لإعلانات النقر للوصول إلى WhatsApp، يمكنك إعادة توجيه البيانات باستخدام خطافات الويب (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 الخاص بجهة الاتصال. (إزالة علامة لا تؤدي إلى تشغيله؛ راجع تحديث علامات جهات الاتصال.)

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

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

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

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

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

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


القيود

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

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