Your AI Connector Docs

Click-to-WhatsApp Anzeigen-Attribution

Wenn Sie Meta (Facebook/Instagram) „Click to WhatsApp“-Anzeigen schalten, kann Your AI Connector Ihnen sagen, von welcher Anzeige jeder WhatsApp-Lead stammt – und Ihnen die Meta-Klick-ID übermitteln, die Sie benötigen, um echte Conversions an Meta zurückzumelden. Dadurch können Ihre Werbekampagnen auf tatsächliche Verkäufe und Buchungen optimiert werden, nicht nur auf „Personen, die einen Chat gestartet haben“.

Schalten Sie stattdessen Anzeigen für eine Seite auf Ihrer eigenen Website mit einem WhatsApp-Button? Siehe Anzeigen-Klick-Attribution für WhatsApp.

Was erfasst wird

Wenn jemand auf eine „Click-to-WhatsApp“-Anzeige tippt und Ihrem Unternehmen eine Nachricht sendet, fügt Meta dieser ersten Nachricht versteckte Empfehlungsinformationen hinzu. Your AI Connector liest diese automatisch aus und speichert sie beim Kontakt. Kein Setup, keine Konfiguration – es geschieht einfach.

Die erfassten Informationen werden beim Kontakt als ad_referral gespeichert und enthalten:

Feld Beschreibung
ctwa_clid Der Meta-Klick-Identifikator. Dies ist der Wert, den Sie an die Conversions API von Meta senden, um eine nachgelagerte Conversion genau dem Anzeigenklick zuzuordnen. Bei organischen Beitrags-Referrals leer (siehe unten).
source_id Die ID der Anzeige (oder des Beitrags), auf die die Person geklickt hat.
source_type Entweder ad (eine bezahlte Click-to-WhatsApp-Anzeige) oder post (ein organischer Facebook-/Instagram-Beitrag).
source_url Der mit dem Anzeigeninhalt verknüpfte Link.
headline Der Schlagzeilentext der Anzeige.
body Der Fließtext der Anzeige.
channel Der Kanal, über den der Referral einging: whatsapp, instagram oder messenger.
captured_at Zeitpunkt, zu dem der Referral erstmals beim Kontakt erfasst wurde.

Sie können es ohne jegliche Einrichtung sehen: Die Kontaktseite zeigt unter dem Namen ein Label Came from ad an (bewegen Sie den Mauszeiger darüber, um die Anzeigendetails zu sehen), das Kontakt-Panel neben dem Chat zeigt es ebenfalls an und die Aktivität des Kontakts beginnt mit dem Anzeigen-Tap. Sie können dies auch über Webhooks und die API auslesen (siehe unten). Es handelt sich nicht um eine Spalte in der Kontakte-Tabelle.

Eines verrät Ihnen die Payload nicht: über welche Ihrer Nummern das Gespräch eingegangen ist. Sie enthält weder eine Seiten-ID noch eine WhatsApp Business Account-ID. Bei einer einzelnen Nummer spielt das keine Rolle; wenn Sie jedoch mehrere Nummern auf verschiedenen Facebook-Seiten betreiben, müssen Sie dies auf Ihrer Seite zuordnen.

Leads, die ohne Telefonnummer eingehen

Einige Personen, die Ihnen über eine Anzeige schreiben, haben ihre Telefonnummer bei WhatsApp verborgen. In diesem Fall übermittelt Meta anstelle einer Nummer eine private ID für die Person, und der Kontakt wird mit einem leeren Telefonfeld erstellt. Das ist so vorgesehen. Antworten, KI-Antworten und automatische Follow-ups erreichen die Person dennoch, da Your AI Connector sie über diese ID anspricht.

Lassen Sie das Telefonfeld bei einem solchen Kontakt leer. Geben Sie nicht Ihre eigene geschäftliche Nummer ein: Eine Nachricht kann nicht von einer Nummer an sich selbst gesendet werden, sodass das nächste automatische Follow-up fehlschlagen würde und der Kontakt pausiert würde. Your AI Connector verweigert nun das Speichern einer Ihrer eigenen verbundenen Nummern als Telefonnummer eines Kontakts. Wenn die Person ihre Nummer später teilt oder Ihnen erneut schreibt, während sie sichtbar ist, wird sie automatisch ausgefüllt.

Für welche Verbindung dies funktioniert

Dies funktioniert nur mit der offiziellen WhatsApp-API-Verbindung. Meta stellt die strukturierten Empfehlungsinformationen (einschließlich ctwa_clid) nur über die offizielle WhatsApp Business API bereit. Die inoffizielle WhatsApp-(Web)-Verbindung empfängt diese nicht – aufgrund der Funktionsweise sind über diese Verbindung keine Anzeigen-Klickdaten verfügbar.

Wenn Ihnen eine lückenlose Anzeigen-Attribution wichtig ist, führen Sie Ihre Click-to-WhatsApp-Kampagnen über eine Nummer durch, die mit der offiziellen WhatsApp API verbunden ist.

Click-to-Instagram- und Click-to-Messenger-Anzeigen

Anzeigen, die ein Instagram-DM- oder Messenger-Chat-Fenster öffnen, werden auf die gleiche Weise erfasst, und zwar für die Facebook-Seite und das Instagram-Konto, die Sie mit der Karte Instagram & Messenger verbunden haben. Wenn jemand über eine dieser Anzeigen einen Chat startet, erhält der Kontakt ein ad_referral, wobei channel auf instagram oder messenger, source_type auf ad und source_id auf die Anzeigen-ID gesetzt ist. Dadurch können Sie die Anzeige hinter jedem Kontakt nachvollziehen und die Kosten pro Buchung je Anzeige ermitteln.

Einige Unterschiede zu WhatsApp:

  • Es gibt kein ctwa_clid; dieses Feld ist leer. Meta stellt diesen Klick-Identifikator nur für WhatsApp aus.
  • headline ist der Titel der Anzeige, wenn Meta ihn sendet, und source_url ist der Link zum Bild oder Video der Anzeige, sofern vorhanden. body ist leer.
  • Wenn der Kontakt ursprünglich über eine Anzeige kam und später einen Chat über eine andere Anzeige startet, zeigt ad_referral die neuere Anzeige an.
  • Messenger-Anzeigenkontakte enthalten die Anzeige ab dem 14. Oktober 2026. Kontakte, die vor diesem Datum über eine Messenger-Anzeige kamen, haben kein ad_referral, da die Anzeigendetails damals nicht erfasst wurden und nachträglich nicht ausgefüllt werden können.
  • Messenger-Chats, die durch Tippen auf die Schaltfläche Get Started (Loslegen) der Seite gestartet werden, werden nicht erfasst. Entfernen Sie die Schaltfläche „Get Started“ von Ihrer Seite (Meta Business Suite, Posteingang-Einstellungen), damit Nutzer den Chat durch Tippen beginnen und die Anzeige bei ihrer ersten Nachricht erfasst wird.

First-Touch-Verhalten

Die Empfehlung wird bei der ersten Nachricht erfasst, die ein Kontakt aus einer Anzeige heraus sendet. Wenn derselbe Kontakt später auf eine andere Anzeige klickt und dieser neuere Klick eine Klick-ID enthält, wird die gespeicherte ad_referral aktualisiert, damit die Klick-ID für das Reporting aktuell bleibt. Empfehlungen durch organische Beiträge (die keine ctwa_clid haben) überschreiben niemals eine zuvor erfasste Klick-ID einer bezahlten Anzeige.

Übermittlung der Daten an Meta oder Google Ads

Your AI Connector erfasst die Attributionsdaten und stellt sie bereit. Für Anzeigen, die Nutzer zuerst auf Ihre eigene Website leiten, kann Your AI Connector Ergebnisse für Sie an Meta senden, sobald ein Tag angewendet wird: siehe Ergebnisse an Meta senden. Bei Click-to-WhatsApp-Anzeigen leiten Sie die Daten mithilfe von Webhooks und einem Automatisierungstool weiter.

Das ad_referral-Objekt ist im Abschnitt contact der ausgehenden Webhook-Ereignisse enthalten (zum Beispiel „Neue Nachricht“, „Kontakt fortgesetzt“, „Kontakt-Tags aktualisiert“ und Analyseereignisse wie „Termin gebucht“).

Ein typisches Setup für eine lückenlose Attribution:

  1. Ein Lead klickt auf Ihre „Click-to-WhatsApp“-Anzeige und schreibt Ihnen. Your AI Connector speichert ad_referral (einschließlich ctwa_clid) beim Kontakt.
  2. Während der Lead den Prozess durchläuft – Anruf gebucht, Kunde geworden, verloren – markieren Sie dieses Ergebnis (siehe „Den Funnel-Status übertragen“ weiter unten).
  3. Ein Webhook wird an Ihr Automatisierungstool (Zapier, Make oder Pabbly) gesendet, das sowohl das Ergebnis als auch die ctwa_clid des Kontakts enthält.
  4. Ihr Automatisierungstool ruft die Conversions API von Meta (unter Verwendung von action_source = business_messaging und der ctwa_clid) oder Google Ads (Offline Conversion Import / Enhanced Conversions for Leads) auf, um die Conversion zu melden.

Auf diese Weise erfahren Meta und Google, welche Anzeigen echte Ergebnisse erzielt haben, und optimieren diese entsprechend.

Funnel-Stufe übertragen

Um eine Conversion zu melden, benötigen Sie normalerweise zwei Dinge: die Click-ID (wird automatisch erfasst) und das Ergebnis (das Sie festlegen). Der zuverlässigste Weg, ein Ergebnis zuzuordnen, sind Tags, da das Anwenden eines Tags den contact_tags_updated-Webhook auslöst – und diese Payload enthält die ad_referral des Kontakts. (Das Entfernen eines Tags löst ihn nicht aus; siehe Kontakt-Tags aktualisiert.)

Sie können Tags automatisch anwenden:

  • Lassen Sie Ihren KI-Agenten den Kontakt während des Gesprächs taggen – richten Sie Auto-Tagging-Regeln in der Konfiguration des Agenten ein. So funktioniert das Muster „eine Landingpage pro Anzeige → eine Einstiegsnachricht → ein Tag“, wenn Sie die Quelle selbst kennzeichnen möchten.
  • Oder taggen Sie manuell über „Chats“ oder die „Kontakte“-Seite.

Wann immer sich ein relevanter Tag ändert, wird der Webhook mit der angehängten Click-ID ausgelöst, bereit zur Weiterleitung als Conversion.

Die Webhook-URL wird direkt am Tag selbst festgelegt, und zwar im Tab Tags des Editors des KI-Agenten, dem der Kontakt zugewiesen ist, nicht in den Einstellungen. Jeder Tag erhält eine eigene URL, und sie können alle auf denselben Endpunkt verweisen, falls Sie alles an einem zentralen Ort empfangen möchten.

Lesen einer bereits verpassten Click-ID

ad_referral wird auch von der API sowohl bei GET /v1/contacts/{id} (als adReferral) als auch beim Kontaktlisten-Endpunkt (als ad_referral) zurückgegeben. Wenn Ihr Empfänger also ausgefallen war oder Sie einen Abgleich im Nachhinein durchführen, können Sie die Click-ID auslesen, anstatt auf den nächsten Webhook zu warten. Kontakte, die eingegangen sind, bevor die Click-ID bei ihnen gespeichert wurde, haben hier null – der Wert kann nur aus der eingehenden Nachricht selbst erfasst werden, daher gibt es nichts, was nachträglich ausgefüllt werden könnte.

Einschränkungen

  • Nur offizielle WhatsApp-API-Verbindung (keine inoffizielle Web-Verbindung).
  • Die integrierte Funktion Ergebnisse an Meta senden übermittelt die vom Website-Skript aufgezeichneten Klickdaten; sie sendet nicht die ctwa_clid von Click-to-WhatsApp-Anzeigen. Für diese sowie für Google Ads leiten Sie die Daten über Zapier/Make/Pabbly weiter. Wenn Sie eine native Integration wünschen, informieren Sie den Support unter hi@youraiconnector.com.
  • Die Attribution wird ab dem Zeitpunkt der Aktivierung erfasst. Sie kann nicht für Konversationen nachgetragen werden, die zuvor stattgefunden haben.

Nächste Schritte