Your AI Connector Docs

Attribuzione degli annunci Click-to-WhatsApp

Se pubblichi annunci Meta (Facebook/Instagram) “Click to WhatsApp”, Your AI Connector può dirti da quale annuncio proviene ogni lead di WhatsApp e fornirti l’identificatore di clic di Meta necessario per segnalare le conversioni reali a Meta. Questo consente alle tue campagne pubblicitarie di ottimizzarsi per vendite e prenotazioni effettive, non solo per “persone che hanno avviato una chat”.

Cosa viene acquisito

Quando qualcuno tocca un annuncio Click-to-WhatsApp e invia un messaggio alla tua attività, Meta allega informazioni di riferimento nascoste a quel primo messaggio. Your AI Connector le legge automaticamente e le memorizza sul contatto. Nessuna configurazione, nessuna impostazione: avviene semplicemente.

Le informazioni acquisite vengono memorizzate sul contatto come ad_referral e contengono:

Campo Che cos’è
ctwa_clid L’identificativo del clic di Meta. Questo è il valore che invii alla Conversions API di Meta per attribuire una conversione a valle all’esatto clic sull’annuncio. Vuoto per i referral da post organici (vedi sotto).
source_id L’ID dell’annuncio (o del post) su cui la persona ha fatto clic.
source_type O ad (un annuncio a pagamento Click-to-WhatsApp) o post (un post organico di Facebook/Instagram).
source_url Il link associato al contenuto dell’annuncio.
headline Il testo del titolo dell’annuncio.
body Il testo del corpo dell’annuncio.
channel Il canale su cui è arrivato il referral (attualmente sempre whatsapp).
captured_at Quando il referral è stato registrato per la prima volta sul contatto.

Puoi visualizzarlo nel pannello di visualizzazione rapida di un contatto se hai configurato un campo personalizzato per esso, oppure leggerlo direttamente tramite webhook e API (vedi sotto) — non è separato come campo etichettato a sé stante nella tabella Contatti.

Una cosa che il payload non ti dice: su quale dei tuoi numeri è arrivata la conversazione. Non contiene alcun ID pagina o ID account WhatsApp Business. Con un singolo numero non è un problema; se gestisci diversi numeri su pagine Facebook differenti, dovrai mapparli dal tuo lato.

Su quale connessione funziona

Funziona solo sulla connessione ufficiale WhatsApp API. Meta fornisce le informazioni di riferimento strutturate (incluso ctwa_clid) solo tramite l’API ufficiale di WhatsApp Business. La connessione WhatsApp (web) non ufficiale non le riceve: non sono disponibili dati sui clic degli annunci su quella connessione, per come è progettata.

Quindi, se l’attribuzione degli annunci a ciclo chiuso è importante per te, gestisci le tue campagne Click-to-WhatsApp tramite un numero collegato via API ufficiale di WhatsApp.

Comportamento al primo contatto

Il referral viene acquisito al primo messaggio che un contatto invia da un annuncio. Se lo stesso contatto fa clic in seguito su un annuncio diverso e quel clic più recente contiene un identificativo di clic, il valore ad_referral memorizzato viene aggiornato in modo che l’ID del clic rimanga aggiornato per la reportistica. I referral da post organici (che non hanno un ctwa_clid) non sovrascrivono mai un ID di clic di un annuncio a pagamento acquisito in precedenza.

Trasferimento dei dati in Meta o Google Ads

Your AI Connector acquisisce i dati di attribuzione e li espone, ma attualmente non invia nativamente le conversioni a Meta o Google per te. Inoltri i dati utilizzando webhook e uno strumento di automazione.

L’oggetto ad_referral è incluso nella sezione contact degli eventi webhook in uscita (ad esempio Nuovo messaggio, Contatto ripreso, Tag contatto aggiornati ed eventi di analisi come Appuntamento prenotato).

Una tipica configurazione a ciclo chiuso:

  1. Un lead fa clic sul tuo annuncio Click-to-WhatsApp e ti invia un messaggio. Your AI Connector registra ad_referral (incluso ctwa_clid) sul contatto.
  2. Man mano che il lead avanza (ha prenotato una chiamata, è diventato un cliente, è stato perso), contrassegni quel risultato (vedi “Gestione della fase del funnel” di seguito).
  3. Un webhook si attiva verso il tuo strumento di automazione (Zapier, Make o Pabbly) portando sia il risultato che l’ctwa_clid del contatto.
  4. Il tuo strumento di automazione chiama le API di conversione di Meta (utilizzando action_source = business_messaging e ctwa_clid) o Google Ads (Importazione conversioni offline / Conversioni avanzate per i lead) per segnalare la conversione.

In questo modo Meta e Google imparano quali annunci hanno prodotto risultati reali e si ottimizzano di conseguenza.

Gestione della fase del funnel

Per segnalare una conversione solitamente sono necessarie due cose: l’id del clic (acquisito automaticamente) e il risultato (che imposti tu). Il modo più affidabile per allegare un risultato è tramite i tag, poiché l’applicazione di un tag attiva il webhook contact_tags_updated — e quel payload include l’id del contatto ad_referral. (La rimozione di un tag non lo attiva; vedi Tag contatto aggiornati.)

Puoi applicare i tag automaticamente:

  • Lascia che il tuo Agente AI tagghi il contatto durante la conversazione: imposta regole di tagging automatico nella configurazione dell’agente. È così che funziona il modello “una landing page per annuncio → un messaggio di ingresso → un tag” se vuoi etichettare tu stesso la fonte.
  • Oppure tagga manualmente dalle Chat o dalla pagina Contatti.

Ogni volta che un tag rilevante cambia, il webhook si attiva con l’id del clic allegato, pronto per essere inoltrato come conversione.

L’URL del webhook viene impostato sul tag stesso, nella scheda Tag dell’agente (o della campagna) a cui appartiene il contatto, non nelle Impostazioni. Ogni tag ottiene il proprio URL e tutti possono puntare allo stesso endpoint se desideri un unico punto in cui ricevere tutto.

Leggere un click id che ti sei già perso

ad_referral viene restituito anche dall’API sia su GET /v1/contacts/{id} (come adReferral) che sull’endpoint dell’elenco contatti (come ad_referral), quindi se il tuo ricevitore era inattivo, o se stai effettuando una riconciliazione a posteriori, puoi leggere il click id invece di attendere il webhook successivo. I contatti arrivati prima che il click id venisse registrato su di essi hanno null qui: il valore può essere acquisito solo dal messaggio in arrivo, quindi non c’è nulla da inserire retroattivamente.

Limitazioni

  • Solo connessione ufficiale alle API di WhatsApp (non la connessione web non ufficiale).
  • Non sono ancora presenti integrazioni native con un clic per Meta CAPI o Google Ads: i dati vengono inoltrati tramite Zapier/Make/Pabbly. Se desideri un’integrazione nativa, segnalalo al supporto all’indirizzo hi@youraiconnector.com.
  • L’attribuzione viene acquisita a partire dal momento in cui questa funzione è attiva. Non può essere applicata retroattivamente alle conversazioni avvenute in precedenza.

Prossimi passi