Conversions API per Click-to-WhatsApp Ads: guida tecnica 2026

SendSeven Team, Editorial Team

Come integrare Meta Conversions API (CAPI) con i Click-to-WhatsApp Ads tramite webhook e REST API di SendSeven. I 4 eventi chiave, hashing SHA-256, ctwa_clid e deduplica con il Pixel.

Il Pixel di Meta funziona sul browser dell'utente — ma con iOS 14+, blocchi degli ad blocker e Safari ITP, si stima che il 30-50% degli eventi non venga tracciato. CAPI risolve questo problema inviando gli eventi lato server, dove i blocchi non si applicano.

CAPI vs Pixel: perché CAPI vince per i CTWA

Per i CTWA, il confronto è ancora più netto che per il web:

• Il Pixel non può tracciare le conversazioni WhatsApp — WhatsApp è un'app mobile, non un browser. Non esiste una pagina web dove il Pixel possa caricarsi dopo una conversione.
• CAPI può tracciare ogni fase della conversazione — perché gli eventi vengono inviati dal tuo sistema (o da SendSeven) direttamente all'API di Meta, indipendentemente dal dispositivo dell'utente.
• Attribuzione più precisa con ctwa_clid — il parametro di attribuzione specifico per i CTWA permette a Meta di collegare la conversione all'annuncio che ha generato la conversazione.

ctwa_clid: il parametro di attribuzione dei CTWA

Quando un utente clicca su un CTWA, Meta aggiunge automaticamente un parametro ctwa_clid al primo messaggio inviato dall'utente. Questo identificatore univoco permette di attribuire la conversazione (e le conversioni successive) all'annuncio specifico.

Come recuperare ctwa_clid con SendSeven:

// Webhook SendSeven - evento: message.received
{
  "event": "message.received",
  "data": {
    "message_id": "wamid.xxx",
    "from": "+39XXXXXXXXXX",
    "text": "Ciao, ho visto il vostro annuncio...",
    "referral": {
      "source_url": "https://fb.com/ads/...",
      "source_type": "ad",
      "source_id": "AD_ID",
      "ctwa_clid": "ARAkLgU8Gt3...",  // ← Questo è il parametro da salvare
      "headline": "Testo del titolo",
      "body": "Testo del corpo"
    }
  }
}

Salva ctwa_clid nel tuo CRM associato al numero di telefono dell'utente. Ti servirà per tutti gli eventi CAPI successivi della stessa conversazione.

I 4 eventi CAPI per i CTWA

Per ottimizzare le campagne CTWA, invia questi 4 eventi a Meta tramite CAPI:

1. Lead — al primo messaggio dell'utente (conversazione avviata). Evento di qualità «top of funnel».
2. Contact — quando il lead è qualificato (es. bot ha raccolto nome, esigenza, localizzazione).
3. InitiateCheckout — quando viene inviato un preventivo o un'offerta concreta.
4. Purchase — quando la vendita è chiusa (es. conferma appuntamento, ordine confermato).

Meta usa questi eventi per ottimizzare la distribuzione degli annunci verso utenti con probabilità più alta di convertire in Purchase, non solo in Lead.

Hashing SHA-256 per i dati utente

Prima di inviare dati utente a Meta tramite CAPI, devi applicare l'hashing SHA-256. Questo è obbligatorio per: numero di telefono, email, nome, cognome.

const crypto = require('crypto');

function hashData(data) {
  return crypto
    .createHash('sha256')
    .update(data.trim().toLowerCase())
    .digest('hex');
}

// Esempio: numero di telefono italiano
// Formato: country code + numero (senza spazi, trattini, parentesi)
const phone = '+39XXXXXXXXXX';
const phoneNormalized = phone.replace(/[^0-9]/g, ''); // '39XXXXXXXXXX'
const phoneHashed = hashData(phoneNormalized);

Implementazione: webhook SendSeven → CAPI

L'architettura consigliata: webhook SendSeven → tuo server → Meta CAPI. SendSeven non ha attualmente una integrazione CAPI con interfaccia grafica — il routing degli eventi avviene tramite i webhook di SendSeven e la REST API di SendSeven per recuperare i metadati della conversazione.

const express = require('express');
const crypto = require('crypto');
const https = require('https');

const app = express();
app.use(express.json());

const META_PIXEL_ID = 'IL_TUO_PIXEL_ID';
const META_ACCESS_TOKEN = 'IL_TUO_ACCESS_TOKEN';
const META_CAPI_URL = `https://graph.facebook.com/v19.0/${META_PIXEL_ID}/events`;

function hashData(data) {
  return crypto.createHash('sha256').update(data.trim().toLowerCase()).digest('hex');
}

async function sendCapiEvent(eventName, phone, ctwaClid, eventId) {
  const phoneNorm = phone.replace(/[^0-9]/g, '');
  
  const payload = {
    data: [{
      event_name: eventName,
      event_time: Math.floor(Date.now() / 1000),
      event_id: eventId, // per la deduplica con il Pixel
      action_source: 'other',
      user_data: {
        ph: [hashData(phoneNorm)],
        client_user_agent: 'WhatsApp/2.x'
      },
      custom_data: {
        ctwa_clid: ctwaClid
      }
    }],
    access_token: META_ACCESS_TOKEN
  };
  
  const response = await fetch(META_CAPI_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
  
  return response.json();
}

// Webhook SendSeven: nuovo messaggio in arrivo
app.post('/webhook/sendseven', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'message.received' && data.referral?.ctwa_clid) {
    const { from: phone, referral: { ctwa_clid } } = data;
    
    // Evento Lead: primo messaggio da un CTWA
    await sendCapiEvent('Lead', phone, ctwa_clid, `lead_${data.message_id}`);
    
    // Salva ctwa_clid nel DB per gli eventi successivi
    await db.saveCtwaClid(phone, ctwa_clid);
  }
  
  res.json({ status: 'ok' });
});

// Webhook per evento qualificazione completata (inviato manualmente o dal bot)
app.post('/webhook/qualified', async (req, res) => {
  const { phone, event_id } = req.body;
  const ctwaClid = await db.getCtwaClid(phone);
  
  if (ctwaClid) {
    await sendCapiEvent('Contact', phone, ctwaClid, event_id);
  }
  
  res.json({ status: 'ok' });
});

app.listen(3000);

Deduplica Pixel + CAPI

Se usi sia il Pixel che CAPI (configurazione consigliata per la massima copertura), Meta deduplicò automaticamente gli eventi duplicati tramite event_id. Regole:

• Usa lo stesso event_id per lo stesso evento sia nel Pixel che in CAPI.
• Gli eventi devono arrivare entro 48 ore l'uno dall'altro per essere deduplicati.
• Se usi solo CAPI (senza Pixel) per i CTWA, non hai bisogno della deduplica.

Test e verifica con Meta Events Manager

Dopo l'implementazione, verifica gli eventi nel Meta Events Manager → Strumento di test degli eventi. Passi:

1. Vai su Meta Events Manager → seleziona il tuo Pixel → scheda «Strumento di test eventi».
2. Copia il codice di test e aggiungilo al payload CAPI come parametro test_event_code.
3. Invia una richiesta CAPI di test e verifica che l'evento appaia in tempo reale nel pannello.
4. Controlla la colonna «Qualità evento» — punta a «Alta» (match rate >90%).

Il match rate basso (sotto 70%) indica che i dati utente (numero di telefono) non coincidono con i profili Meta. Verifica il formato di normalizzazione del numero di telefono (deve includere il prefisso internazionale senza il «+», es. «39XXXXXXXXXX» per l'Italia).

FAQ

CAPI è obbligatorio per i CTWA?

No, non è tecnicamente obbligatorio. Puoi fare campagne CTWA con solo il Meta Pixel o anche senza tracking. Tuttavia, senza CAPI l'attribuzione delle conversioni WhatsApp è quasi impossibile (il Pixel non può tracciare eventi in app), il che significa che Meta non può ottimizzare la distribuzione degli annunci verso gli utenti più propensi all'acquisto.

Quanto è difficile implementare CAPI?

Con uno sviluppatore o con esperienza in Node.js/Python, l'implementazione base richiede 2-4 ore. La parte più delicata è la normalizzazione e l'hashing del numero di telefono. Usa sempre il prefisso internazionale senza «+» (es. «39XXXXXXXXXX» per l'Italia) e verifica il match rate nel Meta Events Manager prima di andare in produzione.

Posso usare CAPI con qualsiasi piattaforma WhatsApp Business API?

Sì, qualsiasi BSP (come la WhatsApp Business API di SendSeven) che espone webhook sugli eventi di messaggistica può essere usato. Con SendSeven, i webhook per i messaggi in arrivo (message.received) sono configurabili nella sezione Impostazioni → Sviluppatori → Webhook.

Articoli correlati:

• Guida completa ai CTWA per l'Italia 2026
• Creare CTWA in 7 passi
• Costo e ROI dei CTWA in Italia