Funzioni personalizzate #

Le funzioni personalizzate consentono al tuo bot AI di connettersi ad altri sistemi durante le conversazioni dal vivo. Invece di dire “Controllo e ti faccio sapere”, il bot può cercare lo stato di un ordine, verificare l’inventario o creare un record nel tuo CRM (sistema di gestione delle relazioni con i clienti - il software che utilizzi per tracciare lead e clienti, come HubSpot o Salesforce) - tutto in tempo reale, mentre il cliente attende.

Funzioni personalizzate vs Webhook #

Questo è il punto di confusione più comune, quindi vale la pena chiarirlo prima di costruire qualsiasi cosa.

Quando scegliere cosa: Se devi solo comunicare a un altro sistema che è successo qualcosa, usa un webhook - un messaggio automatizzato unidirezionale inviato a un altro sistema (vedi Impostazioni → Integrazioni → Webhook). Se il bot deve apprendere qualcosa da un altro sistema prima di continuare la conversazione, usa una funzione personalizzata.

Esempi di ciò che sbloccano le funzioni personalizzate #

Poiché la risposta viene reinserita nella conversazione, le funzioni personalizzate rendono possibili operazioni che i webhook semplicemente non possono fare:

• Ricerca dell’inventario Shopify o WooCommerce in tempo reale — Prima di fare un preventivo a un cliente, il bot controlla le scorte in tempo reale e risponde “Sì, ne abbiamo 12 nella taglia M” invece di “faccia controllare e le faccio sapere”.
• Prezzi dinamici da un foglio Google — Il tuo team di vendita aggiorna i prezzi in un foglio; il bot legge l’ultima riga a metà conversazione e cita il prezzo corrente senza che nessuno debba toccare la configurazione dell’IA.
• Agente di richiamata Voice-AI — Quando il bot qualifica un lead, attiva un agente vocale (ad esempio, un chiamante basato su ElevenLabs) per richiamare il lead entro pochi minuti e conferma al cliente “ottimo, si aspetti una chiamata nei prossimi 5 minuti”.
• PDF di preventivo personalizzato, generato e inviato via email durante la chat — Il bot raccoglie i requisiti, chiama il tuo generatore di preventivi, ottiene un URL del PDF e dice al cliente “Ho appena inviato il suo preventivo via email, controlli la posta in arrivo”.

Cosa possono fare le funzioni personalizzate? #

Pensa alle funzioni personalizzate come a un modo per dare al tuo bot superpoteri che vanno oltre la semplice chat. Ecco esempi reali:

• Tracciamento ordini - Un cliente chiede “Dov’è il mio ordine?” e il bot controlla il tuo sistema di e-commerce e risponde con lo stato della spedizione e il link di tracciamento
• Controllo inventario - “Lo avete nella taglia 10?” Il bot controlla il tuo sistema di magazzino e fornisce una risposta in tempo reale
• Aggiornamenti CRM - Quando il bot qualifica un lead, crea o aggiorna automaticamente un record in HubSpot, Salesforce o qualsiasi altro CRM
• Generazione preventivi - Il bot raccoglie i requisiti del cliente e genera un preventivo personalizzato dal tuo sistema di prezzi
• Prenotazioni - Il bot crea un appuntamento nel tuo sistema di prenotazione esterno
• Verifica sconti - “Questo codice coupon è valido?” Il bot controlla e conferma
• Ricerca account - Un cliente abituale viene riconosciuto automaticamente e i dettagli del suo account vengono recuperati

Il cliente non vede mai cosa succede dietro le quinte. Sperimenta semplicemente un bot in grado di rispondere alle sue domande con informazioni reali e aggiornate.

Come funzionano le funzioni personalizzate (versione semplice) #

Ecco cosa succede quando una funzione personalizzata viene attivata durante una conversazione:

1. Il cliente chiede qualcosa che richiede dati in tempo reale (ad es. “Dov’è il mio ordine?”)
2. Il bot riconosce che deve utilizzare una funzione personalizzata per rispondere
3. Il bot raccoglie eventuali informazioni mancanti dal cliente (ad es. “Qual è il numero del tuo ordine?”)
4. La piattaforma invia una richiesta al tuo sistema (il tuo sito web, CRM o qualsiasi altro strumento) con i dettagli pertinenti
5. Il tuo sistema risponde con i dati (ad es. stato dell’ordine, numero di tracciamento, data di consegna)
6. Il bot legge la risposta e crea una replica naturale: “Il tuo ordine ORD-4582 è stato spedito e dovrebbe arrivare entro venerdì!”

Quanto costa una chiamata a una funzione personalizzata #

Ogni chiamata a una funzione personalizzata viene fatturata in base al livello di qualità AI del tuo Agente:

Configurazione di una funzione personalizzata (passo dopo passo) #

1. Nella barra laterale principale, sotto AI Studio, fai clic su Custom Functions.

2. Fai clic sul pulsante verde + Add Function (o New function) in alto a destra.

L’elenco delle funzioni personalizzate visualizza una tabella con le seguenti colonne:

Questo rende facile scansionare le tue funzioni a colpo d’occhio e trovare quella di cui hai bisogno.

Passaggio 1: Assegna un nome e una descrizione #

Suggerimento: Sii molto specifico nella descrizione e nello scopo. Più sei chiaro su quando la funzione dovrebbe essere utilizzata, più affidabile sarà il bot nell’usarla al momento giusto.

Passaggio 2: Configura la connessione #

Devi indicare all’app dove inviare la richiesta:

Quale metodo scegliere:

Se non sei sicuro di quale utilizzare, verifica con il tuo sviluppatore o consulta la documentazione del sistema a cui ti stai connettendo. GET (per le ricerche) e POST (per la creazione di record) sono i più comuni.

Passaggio 3: Aggiungi le intestazioni di autenticazione #

La maggior parte dei sistemi richiede l’autenticazione per accettare le richieste. Aggiungi le intestazioni necessarie:

Suggerimento di sicurezza: utilizza una chiave API dedicata con autorizzazioni limitate. Non utilizzare credenziali di livello amministratore.

Dove trovare le chiavi API: controlla le impostazioni o la sezione sviluppatori del sistema a cui ti stai connettendo (ad esempio, il tuo CRM, la piattaforma di e-commerce o lo strumento di prenotazione).

Passaggio 4: Definisci l’input (cosa invia il bot) #

I parametri di input sono le informazioni che il bot raccoglie dalla conversazione e invia al tuo sistema.

Per ogni parametro, specifica:

Tipi di parametri disponibili:

Ogni parametro ha anche un campo opzionale Percorso del corpo della richiesta. Normalmente un parametro viene inviato come campo di primo livello nel corpo della richiesta (o come valore di una stringa di query, per il tipo query_param). Se l’endpoint lo richiede annidato — ad esempio {"order": {"id": "ORD-123"}} — imposta il percorso su order.id e la piattaforma anniderà il valore per te.

Esempio: per una ricerca dello stato dell’ordine, potresti definire:

• order_number (string, obbligatorio): “Il numero d’ordine del cliente. Di solito inizia con ORD- seguito da cifre. Chiedi al cliente questo dato se non lo ha menzionato.”
• email (string, facoltativo): “L’indirizzo email del cliente per un’ulteriore verifica. Necessario solo se il numero d’ordine da solo non trova una corrispondenza.”

Cosa riceve automaticamente il tuo sistema #

Oltre ai parametri di input definiti, la piattaforma include automaticamente dati di sistema in ogni richiesta. Il tuo endpoint li riceve in un campo system:

Questo è utile se il tuo sistema deve identificare il contatto, verificare quale campagna ha attivato la funzione o comportarsi in modo diverso durante i test.

Non ti servono i dati di sistema? Attiva l’opzione Salta dati di sistema nel generatore di funzioni. Il bot invierà quindi solo i parametri di input definiti, senza dati sul contatto o sulla campagna. Utilizza questa opzione se il tuo endpoint rifiuta campi imprevisti o se desideri semplicemente un payload più leggero.

Passaggio 5: Testalo, poi lascia che il bot legga la risposta #

Normalmente non è necessario mappare affatto i campi di risposta. Una volta che l’endpoint risponde, il bot legge l’intera risposta JSON e utilizza la Descrizione e lo Scopo (Azione AI) della funzione — oltre alla descrizione di ogni parametro — per capire cosa è importante e presentarlo in modo naturale. Una descrizione chiara della funzione stessa (“Recupera lo stato attuale di un ordine cliente, incluse le informazioni di spedizione e il tracciamento”) è più efficace di una mappatura campo per campo.

Se l’endpoint restituisce una risposta di grandi dimensioni e vuoi che il bot veda solo alcuni valori specifici, apri la sezione Mappatura della risposta (compressa per impostazione predefinita, appena sopra Test). Ogni riga seleziona un campo di primo livello dalla risposta: Campo di risposta è il nome del campo nella risposta JSON della tua API, e Campo di output è il nome con cui il bot lo riceve. Con almeno una riga compilata, il bot riceve solo i valori mappati invece dell’intero corpo della risposta. Lascia la sezione vuota per mantenere il comportamento predefinito di risposta completa.

Prima di salvare, utilizza la sezione Test in fondo al generatore per inviare la richiesta esattamente come configurata e vedere la risposta reale, senza uscire dall’app:

La risposta che vedi qui è la risposta grezza dell’endpoint. Se hai configurato la Mappatura della risposta qui sopra, il bot in una chat reale riceverà solo quei campi mappati — il test mostra sempre la risposta grezza completa in modo che tu possa vedere cosa è disponibile per la mappatura. Se qualcosa sembra non corretto (nomi di campo imprevisti, nidificazione extra), correggilo sul tuo endpoint o modifica la tua mappatura.

Assegnazione di funzioni a un Agente #

Dopo aver creato una funzione personalizzata, devi indicare a ciascun Agente quali funzioni può utilizzare:

1. Apri l’Agente sotto AI Studio → Agenti AI.
2. Vai alla scheda Abilità AI. (Per una campagna che mantiene ancora le proprie impostazioni AI direttamente anziché tramite un Agente separato, lo stesso elenco appare invece nel passaggio Abilità AI della campagna stessa.)
3. Vedrai un elenco di ogni funzione personalizzata che hai creato. Attiva ogni funzione che vuoi che il bot di questo Agente sia in grado di chiamare.
4. Fai clic su Salva modifiche in basso. Le selezioni vengono applicate solo una volta salvate.

Solo le funzioni assegnate sono disponibili al bot per quell’Agente. Questo impedisce al bot di utilizzare accidentalmente funzioni non pertinenti.

Test delle funzioni personalizzate #

Prima di andare online, esegui dei test approfonditi:

1. Esegui il test integrato - Utilizza la sezione Test all’interno del generatore di funzioni (vedi sopra) per un controllo rapido senza uscire dall’app: inserisci valori realistici e fai clic su Esegui test.
2. Testa direttamente l’endpoint del tuo sistema - Per la lista di controllo completa qui sotto, uno strumento dedicato come Postman (o il tuo sviluppatore) scava più a fondo di un singolo Esegui test.
3. Testa in Prova - Simula una conversazione in cui il cliente chiede qualcosa che dovrebbe attivare la funzione.
4. Controlla la risposta - Assicurati che il bot legga e presenti correttamente i dati.
5. Testa gli scenari di errore - Cosa succede se il cliente fornisce un numero d’ordine non valido? Cosa succede se il tuo sistema è temporaneamente fuori servizio?

Quando il test restituisce 401 o 403 #

Un errore 401 o 403 significa che il tuo endpoint ha ricevuto la richiesta ma l’ha rifiutata. L’indizio principale è che non appare nulla nei tuoi log — la maggior parte degli strumenti rifiuta una chiamata non autorizzata prima ancora di avviare il flusso di lavoro, quindi non c’è nulla da vedere dalla tua parte e sembra che la richiesta non sia mai arrivata.

Quasi sempre si tratta di una mancata corrispondenza nell’autenticazione: il tuo endpoint richiede un tipo di credenziale e la funzione ne sta inviando una diversa. Verifica che l’intestazione aggiunta nel Passaggio 3 sia esattamente quella prevista dal tuo sistema.

La versione più comune di questo problema è un webhook protetto con Basic Auth (n8n, Make e la maggior parte degli strumenti self-hosted offrono questa opzione tramite una casella di controllo sul webhook stesso) mentre la funzione invia un’intestazione segreta personalizzata come X-My-Secret. La Basic Auth accetta solo un’intestazione Authorization, quindi un’intestazione personalizzata viene ignorata e la chiamata viene rifiutata. Hai due opzioni:

• Disattiva la Basic Auth sul webhook e verifica invece l’intestazione personalizzata all’interno del flusso di lavoro.
• Mantieni attiva la Basic Auth e aggiungi un’intestazione Authorization alla funzione il cui valore sia la parola Basic seguita dal tuo username:password codificato in base64.

Entrambe le soluzioni funzionano: assicurati solo che entrambe le parti concordino.

Quando il test restituisce 404 #

L’URL dell’endpoint è errato o il flusso di lavoro non è pubblicato. In n8n nello specifico, ogni webhook ha un URL di Test e un URL di Produzione separati, e quello di Test rimane in ascolto solo mentre l’editor è aperto. Copia l’URL di Produzione e assicurati che il flusso di lavoro sia attivo.

Visualizzazione degli errori in Prova e Chat #

Quando l’IA richiama una funzione personalizzata durante una conversazione e la chiamata fallisce — credenziali errate, endpoint non raggiungibile, timeout — la conversazione ora lo mostra: un indicatore rosso “(nome funzione) non riuscita” appare nel thread, sia nella scheda Prova dell’agente che nelle conversazioni reali in Chat. Fai clic sull’indicatore per espandere i dettagli: il codice di stato restituito dal tuo endpoint e il corpo della risposta, che di solito sono sufficienti per capire esattamente cosa correggere (un 401 con un messaggio “unauthorized” indica l’intestazione di autenticazione, un timeout significa che il tuo endpoint ha impiegato più di 30 secondi).

Anche le chiamate riuscite mostrano un indicatore: fai clic su di esso per vedere cosa ha effettivamente restituito il tuo endpoint. Questo è il modo più rapido per eseguire il debug di un’integrazione end-to-end: effettua la conversazione di test in Prova, quindi fai clic sull’indicatore della funzione per vedere il risultato reale della richiesta senza lasciare la pagina.

Esempio completo: Ricerca stato ordine #

Ecco un esempio completamente configurato che puoi utilizzare come modello:

Informazioni di base:

• Nome: check_order_status
• Descrizione: “Recupera lo stato attuale di un ordine cliente, incluse le informazioni di spedizione e il tracciamento”
• Azione AI: “Chiama questa funzione quando un cliente chiede informazioni sullo stato del proprio ordine, su dove si trovi il pacco o su quando arriverà. Chiedi sempre prima il numero d’ordine.”

Connessione:

• URL: https://api.mystore.com/orders/lookup
• Metodo: POST

Intestazioni:

• Authorization: Bearer sk_live_abc123
• Content-Type: application/json

Parametri di input:

• order_number (testo, obbligatorio): “Il numero d’ordine fornito dal cliente”
• customer_email (testo, facoltativo): “Email del cliente per un’ulteriore verifica”

Nessuna mappatura della risposta necessaria — con una Descrizione e un’Azione AI chiare già impostate sopra, il bot legge qualsiasi JSON restituito dal tuo endpoint (stato, numero di tracciamento, data di consegna, articoli) e capisce come parlarne.

Come appare la conversazione:

Cliente: Ehi, dov’è il mio ordine?

Bot: Ciao! Sarei felice di controllare il tuo ordine. Potresti condividere con me il numero d’ordine?

Cliente: È ORD-78234

Bot: Fammi controllare per te…

Il tuo ordine ORD-78234 è stato spedito ed è in viaggio! La data di consegna stimata è il 10 marzo. Puoi tracciare il tuo pacco qui: https://tracking.example.com/1Z999AA1

C’è qualcos’altro in cui posso aiutarti?

Esempio completo: Stato dell’ordine Shopify #

Se il negozio utilizza Shopify, non è necessario uno sviluppatore per creare un endpoint di ricerca: il sistema di Shopify può rispondere direttamente alle domande sugli ordini. (Per domande su prodotti e scorte in un negozio Shopify non serve affatto una funzione personalizzata: connetti invece il server integrato del negozio — vedi Connettere un negozio Shopify.)

Per prima cosa, crea un token di accesso in Shopify. Shopify ha modificato questa procedura nel corso del 2026: le app non possono più essere create all’interno dell’amministrazione di Shopify e la nuova schermata delle app fornisce un Client ID e un Client secret invece di un token già pronto. I passaggi seguenti trasformano questi dati in un token permanente. Prevedi circa dieci minuti, una volta per negozio. (Se il negozio ha già un’app creata con il vecchio metodo, il token esistente continuerà a funzionare: passa direttamente alla funzione personalizzata qui sotto.)

1. Vai alla Dashboard per sviluppatori Shopify su dev.shopify.com, apri la tua organizzazione e clicca su App → Crea app. Dalle un nome come Order lookup.
2. Assegna all’app l’autorizzazione read_orders, rilascia una versione e installa l’app sul negozio.
3. Apri le Impostazioni dell’app e aggiungi l’indirizzo web del negozio (ad esempio https://www.yourstore.com/) agli URL di reindirizzamento consentiti. Salva.
4. Sempre in Impostazioni, copia l’ID cliente e il Segreto cliente.
5. In un browser in cui hai effettuato l’accesso all’amministrazione Shopify di quel negozio, apri l’indirizzo sottostante, sostituendo il nome del negozio, l’ID cliente e l’indirizzo di reindirizzamento con i tuoi: https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345 Approva la schermata che appare. Il browser approderà al tuo indirizzo di reindirizzamento e la barra degli indirizzi ora conterrà code= seguito da un lungo valore: copia quel valore. È valido solo per un paio di minuti, quindi passa subito al passaggio successivo.
6. Scambia quel codice con il token, operazione che puoi fare all’interno di Your AI Connector. Nel generatore di funzioni personalizzate, imposta Metodo su POST e URL su https://YOUR-STORE.myshopify.com/admin/oauth/access_token, aggiungi tre parametri di input di testo denominati client_id, client_secret e code, quindi clicca su Test, inserisci i tre valori ed eseguilo. La risposta contiene access_token: quello è il tuo token permanente. Copialo in un posto sicuro, quindi svuota il generatore e configura la funzione reale qui sotto.

Quindi configura la funzione personalizzata:

Informazioni di base:

• Nome: check_shopify_order
• Descrizione: “Cerca un ordine nel sistema Shopify del negozio e ne restituisce lo stato, il tracciamento e gli articoli”
• Azione IA: “Chiama questa funzione quando un cliente chiede informazioni sullo stato dell’ordine o sulla consegna. Chiedi sempre prima il numero dell’ordine.”

Connessione:

• URL: https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any — sostituisci YOUR-STORE con il nome .myshopify.com del negozio (questo indirizzo utilizza il dominio tecnico di Shopify, non il dominio personalizzato del negozio)
• Metodo: GET

Intestazioni:

• X-Shopify-Access-Token: shpat_... (il token ottenuto in precedenza)

Parametri di input:

• name (query_param, obbligatorio): “Il numero dell’ordine del cliente esattamente come appare nella conferma d’ordine, incluso il simbolo # — ad esempio #1001. Chiedilo al cliente se non lo ha menzionato.”

Nessuna mappatura della risposta necessaria — il bot legge l’ordine restituito (stato del pagamento, stato dell’evasione, tracciamento, articoli) e risponde in modo naturale.

Buono a sapersi: un token creato in questo modo può visualizzare gli ordini degli ultimi 60 giorni — sufficienti per le domande di assistenza quotidiane, ma non per uno storico completo degli ordini.

Esempio completo: Prenotare un appuntamento #

Informazioni di base:

• Nome: create_booking
• Descrizione: “Crea un nuovo appuntamento nel nostro sistema di prenotazione”
• Azione AI: “Usa questa funzione dopo aver confermato data, ora e dettagli di contatto con il cliente. Non chiamarla finché il cliente non conferma esplicitamente di voler prenotare.”

Connessione:

• URL: https://booking.mycompany.com/api/appointments
• Metodo: POST

Parametri di input:

• date (testo, obbligatorio): “Data dell’appuntamento nel formato AAAA-MM-GG”
• time (testo, obbligatorio): “Ora dell’appuntamento nel formato HH:MM”
• name (testo, obbligatorio): “Nome completo del cliente”
• phone (testo, obbligatorio): “Numero di telefono del cliente”
• service_type (testo, obbligatorio): “Il tipo di servizio da prenotare”

Esempio completo: Aggiungere un iscritto alla newsletter al proprio CRM #

Un modello molto comune: il bot termina la risposta, propone la newsletter, il contatto risponde con il proprio indirizzo email e tale indirizzo deve finire immediatamente nel proprio strumento di email marketing. La maggior parte dei CRM (FluentCRM, ActiveCampaign, MailerLite, Brevo e altri) accetta un semplice POST proprio per questo scopo, quindi non è necessaria alcuna piattaforma di automazione intermedia.

Questo esempio utilizza FluentCRM su WordPress. La struttura è la stessa per qualsiasi altro strumento che fornisca un “webhook in entrata” o un endpoint per “creare un iscritto”.

Per prima cosa, ottieni l’URL dal tuo CRM. In WordPress, apri FluentCRM → Impostazioni → Webhook in entrata e crea un webhook. Scegli l’elenco, i tag e lo stato di iscrizione che i nuovi contatti dovrebbero ricevere, quindi copia l’URL del webhook generato. Tutto ciò che imposti qui viene applicato automaticamente, quindi il bot deve solo inviare l’indirizzo email.

Quindi configura la funzione personalizzata:

Informazioni di base:

• Nome: add_newsletter_subscriber
• Descrizione: “Aggiunge una persona alla nostra lista newsletter utilizzando l’indirizzo email fornito nella chat”
• Azione AI: “Utilizza questa funzione nel momento in cui il contatto accetta di iscriversi alla newsletter e fornisce il proprio indirizzo email. Non chiamarla prima che abbiano effettivamente fornito un indirizzo e non chiamarla due volte per la stessa persona.”

Connessione:

• URL: l’URL del webhook copiato dal tuo CRM
• Metodo: POST

Parametri di input:

• email (stringa, obbligatorio): “L’indirizzo email fornito dal contatto nella conversazione”
• first_name (stringa, facoltativo): “Il nome del contatto, se menzionato”

Ignora dati di sistema: attiva questa opzione. Il tuo CRM ha bisogno solo dei campi sopra indicati e un payload più snello evita errori da parte di strumenti che rifiutano campi imprevisti.

Mappatura della risposta: non necessaria in questo caso. Non è necessario che torni nulla affinché il bot possa continuare.

Non dimenticare di attivare la funzione per l’Agente che gestisce la conversazione (vedi Assegnazione di funzioni a un Agente). Questo è il motivo più comune per cui una funzione costruita correttamente non viene mai attivata.

Suggerimenti per funzioni personalizzate affidabili #

1. Assicurati che le richieste ripetute siano sicure. Se la stessa richiesta viene inviata accidentalmente due volte, non dovrebbe creare record duplicati. Problemi di rete possono occasionalmente causare questo inconveniente.

2. Restituisci messaggi di errore chiari. Se qualcosa va storto lato sistema, restituisci un errore leggibile dall’utente. Il bot lo inoltrerà al cliente in modo appropriato.

3. Mantieni i tempi di risposta sotto i 10 secondi. Se il tuo sistema impiega più tempo, valuta di restituire prima una rapida conferma.

4. Gestisci credenziali scadute o non valide. Se la tua chiave API scade, assicurati che il messaggio di errore sia chiaro in modo che il bot sappia di dover avvisare un operatore umano invece di riprovare.

5. Scrivi descrizioni dettagliate. L’IA utilizza le tue descrizioni per capire quando chiamare la funzione e come estrarre le informazioni corrette dalla conversazione. Descrizioni vaghe portano a errori.

6. Testa con conversazioni reali. La funzione Prova (Try Out) è ottima per i test iniziali, ma monitora le tue prime conversazioni dal vivo per assicurarti che tutto funzioni con le richieste reali dei clienti.

7. Mantieni i log lato tuo. Chiedi al tuo sviluppatore di registrare le richieste provenienti dall’app in modo da poter risolvere rapidamente eventuali problemi.

8. Utilizza un URL finale pubblico. L’URL della tua funzione deve essere un indirizzo web pubblico (HTTP/HTTPS). Gli indirizzi interni, localhost e di rete privata vengono rifiutati per motivi di sicurezza e la piattaforma non segue i reindirizzamenti: punta la funzione direttamente all’URL finale, non a uno che reindirizza ad esso.

Limiti di esecuzione #

Ogni funzione personalizzata dispone di una sezione opzionale Limiti di esecuzione nella parte inferiore dell’editor. Controlla con quale frequenza l’IA può eseguire la funzione e se un risultato precedente può essere riutilizzato. Tutto ciò che si trova qui è facoltativo: lascia tutto vuoto e la funzione si comporterà esattamente come prima.

Funzione di sola lettura. Attiva questa opzione se la tua funzione legge solo i dati (una ricerca di azioni, un controllo prezzi, una ricerca dello stato dell’ordine) e non crea o modifica mai nulla. Quando un temporaneo problema di rete interrompe l’IA a metà risposta, la piattaforma può ritentare in sicurezza il turno di conversazione invece di lasciare il cliente senza una risposta. Abilitala solo se la funzione non scrive mai nulla: una funzione che crea record deve rimanere disattivata, in modo che un nuovo tentativo non possa mai eseguirla accidentalmente due volte.

Fornisci risultato memorizzato nella cache su chiamate ripetute. Quando l’IA chiama nuovamente la funzione con gli stessi input (ad esempio, il cliente pone la stessa domanda due volte), il risultato precedente viene riutilizzato invece di chiamare nuovamente il tuo endpoint. I risultati memorizzati nella cache vengono conservati fino a 24 ore e una chiamata con input diversi viene sempre inviata al tuo endpoint come nuova.

Esecuzioni massime per conversazione. Un limite rigido sul numero di volte in cui la funzione può essere eseguita all’interno di una conversazione. Impostalo su 1 per le funzioni che dovrebbero essere attivate solo una volta per chat: generare un preventivo, attivare una richiamata, avviare un’automazione. Quando viene raggiunto il limite, l’IA viene informata che la funzione è già stata eseguita e riceve il risultato più recente, così può ancora rispondere al cliente invece di rimanere in silenzio.

Esecuzioni massime per intervallo di tempo. Un limite di frequenza nel tempo: ad esempio, al massimo 5 esecuzioni entro 60 minuti. Utile per funzioni che chiamano servizi di terze parti a pagamento o attivano automazioni più pesanti. Entrambe le caselle devono essere compilate insieme (un numero di esecuzioni e una finestra in minuti, fino a 7 giorni).

Un paio di cose da sapere:

• I limiti contano solo le esecuzioni riuscite. Una chiamata fallita dal lato del tuo endpoint non consuma il budget.
• Quando un’esecuzione viene bloccata da un limite, il cliente non viene mai lasciato in sospeso: l’IA viene informata del motivo e lavora con le informazioni di cui dispone già.
• I limiti si applicano ovunque venga eseguita la funzione: chat regolari su ogni canale e funzioni gestite da un’automazione. Le conversazioni di prova in “Try Out” non vengono conteggiate e non sono limitate.

Strumenti bot integrati #

Oltre alle funzioni personalizzate che crei tu stesso, la piattaforma include una libreria di strumenti predefiniti che il bot IA può utilizzare durante una conversazione. Questi coprono le operazioni più comuni che un bot deve eseguire — avvisare un membro del team, prenotare un appuntamento, etichettare un contatto, cercare sul tuo sito web, programmare un follow-up e altro ancora — così non devi configurarli da zero.

Il bot decide quando utilizzare ogni strumento in base a ciò che accade nella conversazione e a come sono configurati il tuo Agente (e la campagna ad esso collegata). La maggior parte di questi strumenti si attiva automaticamente quando viene abilitata la funzionalità correlata (ad esempio, gli strumenti di prenotazione diventano disponibili solo dopo aver collegato un calendario e abilitato le prenotazioni).

Costo in crediti: Ogni chiamata a uno strumento viene fatturata in base al livello di qualità AI del tuo Agente, e le funzioni personalizzate che crei tu stesso vengono fatturate allo stesso modo:

Strumenti per Team e Attività #

Strumenti per i contatti #

Strumenti di appuntamento e prenotazione #

Questi strumenti sono disponibili solo quando le prenotazioni sono abilitate nella campagna collegata al tuo Agente e quando è configurato un tipo di evento del calendario.

Strumenti di conoscenza e web #

Strumenti di follow-up #

Questi strumenti richiedono che i follow-up siano abilitati nella campagna collegata al tuo Agente.

Esecutore di funzioni personalizzate #

Strumenti di prenotazione ristorante (Zenchef e Formitable) #

Questi strumenti sono disponibili solo quando è collegata un’integrazione Zenchef o Formitable. Consentono al bot di gestire le prenotazioni del ristorante dall’inizio alla fine.

Attivazione e disattivazione degli strumenti #

La maggior parte degli strumenti è controllata nella scheda Abilità AI dell’Agente (o nel passaggio Abilità AI della campagna, se stai lavorando da una campagna ancora classica):

• Strumenti di prenotazione si attivano quando abiliti le prenotazioni e colleghi un calendario: questa rimane un’impostazione per campagna per ora, con un link diretto al passaggio di quella campagna dalla scheda Abilità AI dell’Agente
• Strumenti di follow-up si attivano quando abiliti i follow-up
• Strumenti per ristoranti si attivano quando colleghi un account Zenchef o Formitable
• Ricerca web ha il proprio interruttore nella scheda FAQ e Conoscenza
• Strumenti per le attività possono essere disattivati per Agente con l’interruttore Consenti all’AI di creare attività (sono attivi per impostazione predefinita; l’interruttore Attività a livello di account in Impostazioni → Profilo → Funzionalità disattiva l’intero sistema di attività ovunque)
• Strumenti di aggiornamento contatti sono controllati nella stessa scheda Abilità AI: se l’AI può rinominare i contatti o salvare informazioni aggiuntive raccolte su di essi
• Strumenti di avviso sono sempre disponibili; la targhettizzazione viene eseguita automaticamente dopo ogni risposta del bot (non è uno strumento che il bot sceglie di chiamare)

Se vuoi che il bot smetta di usare uno specifico strumento integrato, il modo più pulito è disabilitare la funzionalità sottostante (ad esempio, disattiva le prenotazioni per disabilitare tutti gli strumenti di prenotazione).

Funzioni gestite da un’automazione #

Alcune voci nella pagina delle Funzioni personalizzate potrebbero presentare un badge Gestito dall’automazione. Queste non sono state create qui, ma provengono da un’automazione con un trigger Funzione Agente IA, che conferisce al tuo agente una capacità i cui passaggi vengono creati visivamente sulla tela dell’automazione invece di puntare a un indirizzo web esterno.

Una funzione gestita viene curata per te: il suo nome, la descrizione e i campi seguono sempre quanto impostato sul trigger dell’automazione, quindi non può essere modificata o eliminata da questa pagina; usa il link Apri automazione e modifica l’automazione stessa. Puoi comunque scegliere quali agenti possono utilizzarla nel modo consueto: nella scheda Abilità IA di un agente, appare insieme alle altre abilità dell’agente con un normale interruttore on/off (se la sua automazione è in pausa, la riga lo segnala; l’abilità diventa attiva quando l’automazione viene accesa). Tutto il resto si comporta come qualsiasi altra funzione personalizzata: l’IA decide quando chiamarla, raccoglie i dettagli che hai definito e può utilizzare la risposta dell’automazione nella stessa conversazione.

Se devi scegliere tra le due opzioni: punta una normale funzione personalizzata verso un sistema che ha già un indirizzo da chiamare; crea un’automazione con un trigger Funzione Agente AI quando il lavoro è qualcosa che preferiresti assemblare per passaggi (cercare qualcosa in un foglio di calcolo o database, ramificare in base a una condizione, creare record) senza dover gestire un tuo server. Vedi Automazioni.

Requisiti del piano #

Le funzioni personalizzate sono disponibili nei piani che includono la funzionalità delle funzioni personalizzate. Controlla il tuo abbonamento per confermare la disponibilità.

Prossimi passi #

• Collega server MCP al tuo Bot — un pacchetto di strumenti già pronti invece di una funzione alla volta.
• Agenti AI — la pagina principale del gruppo AI Studio in cui risiedono le Funzioni Personalizzate e dove le funzioni personalizzate vengono assegnate a un bot.