Tool personalizzati: collegare l'agente AI ai tuoi sistemi con un webhook
Crea tool personalizzati che l'agente AI attiva in conversazione: URL webhook, parametri, header, cooldown, test e cronologia degli invii.
I Tool Personalizzati permettono all'agente AI di attivare le tue automazioni durante le conversazioni: quando si verifica la condizione che descrivi, Recontatto invia una chiamata webhook al tuo sistema (un gestionale, un CRM, uno strumento come Make o Zapier) con i dati raccolti in chat. Se vuoi, la risposta del tuo sistema torna all'AI, che la usa per rispondere al cliente.
Apri la pagina Tool Personalizzati
Vai su Agenti AI → Tool Personalizzati e clicca Crea tool. Se non ne hai ancora, la pagina mostra Nessun tool personalizzato.
Compila la configurazione base
Nella scheda Configurazione Base inserisci:
- Nome tool, ad esempio «Verifica stato ordine»;
- Descrizione trigger: è il testo che dice all'AI quando attivare il tool. Sii specifico: descrivi condizioni ed eccezioni e, se serve, cita per nome gli altri tool per coordinarli;
- URL Webhook, che deve usare HTTPS;
- Header personalizzati, per esempio una chiave di autenticazione richiesta dal tuo sistema;
- Cooldown (minuti), cioè il tempo minimo tra due attivazioni per lo stesso telefono (0 = nessun limite), e Timeout (secondi).
Decidi se il tool restituisce dati
Attiva Restituisce dati all'AI se vuoi che il corpo della risposta del webhook venga passato all'AI, che potrà usarlo nella risposta al cliente (ad esempio la disponibilità di un appuntamento o lo stato di una pratica). Se lo lasci disattivato, il tool invia i dati e basta.
Aggiungi i parametri
Nella scheda Parametri clicca Aggiungi parametro per ogni dato da inviare. Per ciascuno indica Nome (solo lettere, numeri e underscore), Tipo (String, Number o Boolean), se è Obbligatorio e la Sorgente:
- Generato dall'AI: l'AI estrae il valore dalla conversazione seguendo la Descrizione per l'AI che scrivi tu;
- Valore statico: un valore fisso, sempre uguale;
- Campo cliente: un dato del contatto, come telefono, nome, cognome o email.
Testa il webhook
Prima di usarlo in produzione premi Testa. Il test invia dati di esempio (i valori statici sono reali, quelli dinamici e AI usano segnaposto) e ti mostra Stato, Latenza, Risposta e Payload inviato, così verifichi che il tuo sistema riceva tutto correttamente.
Attiva il tool sull'agente
Salva il tool e assicurati che sia attivo con il suo interruttore (un tool spento appare come Inattivo). Poi apri Agenti AI → Strumenti e permessi e, nel riquadro dei tool personalizzati, attiva l'interruttore del tool per l'agente che deve usarlo. Ricordati di premere Salva.
Controlla gli invii recenti
Nella scheda di ogni tool trovi Invii recenti, con l'esito e il numero di tentativi di ogni chiamata. Gli invii non riusciti vengono ritentati automaticamente. Le attivazioni compaiono anche nel Registro attività come Tool personalizzato.
Ogni chiamata include gli header X-Recontatto-Delivery-Id e X-Recontatto-Tool-Name: usali nel tuo sistema per riconoscere il tool e per ignorare eventuali invii duplicati.
Eliminando un tool cancelli definitivamente anche tutta la cronologia degli invii, e l'azione non può essere annullata. Se vuoi solo sospenderlo, disattivalo con il suo interruttore.