# Moduli Lead di Facebook Stai pubblicando annunci Facebook per acquisire lead? Questa integrazione invia automaticamente quei lead in Your AI Connector in modo da poterli ricontattare tramite WhatsApp, SMS o qualsiasi altro canale collegato, senza muovere un dito. Funziona collegando Facebook Lead Ads a Your AI Connector tramite una piattaforma di automazione (come Pabbly, Zapier o Make). Queste piattaforme fungono da ponte tra Facebook e Your AI Connector, trasferendo le informazioni sui lead dall'uno all'altro utilizzando l'API (un metodo che consente a diversi software di scambiare dati automaticamente). --- ## Prerequisiti Prima di iniziare, assicurati di avere: - Accesso a **Facebook Ads Manager** con autorizzazione alla creazione di Lead Ads. - **Un account** con una chiave API attiva (generane una in **Impostazioni → Integrazioni → Chiave API** — vedi [Accesso API](api-access.md) per i passaggi esatti). - **Un account su una piattaforma di automazione** — Pabbly Connect, Zapier o Make (Integromat). Questa guida utilizza Pabbly come esempio, ma i passaggi sono simili su qualsiasi piattaforma. - **Una lista contatti** in Your AI Connector in cui verranno aggiunti i nuovi lead — vedi [Organizzazione di liste e contatti](../get-started/list-and-contact-management.md). --- ## Panoramica L'integrazione funziona in tre fasi: 1. Un potenziale cliente compila il tuo modulo Facebook Lead Form. 2. La tua piattaforma di automazione rileva il nuovo lead e invia le informazioni a Your AI Connector automaticamente (utilizzando due chiamate API). 3. Your AI Connector crea il contatto e lo aggiunge alla lista specificata. Da quel momento, un broadcast, una campagna o un Agente AI che hai assegnato gestirà il resto, che si tratti di un messaggio di benvenuto basato sull'IA, una sequenza drip o un follow-up manuale. --- ## Passaggio 1: Crea il tuo modulo Lead di Facebook 1. Apri **Facebook Ads Manager**. 2. Crea una nuova campagna con l'obiettivo **Lead**. 3. A livello di annuncio, scegli **Modulo istantaneo** come metodo di acquisizione lead. 4. Crea il tuo modulo con i campi di cui hai bisogno. Come minimo, includi: - **Nome** - **Numero di telefono** (con prefisso internazionale) - Facoltativo: Cognome, email 5. Pubblica l'annuncio o salva il modulo come bozza per i test. --- ## Passaggio 2: Testa il modulo Lead Prima di collegare l'automazione, invia un lead di prova: 1. In Ads Manager, vai al tuo modulo Lead. 2. Fai clic su **Anteprima** e compila il modulo con dati di prova. 3. Conferma che il lead di prova appaia nel tuo **Facebook Lead Center** (sotto Strumenti di pubblicazione sulla tua Pagina Facebook, o in Ads Manager sotto "Lead"). Questa voce di test verrà utilizzata per configurare la mappatura dei campi nella tua piattaforma di automazione. --- ## Passaggio 3: Configura l'automazione ### Connetti Facebook Lead Ads come trigger 1. Accedi alla tua piattaforma di automazione (Pabbly, Zapier o Make). 2. Crea un nuovo workflow / scenario / zap. 3. Imposta il **trigger** su "Facebook Lead Ads - New Lead". 4. Connetti il tuo account Facebook e seleziona la Pagina e il Modulo Lead. 5. Recupera il lead di test per confermare che la connessione funzioni e per mappare i campi. ### Configura la chiamata API 1: Crea contatto Aggiungi un passaggio di azione con una richiesta HTTP / Webhook / API: - **Metodo:** `POST` - **URL:** `https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY` - **Intestazioni:** ``` Content-Type: application/json ``` - **Corpo (JSON):** ```json { "firstName": "{{first_name}}", "lastName": "{{last_name}}", "phone": "{{phone_number}}", "email": "{{email}}" } ``` Sostituisci `{{placeholders}}` con le mappature dei campi effettive dal tuo passaggio di trigger. ::: warning **Importante:** Il numero di telefono deve includere il prefisso internazionale (ad esempio, `+1` per gli Stati Uniti o `+31` per i Paesi Bassi). Se il modulo per i lead raccoglie il numero di telefono senza prefisso internazionale, aggiungi un passaggio di formattazione nella tua automazione per anteporlo. ::: La risposta dell'API restituisce l'ID del nuovo contatto in `data.contactId`. Salva quel valore: ti servirà per il passaggio successivo. > **Puoi saltare la seconda chiamata.** `POST /v1/contacts` accetta anche `listId` (una lista) o `listIds` (diverse) nel corpo della creazione, il che aggiunge il nuovo contatto a quelle liste nella stessa richiesta. Usa la versione in due passaggi qui sotto solo se la tua piattaforma di automazione richiede che il contatto esista prima di decidere quale lista utilizzare. ### Configura la chiamata API 2: Aggiungi contatto alla lista Aggiungi un secondo passaggio di azione: - **Metodo:** `POST` - **URL:** `https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY` - **Intestazioni:** ``` Content-Type: application/json ``` - **Corpo (JSON):** ```json { "contactId": "{{contact_id_from_previous_step}}", "listId": "YOUR_LIST_ID" } ``` Sostituisci `YOUR_LIST_ID` con l'ID effettivo della tua lista contatti (vedi [Trovare l'ID della tua lista](#finding-your-list-id) qui sotto) e mappa `contactId` al `data.contactId` restituito dalla prima chiamata API. --- ## Trovare l'ID della tua lista 1. In Your AI Connector, fai clic su **Contatti**, quindi sulla scheda **Liste**. 2. Apri il menu della riga ("⋯") accanto alla lista desiderata e fai clic su **Copia ID lista**. Vedi [Organizzazione di liste e contatti](../get-started/list-and-contact-management.md) per la guida completa alla pagina Liste. --- ## Passaggio 4: Testa il flusso di lavoro completo 1. Invia un altro lead di prova tramite il tuo modulo Facebook (o riproduci il lead di prova esistente nella tua piattaforma di automazione). 2. Controlla Your AI Connector per confermare che: - Il **contatto** sia stato creato con nome, numero di telefono ed email corretti. - Il contatto sia stato **aggiunto alla lista corretta**. 3. Se hai un broadcast, una campagna o un Agente AI impostato per inviare messaggi automaticamente a quella lista, conferma che si attivi come previsto. --- ## Riferimento dati Di seguito sono riportati esempi dei dati inviati e ricevuti durante l'integrazione. ### Crea contatto - Richiesta ```json POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY { "firstName": "Jane", "lastName": "Smith", "phone": "+15551234567", "email": "jane@example.com" } ``` ### Crea contatto - Risposta ```json { "success": true, "data": { "message": "Successfully created new contact", "contactId": "abc123xyz", "listsAdded": [] } } ``` ### Aggiungi contatto alla lista - Richiesta ```json POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY { "contactId": "abc123xyz", "listId": "LIST_ID" } ``` --- ## Suggerimenti - **Gestione dei duplicati:** se esiste già un contatto con lo stesso numero di telefono, la chiamata di creazione restituisce `{"success": false, "error_code": 409}` e non restituisce il contatto esistente. Crea una ramificazione su `error_code` (lo stato HTTP è 200) e cerca il contatto con `GET /v1/contacts?phoneNumber=...` prima della chiamata di aggiunta alla lista. - **Moduli multipli:** crea flussi di lavoro di automazione separati per diversi moduli di lead, ognuno dei quali punta a una lista diversa e a un broadcast, una campagna o un agente AI diverso. - **Notifiche di errore:** configura la tua piattaforma di automazione per avvisarti se una chiamata API fallisce, in modo da non perdere i lead. --- ## Prossimi passi - [Passaggio da Campagne a Broadcast & Agenti](../moving-from-campaigns.md) — configura qualcosa per inviare messaggi automaticamente ai nuovi lead. - [Accesso API](api-access.md) — documentazione API completa per integrazioni avanzate. - [Webhook](webhooks.md) — ricevi notifiche quando i contatti vengono creati o etichettati.