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:

I valori delle intestazioni che contengono una chiave o una password, come Authorization o X-API-Key, vengono visualizzati come punti una volta digitati. Fai clic sull’occhio accanto al valore per visualizzarlo.

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 agente ha chiamato la funzione o comportarsi in modo diverso durante i test.

Quando un controllo di follow-up chiama la tua funzione (vedi Invia solo quando un controllo viene superato), la richiesta è diversa da una chiamata durante la conversazione: non ha parametri di input e il campo system contiene solo system.contact (con il suo id) più un blocco system.follow_up (type, cycle_number, follow_up_number, reason, campaign_id, agent_id). Non contiene alcun oggetto campaign. Ignora dati di sistema si applica anche a quella chiamata.

Non ti servono i dati di sistema? Attiva l’interruttore Salta dati di sistema nel generatore di funzioni. Il bot invierà quindi solo i parametri di input che hai definito — nessun dato sul contatto o sull’agente. Usalo se il tuo endpoint rifiuta campi imprevisti o se desideri semplicemente un payload più snello.

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 IA.
2. Vai alla scheda Abilità IA.
3. Vedrai un elenco di ogni funzione personalizzata che hai creato. Attiva ogni funzione che desideri che il bot di questo Agente possa 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 chiama una funzione personalizzata durante una conversazione e la chiamata fallisce, ad esempio a causa di credenziali errate, un endpoint non attivo o un timeout, la conversazione ora lo mostra: un indicatore rosso “(nome funzione) fallito” appare nel thread, sia nella scheda Prova dell’agente che nelle conversazioni reali in Chat. Clicca 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’header di autenticazione, un timeout significa che il tuo endpoint ha impiegato più di 30 secondi; per un lavoro che richiede più tempo, vedi Lavori a lunga esecuzione).

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.

Quando uno strumento continua a non funzionare nelle conversazioni reali #

Se la stessa funzione personalizzata fallisce 3 volte nell’arco di 24 ore mentre il tuo agente IA sta chattando, riceverai un avviso al giorno: via email, sotto l’icona della campanella e come notifica push, se l’hai abilitata. L’avviso indica lo strumento, mostra l’ultimo errore e fornisce i link alle chat interessate, poiché l’agente avrà comunicato a quei contatti di aver riscontrato un problema tecnico. La riga della funzione in Impostazioni mostra una dicitura In errore con il conteggio degli errori e l’ultimo errore finché lo strumento non torna a funzionare; una chiamata riuscita azzera il conteggio. Puoi disattivare questi avvisi in Impostazioni → Notifiche → Errori degli strumenti.

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. Se il tuo firewall richiede una allowlist IP, ogni chiamata a una funzione personalizzata (e ogni controllo successivo) viene inviata da un unico indirizzo IPv4 fisso, lo stesso utilizzato dai nostri webhook; nessun intervallo, nessun IPv6, nessuna rotazione. Contatta l’assistenza e ti forniremo l’indirizzo. Attiva la firma delle richieste e verifica la firma come tuo vero controllo di attendibilità, trattando l’IP come un filtro aggiuntivo.

9. 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 redirect: punta la funzione direttamente all’URL finale, non a uno che reindirizza ad esso.

Lavori a lunga esecuzione: ottieni il risultato in seguito #

Normalmente una funzione personalizzata deve rispondere entro 30 secondi, mentre il contatto attende la risposta. Alcuni lavori richiedono più tempo: renderizzare un video, eseguire un controllo del credito, attendere che una persona dalla tua parte approvi qualcosa. Per questi, attiva Il risultato arriva dopo (lunga esecuzione). La chiamata dell’IA avvia quindi solo il lavoro. Il tuo servizio risponde immediatamente, l’IA comunica al contatto che il risultato è in arrivo e prosegue con la conversazione, e il tuo servizio invia il risultato a un link di callback non appena è pronto.

Quando utilizzarlo #

Utilizzalo quando il tuo servizio non può rispondere in modo affidabile entro 30 secondi. Lascialo disattivato per ricerche rapide (stato di un ordine, controllo di magazzino, prezzo): sono più semplici come chiamata normale, perché l’IA risponde con il risultato nella stessa risposta.

Le impostazioni nell’editor #

Le trovi nell’editor delle funzioni personalizzate, accanto a Salta dati di sistema.

Cosa riceve il tuo servizio #

Con l’opzione attiva, ogni chiamata trasporta il link di callback in tre punti, oltre a tutto ciò che è descritto sopra (i tuoi parametri di input, il blocco system e gli header di firma):

Il link è univoco per ogni chiamata, appartiene a quel contatto e a quella chiamata, funziona una volta sola e scade dopo Attendi fino a. Non hai bisogno di una chiave API per usarlo: il link stesso è l’autorizzazione. Trattalo come una password e non scriverlo mai in un log pubblico.

Invio del risultato #

Quando il lavoro è completato, invia una POST al link di callback:

POST https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 },
  "message": "Your video is ready: https://cdn.example.com/spring-offer.mp4"
}

• result è ciò che l’IA legge. Può essere testo o un oggetto JSON.
• message è facoltativo. Con Invia il testo così com’è, il contatto riceve message quando ne invii uno, altrimenti result quando si tratta di testo.
• media_url è facoltativo: un link https a un file (immagine, video, audio o documento) che il contatto riceve come vero e proprio allegato, non come link. Vedi Invio di un file qui sotto.
• Puoi anche inviare un corpo di testo semplice con Content-Type: text/plain. Viene trattato come result.
• Il corpo può arrivare fino a 64 KB.

Cosa risponde il link di callback:

Un esempio completo: un video che richiede tre minuti #

1. L’IA chiama la tua funzione. Ricevi (abbreviato):

POST https://api.example.com/render
X-Callback-Url: https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "video_title": "Spring offer",
  "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
  "system": {
    "contactId": "...",
    "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
    "callback_expires_at": "2026-10-20T19:15:00.000Z"
  }
}

2. Il tuo servizio avvia il rendering e risponde immediatamente:

{ "status": "started" }

3. L’IA comunica al contatto che il video è in fase di creazione e continua a chattare.
4. Tre minuti dopo, il tuo servizio pubblica il risultato sul link di callback:

{ "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 } }

5. L’IA scrive il messaggio successivo con parole sue, ad esempio “Il tuo video è pronto: https://cdn.example.com/spring-offer.mp4”.

Usi Zapier o Make? Lascia che il webhook del trigger riceva la chiamata e rendi l’ultimo passaggio del flusso una richiesta POST a callback_url dai dati del trigger.

Cosa succede nella chat #

Il risultato viene salvato nella conversazione come voce di funzione, quindi lo vedrai nella posta in arrivo come qualsiasi altra chiamata a funzione personalizzata. Poi, a seconda di Quando arriva il risultato, l’IA scrive e invia il messaggio successivo (questo costa una risposta dell’IA, come qualsiasi messaggio dell’IA), oppure il tuo testo viene inviato così com’è. Con Invia il testo così com’è, viene inviato il campo message quando ne includi uno, altrimenti result quando è testo semplice; se pubblichi solo un oggetto senza testo, l’IA scrive il messaggio al suo posto.

Se l’IA è disattivata per quel contatto quando arriva il risultato (un membro del team ha preso in carico la conversazione, l’IA è stata messa in pausa, l’agente è spento o ha esaurito i crediti), il risultato viene comunque salvato nella conversazione, ma non viene inviato alcun messaggio. Non viene inviato nemmeno in seguito quando l’IA viene riattivata. Il membro del team vede il risultato nella chat e può utilizzarlo.

Nella scheda Prova dell’agente, l’intero flusso funziona allo stesso modo: il risultato arriva nella chat di test.

Invio di un file (video, immagine, PDF) #

Un risultato che è un file, ad esempio un video che il tuo servizio ha elaborato in background, arriva al contatto come allegato che può aprire nella chat, in entrambe le modalità. La piattaforma trova il file nel tuo callback in questo modo:

1. media_url nel corpo, quando ne invii uno.
2. Altrimenti un campo file sull’oggetto result: file_url, video_url, image_url, pdf_url, document_url, audio_url, attachment_url o download_url.
3. Altrimenti il primo link https nel testo che termina con un’estensione di file come .mp4, .jpg, .png o .pdf.

Con L’IA scrive il messaggio successivo, l’IA scrive il testo e il file viene allegato a quel messaggio (all’IA viene detto di non incollare il link). Con Invia il testo così com’è, il tuo message è la didascalia dell’allegato.

{
  "result": { "status": "done", "title": "Spring offer" },
  "message": "Your video is ready.",
  "media_url": "https://cdn.example.com/spring-offer.mp4"
}

I file possono pesare fino a 16 MB e devono essere raggiungibili tramite https. Ogni canale supporta tipi diversi: ad esempio, i canali email e WhatsApp accettano video, immagini, audio e documenti, mentre gli SMS non supportano i file. Quando un canale non può accettare il file, o il file è troppo grande, il contatto riceve comunque il messaggio, con il link al file aggiunto alla fine.

Quando il risultato non arriva mai #

Se non viene pubblicato nulla prima che scada il tempo di Attendi fino a, all’IA viene comunicato che il risultato non è mai arrivato, così può avvisare il contatto. Una voce con codice APP-3103 appare sotto Impostazioni → Registro errori e riceverai una notifica di errore dello strumento.

Limiti in sintesi #

• Un risultato per link di callback. I post successivi allo stesso link vengono considerati duplicati e non modificano nulla.
• Fino a 64 KB per risultato.
• Un file per risultato, fino a 16 MB, tramite https.
• Fino a 20 post al minuto per link.
• Attendi fino a da 1 a 168 ore.
• Il tuo servizio ha comunque 30 secondi per rispondere alla prima chiamata.

Verificare che una chiamata provenga realmente da noi #

Chiunque venga a conoscenza dell’URL della tua funzione potrebbe inviarle una richiesta falsa. Un segreto lungo in un’intestazione di autenticazione aiuta, ma è lo stesso valore per ogni chiamata, quindi chiunque veda una richiesta (in un log o in uno screenshot) può riutilizzarlo. La firma delle richieste risolve questo problema: ogni chiamata porta con sé una firma che solo chi possiede il tuo segreto può produrre e che scade dopo pochi minuti.

La firma è opzionale e disattivata per impostazione predefinita, ed è un’impostazione valida per l’intero account: un unico segreto firma ogni funzione personalizzata.

Attivazione della firma #

1. Apri Funzioni personalizzate.
2. Sotto l’elenco delle tue funzioni, trova la scheda Firma delle richieste e fai clic su Attiva firma.
3. Fai clic su Mostra, copia il segreto (inizia con whsec_) e salvalo nel sistema che riceve le chiamate. Trattalo come una password.

Dalla stessa scheda puoi copiare nuovamente il segreto, Ruotarlo (quello vecchio smetterà di funzionare immediatamente) o Disattivare la firma.

Cosa inviamo #

Una volta attivata la firma, ogni chiamata effettuata da una funzione personalizzata porta due intestazioni aggiuntive: le chiamate dell’IA durante una chat, le condizioni di invio successive e il pulsante Esegui test nell’editor.

Ogni chiamata, firmata o meno, porta anche User-Agent: Custom-Function/1.0 a meno che tu non imposti la tua intestazione User-Agent.

Le intestazioni e la firma funzionano esattamente come i webhook firmati, quindi se verifichi già i nostri webhook, lo stesso codice funzionerà anche qui. Solo il segreto è diverso.

Come verificare #

La firma è un HMAC-SHA256 della stringa <timestamp>.<raw request body>, utilizzando il tuo segreto di firma come chiave. Verificala rispetto al corpo raw, i byte esatti che hai ricevuto: analizzare il JSON e riconvertirlo in testo può modificare i byte e la firma non corrisponderà.

Una funzione che utilizza GET (o una POST senza nulla da inviare) non ha un corpo, quindi la stringa firmata è solo <timestamp>. con un corpo vuoto. La firma dimostra quindi che la chiamata proviene da noi ed è recente, ma non copre la stringa di query.

Esempio in Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"] || ""; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = signature.replace("v1=", "");

  return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Esempio in Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    signature = headers.get("X-Webhook-Signature", "").replace("v1=", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Testala con Esegui test nell’editor: una volta attivata la firma, la chiamata di test viene firmata esattamente come una reale, quindi una funzione che supera il test supererà anche il tuo controllo durante le chat reali.

Utilizzi l’API? Lo stesso segreto può essere letto, generato, ruotato e rimosso con GET, POST e DELETE su /v1/custom-functions/signing-secret.

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 titoli, 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. Le funzioni che utilizzano il metodo GET vengono trattate automaticamente come di sola lettura, poiché le richieste GET sono destinate esclusivamente al recupero di dati; le funzioni POST, PUT, PATCH e DELETE richiedono l’attivazione dell’interruttore.

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

Invio di offerte, contratti o fatture su LinkedIn. Quando l’IA risponde su LinkedIn, scrive dalla posta in arrivo del proprietario dell’account, pertanto non dovrebbe inviare offerte, contratti, preventivi, fatture, link di pagamento o accessi per conto del proprietario a meno che quest’ultimo non lo abbia richiesto. Con Automatico (l’impostazione predefinita), una funzione il cui nome o descrizione indica l’invio di uno di questi elementi non viene eseguita su LinkedIn: all’IA viene comunicato che non è stato inviato nulla e viene informata la persona che il proprietario se ne occuperà personalmente. Scegli Consentito per permettere comunque l’esecuzione della funzione su LinkedIn, oppure Mai su LinkedIn per bloccare una funzione che il controllo automatico potrebbe non rilevare. Gli altri canali non sono interessati e, a differenza dei limiti sopra indicati, questa impostazione si applica anche in Prova. 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 è configurato il tuo Agente. 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 sul tuo Agente e un tipo di evento del calendario è configurato.

Strumenti di conoscenza e web #

Strumenti di follow-up #

Questi strumenti richiedono che i follow-up siano abilitati sul 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à IA dell’Agente:

• Gli strumenti di prenotazione si attivano quando abiliti le prenotazioni e colleghi un calendario, nella scheda Prenotazioni sulla stessa scheda Abilità IA
• Gli strumenti di follow-up si attivano quando abiliti i follow-up
• Gli strumenti per ristoranti si attivano quando colleghi un account Zenchef o Formitable
• La ricerca web ha il suo interruttore nella scheda FAQ e Conoscenza
• Gli strumenti per le attività possono essere disattivati per singolo Agente con l’interruttore Consenti all’IA 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)
• Gli strumenti di aggiornamento contatti sono controllati nella stessa scheda Abilità IA: se l’IA può rinominare i contatti o salvare su di essi informazioni extra raccolte
• Gli strumenti di avviso sono sempre disponibili; l’aggiunta di tag avviene 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.