> ## Documentation Index > Fetch the complete documentation index at: https://support.callin.io/llms.txt > Use this file to discover all available pages before exploring further. # Strumenti > Crea strumenti (webhook) in Callin e usali dal campo Conversation Prompt del tuo agente per inviare o consultare dati in tempo reale durante una chiamata. ## Panoramica Gli **strumenti** (webhook) permettono al tuo agente Callin di connettersi a sistemi esterni **in tempo reale** mentre conversa con un utente. Detto in modo semplice: uno strumento è un’**azione automatica** che l’agente può eseguire per **chiedere** o **inviare** informazioni a un altro sistema (per esempio, il tuo CRM) senza interrompere la conversazione. Con uno strumento, il tuo agente può: * **Inviare dati** che l’utente comunica durante la chiamata (per esempio: nome, email, telefono, motivo). * **Consultare dati** in un sistema esterno (per esempio: stato, disponibilità, verifica). * **Attivare automazioni** su piattaforme esterne (CRM, ticket, messaggistica, flussi, ecc.). In Callin, il funzionamento corretto segue sempre questo ordine: 1. **Creare lo strumento** nella sezione **Tools**. 2. **Assegnare lo strumento** all’agente in **AI Agents**. 3. **Indicare nel campo Conversation Prompt** quando deve eseguirsi e cosa deve fare l’agente con il risultato. Se manca uno di questi 3 passaggi, lo strumento non verrà eseguito come ti aspetti. *** ## Prima di iniziare (concetti in 60 secondi) * **Tool / Strumento**: connessione che permette all’agente di “parlare” con un altro sistema (per esempio, un CRM). * **URL**: l’indirizzo a cui Callin invia la richiesta. * **GET**: si usa per **consultare** un’informazione (“Questo contatto esiste?”). * **POST**: si usa per **inviare** un’informazione (“Crea questo lead con questi dati.”). * **Body parameters**: i **dati** che l’agente invierà (email, telefono, nome, ecc.). * **Required**: campi **obbligatori**. Se ne manca uno, il risultato può essere incompleto o il flusso può fallire. > Se il tuo utente non è tecnico, tieni a mente questa idea: **lo strumento crea la connessione**, e il **Conversation Prompt decide quando usarlo e con quali dati**. *** ## Passo 1 — Creare uno strumento (webhook) Per creare uno strumento in Callin: 1. Entra in **Tools** nel pannello di Callin. 2. Clicca su **+ Add Tool**. 3. Compila i campi principali: * **Name**\ Usa un nome corto, chiaro e stabile. Consiglio: **verbo + obiettivo**.\ Esempi: `verifica-contatto-crm`, `crea-lead-crm`, `invia-link-registrazione`. * **Description**\ Spiega **a cosa serve** e soprattutto **quando va usato** (in quale momento della chiamata).\ Esempio: “Verificare se il contatto esiste nel CRM solo dopo aver confermato email e telefono.” * **Method** * Usa **GET** se devi **consultare** informazioni. * Usa **POST** se devi **inviare** informazioni (il caso più comune quando l’agente raccoglie dati e li invia). * **URL**\ Incolla l’URL HTTPS della tua API o il webhook della tua piattaforma esterna. > Assicurati che l’URL sia **HTTPS** e accessibile pubblicamente. Se l’endpoint non è accessibile, lo strumento non funzionerà. ### Configurare i “Body parameters” (se usi POST) Se lo strumento invia informazioni (POST), definisci esattamente quali dati invierà: 1. Vai su **Body parameters**. 2. Clicca su **Add property**. 3. Configura ogni campo: * **Type**: il tipo di dato (testo, numero, vero/falso, ecc.). * **Identifier**: il nome esatto del campo atteso dal tuo endpoint (per esempio: `email`, `telefono`, `nome_completo`). * **Required**: attivalo se il campo è obbligatorio. * **Description**: spiega cosa rappresenta e il formato atteso (per esempio: “Telefono in formato internazionale” o “Email valida”). > Consiglio pratico: se contrassegni un campo come **Required**, il tuo agente deve essere obbligato (tramite il Conversation Prompt) a **chiederlo e confermarlo** prima di eseguire lo strumento. Altrimenti, il webhook riceverà dati incompleti o il flusso fallirà. ### Header e autenticazione (se applicabile) Se il tuo endpoint richiede autenticazione (per esempio, un token o una chiave), dovrai configurarla seguendo esattamente i requisiti della tua API (quali header servono e con quali valori). 4. Clicca su **Save** per salvare lo strumento. *** ## Passo 2 — Assegnare lo strumento a un agente Creare lo strumento non è sufficiente. Devi assegnarlo all’agente: 1. Vai su **AI Agents**. 2. Seleziona l’agente che vuoi configurare. 3. Nell’editor dell’agente, scorri fino alla sezione **Tools**. 4. Clicca su **+ Add Tool**. 5. Seleziona lo strumento e salva. **Controllo rapido:**\ Se lo strumento appare nell’elenco dell’agente, è assegnato correttamente. Se non appare, l’agente non potrà eseguirlo. *** ## Passo 3 — Indicare come usare lo strumento nel “Conversation Prompt” Questo è il passaggio più importante. L’agente eseguirà lo strumento solo se il **Conversation Prompt** gli indica chiaramente: * **Quali dati deve raccogliere** prima di eseguirlo (campi obbligatori). * **Come confermare quei dati** (per ridurre errori). * **Quando** deve eseguirlo (momento esatto della chiamata). * **Cosa deve dire subito dopo** averlo eseguito (incluse frasi esatte se il tuo processo lo richiede). * **Cosa NON deve fare** (per evitare di mischiare flussi o agire troppo presto). ### Regola chiave (per utenti non tecnici) Se non dici all’agente **“quando”** e **“a quali condizioni”** usare lo strumento, l’agente potrebbe: * usarlo troppo presto, * usarlo con dati incompleti, * oppure non usarlo mai. *** ## Esempio 1 — Connettersi a un CRM in tempo reale (verifica + creazione) Questo esempio copre un caso molto comune: l’agente parla con un utente e, **prima di continuare**, controlla nel CRM se il contatto esiste già. Se non esiste, crea un lead e continua la chiamata. ### Strumenti usati in questo esempio **Strumento 1: Verifica\_Contatto\_CRM**\ **Obiettivo:** controllare se il contatto esiste già nel CRM.\ **Quando si usa:** subito dopo aver confermato **email + telefono**.\ **Risultato atteso:** “trovato / non trovato” e, se trovato, dati di base (per esempio: nome e stato). **Strumento 2: Crea\_Lead\_CRM**\ **Obiettivo:** creare un lead se il contatto non esiste.\ **Quando si usa:** solo se la verifica precedente restituisce “non trovato”.\ **Dati minimi consigliati:** nome, email, telefono, motivo. ### Condizioni per eseguire gli strumenti (molto importante) * L’agente **non deve** eseguire nessuno strumento finché: * l’**email** non è confermata (ripetuta e confermata dall’utente), * e il **telefono** non è confermato (ripetuto e confermato dall’utente). * Se l’utente esita o corregge un dato, l’agente deve **aggiornarlo e riconfermarlo** prima di continuare. ### Cosa scrivere nel Conversation Prompt (testo inventato e facile da adattare) **Obiettivo del flusso:**\\ 1. Raccogliere dati base → 2) Confermarli → 3) Verificare nel CRM → 4) Se non trovato, creare lead → 5) Continuare la conversazione. **Istruzioni chiare per l’agente (esempio):** * Durante la chiamata, raccogli e conferma questi dati: * **Nome e cognome** * **Email** * **Telefono** * **Motivo** (una frase breve) * Per confermare: * Ripeti l’email e chiedi: “È corretto?” * Ripeti il telefono e chiedi: “È corretto?” * Solo quando email e telefono sono confermati: * Esegui **Verifica\_Contatto\_CRM**. * Se il risultato indica che il contatto **esiste**: * Di’ all’utente: “Perfetto, vedo già la tua scheda. Continuiamo.” * Non inventare dettagli. Se lo stato arriva nel risultato, puoi citarlo in modo neutro. * Se il risultato indica che il contatto **non esiste**: * Di’ all’utente: “Perfetto, non ti trovo ancora. Ti registro ora e continuiamo.” * Esegui **Crea\_Lead\_CRM** con i dati confermati. * Dopo la creazione, conferma: “Fatto, sei registrato. Continuiamo con il prossimo passo.” * Se lo strumento fallisce o non restituisce risposta: * Non dire informazioni tecniche. * Di’: “Non sono riuscito a verificarlo in questo momento. Continuiamo e, se serve, lo rivediamo alla fine.” * Non ripetere gli strumenti in loop. ### Come apparirebbe in una chiamata (esempio di conversazione) **Agente:** “Perfetto. Per aiutarti, ho bisogno di alcuni dati rapidi. Qual è il tuo nome e cognome?”\ **Utente:** “Laura Martin.”\ **Agente:** “Grazie, Laura. Qual è la tua email?”\ **Utente:** “[laura.martin@esempio.com](mailto:laura.martin@esempio.com)”\ **Agente:** “Perfetto. Ho capito: laura punto martin chiocciola esempio punto com. È corretto?”\ **Utente:** “Sì.”\ **Agente:** “Ottimo. Qual è il tuo numero di telefono?”\ **Utente:** “Sei sei cinque, uno due tre, quattro cinque sei.”\ **Agente:** “Perfetto. Confermo il telefono: 665 123 456. È corretto?”\ **Utente:** “Sì.”\ **Agente:** “Grazie. Un’ultima cosa: in una frase, qual è il motivo della chiamata?”\ **Utente:** “Voglio informazioni sui piani.”\ **Agente:** “Perfetto. Controllo se sei già registrata e poi continuiamo.” (L’agente esegue **Verifica\_Contatto\_CRM**) * **Se trovato:**\ **Agente:** “Perfetto, vedo già la tua scheda. Continuiamo con le informazioni sui piani.” * **Se non trovato:**\ **Agente:** “Perfetto, non ti trovo ancora. Ti registro ora e continuiamo.” (L’agente esegue **Crea\_Lead\_CRM**) **Agente:** “Fatto, sei registrata. Ora sì: passiamo alle informazioni sui piani.” ### Regole di sicurezza del flusso (per evitare errori) * Non eseguire strumenti con dati non confermati. * Non inventare risultati del CRM: usa solo ciò che arriva come risposta. * Non riprovare lo strumento più volte se fallisce: continua e proponi di rivederlo dopo. * Non mischiare flussi: prima CRM (verifica/creazione), poi il resto del processo. *** ## Esempio 2 — Inviare link nel momento giusto (durante la chiamata e alla fine) Di seguito trovi un esempio completo (inventato) con due strumenti: un link principale durante la chiamata e un link di accesso alla fine. **Strumento 1: Invia\_Link\_Registrazione (Link A)**\ **Obiettivo:** inviare il link principale in cui l’utente completa tutto il processo principale.\ **Quando si usa:** durante la chiamata, solo quando l’utente conferma di voler continuare e email + telefono sono confermati. **Il Link A include (dentro il link stesso):** 1. Registrazione iniziale (dati obbligatori) 2. Verifica/conferma delle informazioni 3. Selezione del piano o opzione 4. Configurazione del pagamento (se applicabile) 5. Accettazione termini o firma (se applicabile) 6. Caricamento documenti (se applicabile) 7. Conferma finale **Condizioni per eseguire “Invia\_Link\_Registrazione”:** * L’utente dice chiaramente che vuole continuare. * L’email è confermata (ripetuta e confermata dall’utente). * Il telefono è confermato (ripetuto e confermato dall’utente). **Frase esatta dopo aver inviato il Link A (esempio inventato):** > “Apri il link che ti abbiamo appena inviato e scorri fino alla sezione ‘Registrazione iniziale’. Compila i tuoi dati e dimmi quando sei pronto per continuare.” **Regole durante la chiamata (molto importante):** * Non chiedere all’utente di uscire dal Link A per fare passaggi altrove durante la chiamata. * Non chiedere di accedere a un portale separato mentre sta completando il processo principale. * Guida l’utente passo dopo passo, sempre dal punto in cui si trova. *** **Strumento 2: Invia\_Link\_Portal (Link B)**\ **Obiettivo:** inviare il link di accesso al portale sicuro per controllare lo stato più tardi.\ **Quando si usa:** solo alla fine della chiamata. **Frasi esatte dopo aver inviato il Link B (esempio inventato):** > “Ecco il link per accedere al tuo portale sicuro.”\ > “Ti abbiamo anche inviato email con i dati di accesso.”\ > “Se non le trovi, usa la ricerca nelle email e scrivi il nome della nostra azienda per localizzarle.” **Chiusura finale (esempio inventato):** > “Grazie per il tuo tempo. Se hai bisogno di aiuto in qualsiasi passaggio, siamo disponibili ad assisterti.” *** ## Passo 4 — Testare lo strumento prima di usarlo in produzione Prima di usare lo strumento con i clienti, verifica che: * La richiesta venga eseguita correttamente. * I campi arrivino con il nome previsto (Identifier). * I campi obbligatori (Required) siano sempre presenti. * L’endpoint risponda in modo rapido e coerente. Una buona pratica è testare il webhook con un URL di ispezione temporaneo (per vedere cosa arriva) e poi con il tuo endpoint reale. ### Checklist rapida (30 secondi) * Lo strumento è creato e salvato in **Tools**. * Lo strumento è assegnato all’agente in **AI Agents > il tuo agente > Tools**. * Il **Conversation Prompt** specifica chiaramente: * quali dati chiedere, * come confermarli, * quando eseguire lo strumento, * e cosa dire subito dopo. *** ## Errori comuni e come risolverli | Problema | Causa probabile | Soluzione | | ------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Lo strumento non viene eseguito | Non è assegnato all’agente | Vai su **AI Agents > il tuo agente > Tools** e aggiungilo | | Non arriva nulla all’endpoint | Endpoint non accessibile o URL errato | Verifica che l’URL sia **HTTPS** e accessibile pubblicamente | | Mancano campi | “Identifier / Required” definiti male o l’agente non li raccoglie | Controlla **Body parameters** e adatta il **Conversation Prompt** per richiedere e confermare i dati | | Si esegue nel momento sbagliato | Il Conversation Prompt non definisce condizioni chiare | Specifica regole tipo “solo alla fine”, “solo dopo conferma di email e telefono” | *** ## Consiglio finale Per ottenere un risultato stabile: * Inizia con uno strumento semplice. * Definisci pochi campi obbligatori all’inizio. * Nel Conversation Prompt, sii esplicito su: * **condizioni di esecuzione**, * **ordine del flusso**, * **frasi esatte** (se applicabili), * **e divieti** (cosa l’agente non deve fare).