Your AI Connector Docs

שיוך מודעות “קליק לוואטסאפ” (Click-to-WhatsApp)

אם אתה מריץ מודעות “Click to WhatsApp” של Meta (פייסבוק/אינסטגרם), Your AI Connector יכול לומר לך מאיזו מודעה הגיע כל ליד בוואטסאפ — ולספק לך את מזהה הלחיצה של Meta הדרוש לך כדי לדווח על המרות אמיתיות בחזרה ל-Meta. זה מאפשר לקמפיינים הפרסומיים שלך לבצע אופטימיזציה למכירות והזמנות בפועל, ולא רק ל"אנשים שהתחילו צ’אט".

מריצים מודעות לדף באתר האינטרנט שלכם עם כפתור WhatsApp במקום? ראו ייחוס לחיצות מודעה עבור WhatsApp.

מה נתפס

כאשר מישהו מקיש על מודעת Click-to-WhatsApp ושולח הודעה לעסק שלך, Meta מצרפת מידע הפניה נסתר להודעה הראשונה הזו. Your AI Connector קורא אותו באופן אוטומטי ושומר אותו באיש הקשר. ללא הגדרה, ללא קונפיגורציה — זה פשוט קורה.

המידע שנלכד נשמר באיש הקשר תחת ad_referral ומכיל:

שדה מה הוא מייצג
ctwa_clid מזהה הלחיצה של Meta. זהו הערך שאתה שולח ל-Conversions API של Meta כדי לשייך המרה במורד הזרם ללחיצה המדויקת על המודעה. ריק עבור הפניות מפוסטים אורגניים (ראה להלן).
source_id המזהה של המודעה (או הפוסט) שעליה האדם לחץ.
source_type או ad (מודעת Click-to-WhatsApp ממומנת) או post (פוסט אורגני בפייסבוק/אינסטגרם).
source_url הקישור המשויך לתוכן המודעה.
headline טקסט הכותרת של המודעה.
body טקסט גוף המודעה.
channel הערוץ שדרכו הגיעה ההפניה: whatsapp, instagram או messenger.
captured_at מתי ההפניה תועדה לראשונה אצל איש הקשר.

ניתן לראות זאת ללא כל הגדרה: דף איש הקשר מציג תווית הגיע ממודעה מתחת לשמו (רחפו מעליה כדי לראות את פרטי המודעה), לוח איש הקשר לצד הצ’אט מציג זאת גם כן, והפעילות של איש הקשר מתחילה בלחיצה על המודעה. ניתן גם לקרוא זאת באמצעות webhooks וה-API (ראו להלן). זה אינו עמודה בטבלת אנשי הקשר.

דבר אחד שהמטען (payload) לא אומר לך: על איזה מהמספרים שלך הגיעה השיחה. אין בו מזהה דף (page id) או מזהה חשבון WhatsApp Business. עם מספר בודד זה לא משנה; אם אתה מפעיל מספרים שונים בדפי פייסבוק שונים, תצטרך למפות זאת בצד שלך.

לידים שמגיעים ללא מספר טלפון

חלק מהאנשים ששולחים לך הודעה ממודעה מסתירים את מספר הטלפון שלהם ב-WhatsApp. במקרה כזה, Meta מעבירה מזהה פרטי עבור האדם במקום מספר, ואיש הקשר נוצר עם שדה טלפון ריק. זה צפוי. תשובות, תשובות AI ומעקבים אוטומטיים עדיין יגיעו לאדם, מכיוון ש-Your AI Connector פונה אליו באמצעות המזהה הזה.

השאר את שדה הטלפון ריק עבור איש קשר כזה. אל תקליד בו את מספר העסק שלך: לא ניתן לשלוח הודעה ממספר לעצמו, ולכן המעקב האוטומטי הבא ייכשל ואיש הקשר יושהה. Your AI Connector מסרבת כעת לשמור את אחד מהמספרים המחוברים שלך כמספר טלפון של איש קשר. אם האדם ישתף את המספר שלו מאוחר יותר, או ישלח לך הודעה שוב כשהוא גלוי, הוא יתמלא באופן אוטומטי.

על איזה חיבור זה עובד

זה עובד על חיבור ה-WhatsApp API הרשמי בלבד. Meta מספקת את מידע ההפניה המובנה (כולל ctwa_clid) רק דרך ה-WhatsApp Business API הרשמי. חיבור ה-WhatsApp (web) הלא-רשמי אינו מקבל אותו — אין נתוני לחיצה על מודעות הזמינים בחיבור הזה, מעצם האופן שבו הוא עובד.

לכן, אם שיוך מודעות במעגל סגור חשוב לכם, הריצו את קמפייני ה"קליק לוואטסאפ" שלכם דרך מספר המחובר באמצעות ה-API הרשמי של WhatsApp.

מודעות Click-to-Instagram ו-Click-to-Messenger

מודעות שפותחות הודעה ישירה באינסטגרם או צ’אט במסנג’ר מתועדות באותו אופן, בדף הפייסבוק ובחשבון האינסטגרם שחיברת באמצעות הכרטיס Instagram & Messenger. כאשר מישהו מתחיל צ’אט מאחת המודעות הללו, איש הקשר מקבל ad_referral עם channel שמוגדר כ-instagram או messenger, source_type שמוגדר כ-ad ו-source_id שמוגדר כמזהה המודעה. זה נותן לך את המודעה שמאחורי כל איש קשר, כך שתוכל לחשב את העלות להזמנה לכל מודעה.

כמה הבדלים מ-WhatsApp:

  • אין 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 Ads

Your AI Connector לוכד את נתוני הייחוס וחושף אותם. עבור מודעות ששולחות אנשים קודם כל לאתר האינטרנט שלכם, Your AI Connector יכול לשלוח תוצאות ל-Meta עבורכם כאשר מוחלת תגית: ראו שליחת תוצאות ל-Meta. עבור מודעות Click-to-WhatsApp, אתם מעבירים את הנתונים באמצעות webhooks בתוספת כלי אוטומציה.

האובייקט ad_referral כלול בסעיף contact של אירועי ה-webhook היוצאים (לדוגמה: הודעה חדשה, איש קשר חזר לפעילות, תגיות איש קשר עודכנו, ואירועי אנליטיקה כגון פגישה שנקבעה).

הגדרה טיפוסית למעגל סגור:

  1. ליד לוחץ על מודעת ה-Click-to-WhatsApp שלך ושולח לך הודעה. 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 לומדות אילו מודעות הניבו תוצאות אמיתיות ומבצעות אופטימיזציה לפיהן.

העברת שלב המשפך

כדי לדווח על המרה, בדרך כלל דרושים שני דברים: מזהה הלחיצה (click id) (שנקלט באופן אוטומטי) והתוצאה (שאותה אתה מגדיר). הדרך האמינה ביותר לצרף תוצאה היא באמצעות תגיות, מכיוון שהחלת תגית מפעילה את ה-webhook מסוג contact_tags_updated — וה-payload הזה כולל את ה-ad_referral של איש הקשר. (הסרת תגית אינה מפעילה אותו; ראה עדכון תגיות איש קשר.)

ניתן להחיל תגיות באופן אוטומטי:

  • תנו לסוכן ה-AI שלכם לתייג את איש הקשר במהלך השיחה — הגדירו חוקי תיוג אוטומטיים בהגדרות הסוכן. כך עובד דפוס ה-“דף נחיתה אחד לכל מודעה ← הודעת כניסה אחת ← תגית אחת” אם ברצונכם לתייג את המקור בעצמכם.
  • או תייגו ידנית מתוך הצ’אטים או דף אנשי הקשר.

בכל פעם שתגית רלוונטית משתנה, ה-webhook מופעל עם מזהה הלחיצה המצורף, מוכן להעברה כהמרה.

כתובת ה-URL של ה-webhook מוגדרת על התגית עצמה, בלשונית Tags בעורך של סוכן ה-AI שאליו משויך איש הקשר, ולא בהגדרות (Settings). לכל תגית יש כתובת URL משלה, וכולן יכולות להצביע על אותו נקודת קצה (endpoint) אם ברצונך לרכז את כל המידע במקום אחד.

קריאת מזהה לחיצה (click id) שכבר פספסת

ad_referral מוחזר גם על ידי ה-API ב-GET /v1/contacts/{id} (בתור adReferral) וב-endpoint של רשימת אנשי הקשר (בתור ad_referral), כך שאם המקלט שלך היה מושבת, או שאתה מבצע התאמה בדיעבד, תוכל לקרוא את מזהה הלחיצה בחזרה במקום להמתין ל-webhook הבא. לאנשי קשר שהגיעו לפני שמזהה הלחיצה תועד עליהם יש null כאן — ניתן לתפוס את הערך רק מההודעה הנכנסת עצמה, לכן אין מה למלא רטרואקטיבית.

מגבלות

  • חיבור API רשמי של WhatsApp בלבד (לא החיבור הלא-רשמי מבוסס האינטרנט).
  • ה-שליחת תוצאות ל-Meta המובנה שולח את נתוני הלחיצה שתועדו על ידי הסקריפט של האתר; הוא אינו שולח את ה-ctwa_clid של מודעות Click-to-WhatsApp. עבור אלו, ועבור Google Ads, אתם מעבירים את הנתונים דרך Zapier/Make/Pabbly. אם תרצו אינטגרציה מובנית, הודיעו לתמיכה ב-hi@youraiconnector.com.
  • הייחוס נלכד מרגע זה ואילך, מהרגע שזה פעיל. לא ניתן להחיל אותו רטרואקטיבית על שיחות שהתרחשו לפני כן.

צעדים הבאים