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”.

Stai invece pubblicando annunci che rimandano a una pagina del tuo sito web con un pulsante WhatsApp? Consulta Attribuzione dei clic sugli annunci per WhatsApp.

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’identificatore 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 su 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: whatsapp, instagram o messenger.
captured_at Quando il referral è stato registrato per la prima volta sul contatto.

Puoi vederlo senza alcuna configurazione: la pagina del contatto mostra un’etichetta Proveniente da annuncio sotto il nome (passaci sopra il mouse per i dettagli dell’annuncio), anche il pannello del contatto accanto alla chat lo mostra e l’Attività del contatto inizia con il tocco sull’annuncio. Puoi leggerlo anche tramite webhook e API (vedi sotto). Non è una colonna 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.

Lead che arrivano senza numero di telefono

Alcune persone che ti inviano un messaggio da un annuncio hanno il numero di telefono nascosto da WhatsApp. In tal caso, Meta fornisce un ID privato per la persona invece di un numero, e il contatto viene creato con un campo telefono vuoto. È normale che sia così. Le risposte, le risposte dell’IA e i follow-up automatici raggiungono comunque la persona, perché Your AI Connector si rivolge a lei tramite quell’ID.

Lascia vuoto il campo telefono in un contatto di questo tipo. Non inserire il tuo numero aziendale: un messaggio non può essere inviato da un numero a se stesso, quindi il successivo follow-up automatico fallirebbe e il contatto verrebbe messo in pausa. Your AI Connector ora rifiuta di salvare uno dei tuoi numeri collegati come numero di telefono di un contatto. Se in seguito la persona condivide il proprio numero o ti invia un altro messaggio con il numero visibile, questo verrà compilato automaticamente.

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.

Annunci Click-to-Instagram e Click-to-Messenger

Gli annunci che aprono un DM di Instagram o una chat di Messenger vengono registrati allo stesso modo, sulla Pagina Facebook e sull’account Instagram che hai collegato con la scheda Instagram & Messenger. Quando qualcuno avvia una chat da uno di quegli annunci, il contatto ottiene un ad_referral con channel impostato su instagram o messenger, source_type impostato su ad e source_id impostato sull’ID dell’annuncio. Questo ti fornisce l’annuncio dietro ogni contatto, così puoi calcolare il costo per prenotazione per annuncio.

Alcune differenze rispetto a WhatsApp:

  • Non c’è alcun ctwa_clid; quel campo è vuoto. Meta emette quell’identificativo di clic solo per WhatsApp.
  • headline è il titolo dell’inserzione quando Meta lo invia, e source_url è il link all’immagine o al video dell’inserzione, quando presente. body è vuoto.
  • Se il contatto proviene inizialmente da un’inserzione e successivamente avvia una chat da un’inserzione diversa, ad_referral mostra l’inserzione più recente.
  • I contatti provenienti da inserzioni Messenger includono l’inserzione a partire dal 14 ottobre 2026. I contatti provenienti da un’inserzione Messenger prima di tale data non hanno alcun ad_referral, poiché i dettagli dell’inserzione non venivano registrati all’epoca e non possono essere inseriti in seguito.
  • Le chat di Messenger che iniziano con un tocco sul pulsante Inizia della Pagina non vengono registrate. Rimuovi il pulsante Inizia dalla tua Pagina (Meta Business Suite, impostazioni Posta in arrivo) in modo che le persone avviino la chat scrivendo, così l’inserzione verrà registrata al loro primo messaggio.

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. Per gli annunci che indirizzano le persone prima al tuo sito web, Your AI Connector può inviare i risultati a Meta per te quando viene applicato un tag: consulta Inviare i risultati a Meta. Per gli annunci Click-to-WhatsApp, 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’editor dell’agente IA a cui è assegnato il contatto, non in Impostazioni. Ogni tag ottiene il proprio URL e possono tutti 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 API ufficiale di WhatsApp (non la connessione web non ufficiale).
  • La funzione integrata Inviare i risultati a Meta invia i dati dei clic registrati dallo script del sito web; non invia l’ ctwa_clid degli annunci Click-to-WhatsApp. Per questi, e per Google Ads, inoltri i dati tramite Zapier/Make/Pabbly. Se desideri un’integrazione nativa, contatta l’assistenza all’indirizzo hi@youraiconnector.com.
  • L’attribuzione viene acquisita in futuro, dal momento in cui questa funzione è attiva. Non può essere applicata retroattivamente alle conversazioni avvenute in precedenza.

Prossimi passi