Creare strumenti

​

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

---

​

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