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

| | Webhook | Funzioni personalizzate |
|---|----------|------------------|
| **Direzione** | Unidirezionale (fire-and-forget) | Bidirezionale (chiama e attendi) |
| **Cosa fa il bot** | Invia una notifica quando succede qualcosa, poi prosegue. | Chiama, **si mette in pausa, attende la risposta** e usa ciò che riceve per continuare la conversazione. |
| **Visibilità nella conversazione** | Il risultato a valle è invisibile al bot: non vede mai cosa è successo. | La risposta viene reinserita direttamente nell'IA, così il bot può citarla, ragionarci sopra e rispondere al cliente con essa. |
| **Ideale per** | Registrare eventi, sincronizzare dati con un CRM, attivare automazioni esterne (Zapier, Make, n8n). | Qualsiasi cosa per cui il bot abbia bisogno di una **risposta** prima di poter replicare: ricerche dal vivo, prezzi in tempo reale, generazione di contenuti al volo. |

**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:

| Livello di qualità AI | Crediti per chiamata a funzione personalizzata | Con la tua chiave Anthropic (BYOK) collegata |
|---|---|---|
| Pro | 1 credito | 0 crediti: viene eseguita con la tua chiave |
| Economy (deprecato) | 0,5 crediti | 0 crediti: viene eseguita con la tua chiave |
| Max | 0,25 crediti | ancora 0,25 crediti, fatturati anche con la tua chiave collegata, perché Max viene eseguito sul nostro modello |
| Mini | 0,15 crediti | ancora 0,15 crediti, fatturati anche con la tua chiave collegata, perché Mini viene eseguito sul nostro modello |

---

## 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:

| Colonna | Cosa mostra |
|--------|--------------|
| **Nome** | Il nome della funzione (ad es. `check_order_status`) |
| **Descrizione** | Un breve riepilogo di ciò che fa la funzione (troncato a 50 caratteri nella tabella) |
| **Metodo** | Il metodo HTTP utilizzato, mostrato come badge colorato: GET (blu), POST (verde), PUT (arancione), DELETE (rosso) |
| **Creato** | La data in cui la funzione è stata creata |

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


| Campo | Cosa inserire | Esempio |
|-------|--------------|---------|
| **Nome** | Un nome breve che utilizzi lettere, numeri e trattini bassi | `check_order_status` |
| **Descrizione** | Spiega cosa fa questa funzione (l'IA la legge per decidere quando usarla) | "Cerca lo stato attuale dell'ordine di un cliente utilizzando il numero d'ordine" |
| **Scopo (Azione IA)** | Indica all'IA esattamente quando e come utilizzare questa funzione | "Usala quando un cliente chiede informazioni sullo stato dell'ordine, sulla spedizione o sulla consegna. Chiedi prima il numero dell'ordine." |

**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:

| Campo | Cosa inserire | Esempio |
|-------|--------------|---------|
| **URL** | L'indirizzo web dell'endpoint del tuo sistema (l'indirizzo specifico sul tuo sistema che riceve la richiesta e invia i dati) | `https://api.yourstore.com/v1/orders/status` |
| **Metodo** | Il tipo di richiesta da inviare | Vedi le opzioni sotto |

**Quale metodo scegliere:**

| Metodo | Quando utilizzarlo |
|--------|---------------|
| **GET** | Ricerca di informazioni (stato dell'ordine, inventario, dettagli dell'account) |
| **POST** | Creazione di nuovi record (ticket di supporto, lead, prenotazioni) o ricerche complesse |
| **PUT** | Aggiornamento completo di un record esistente |
| **PATCH** | Aggiornamento parziale di un record esistente |
| **DELETE** | Rimozione di un record |

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:

| Intestazione | Valore di esempio |
|--------|--------------|
| `Authorization` | `Bearer your-api-key-here` |
| `Content-Type` | `application/json` |

**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:

| Proprietà | Cosa significa |
|----------|--------------|
| **Nome** | Il nome del parametro (deve corrispondere a ciò che il tuo sistema si aspetta) |
| **Tipo** | Il tipo di dati (testo, numero, vero/falso, ecc.) |
| **Descrizione** | Indica all'IA cos'è questa informazione e dove trovarla nella conversazione |
| **Obbligatorio** | Se impostato su Sì, il bot chiederà al cliente questa informazione prima di procedere |

**Tipi di parametri disponibili:**

| Tipo | Cosa significa |
|------|--------------|
| **string** | Testo (nomi, numeri d'ordine, indirizzi) |
| **number** | Un valore numerico (quantità, prezzo) |
| **boolean** | Vero o falso (valori sì/no) |
| **array** | Un elenco di elementi. Inviato come un vero elenco JSON — in **Esegui test** puoi digitarlo come `[8624]`, `["a", "b"]` o semplicemente separato da virgole (`8624, 8625`) e verrà convertito per te. Se la tua API è rigorosa riguardo al contenuto dell'elenco — ad esempio solo numeri — imposta il **Tipo di elemento** opzionale accanto al tipo e ogni valore nell'elenco verrà convertito in esso. |
| **query_param** | Testo inviato come parametro URL invece che nel corpo della richiesta. Usalo quando la tua API si aspetta dati nell'URL (ad esempio, `?order_id=123`). |

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`:

| Campo di sistema | Cosa contiene |
|-------------|----------------|
| `system.contactId` | L'ID della piattaforma del contatto nella conversazione |
| `system.campaignId` | L'ID della campagna a cui appartiene la conversazione |
| `system.userId` | Il tuo ID utente |
| `system.channel` | Il canale di messaggistica (es. `"whatsapp"`, `"instagram"`) |
| `system.contact` | Il record completo del contatto (nome, telefono, email, tag, ecc.) |
| `system.campaign` | La configurazione della campagna |
| `system.test` | `true` se si tratta di un test di prova, `false` per conversazioni dal vivo |

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](../ai-agents/ai-agents.md) 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](#step-3-add-authentication-headers) 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](mcp-servers.md#ready-made-example-connect-a-shopify-store).)

**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](https://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 <span data-t="appName">Your AI Connector</span>. 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](#assigning-functions-to-an-agent)). Questo è il motivo più comune per cui una funzione costruita correttamente non viene mai attivata.

::: tip
**Suggerimento:** il bot dispone anche di uno strumento integrato **Aggiorna email contatto**, che salva l'indirizzo nella scheda del contatto all'interno della piattaforma. Questo è separato da tale funzione ed è utile usarlo insieme: lo strumento integrato mantiene completa la tua scheda contatto, la funzione personalizzata invia l'indirizzo al tuo CRM.
:::


---

## 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:

| Livello di qualità AI | Crediti per chiamata a strumento | Con la tua chiave Anthropic (BYOK) collegata |
|---|---|---|
| Pro | 1 credito | 0 crediti: viene eseguita con la tua chiave |
| Economy (deprecato) | 0,5 crediti | 0 crediti: viene eseguita con la tua chiave |
| Max | 0,25 crediti | ancora 0,25 crediti, fatturati anche con la tua chiave collegata, perché Max viene eseguito sul nostro modello |
| Mini | 0,15 crediti | ancora 0,15 crediti, fatturati anche con la tua chiave collegata, perché Mini viene eseguito sul nostro modello |

### Strumenti per Team e Attività

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Avvisa un membro del team** | Mette in pausa il bot per questo contatto e invia un'email al tuo team indicando che è necessario un intervento umano. La chat viene contrassegnata in modo che un collega possa prenderla in carico. | Quando il cliente chiede un operatore umano, è frustrato o chiede qualcosa che il bot non è autorizzato o in grado di rispondere. |
| **Crea un'attività** | Crea una nuova attività sulla tua bacheca, facoltativamente collegata al contatto e alla conversazione. Il bot continua a rispondere normalmente: l'attività è solo un promemoria per il tuo team per il follow-up. | Per elementi non urgenti come una richiesta di funzionalità, un'opportunità di upsell o un richiamo che il team dovrebbe gestire in seguito. |
| **Suggerisci un aggiornamento FAQ** | Quando il bot incontra una domanda a cui non sa rispondere bene, crea un'attività chiedendo al tuo team di aggiungere una risposta alla knowledge base. | Quando un contatto chiede qualcosa non coperto dalle tue FAQ esistenti, così la lacuna viene colmata per la volta successiva. |
| **Aggiungi contesto a un suggerimento FAQ** | Se un altro contatto pone in seguito una domanda simile con un'angolazione diversa, il bot aggiunge quel contesto al suggerimento FAQ esistente invece di creare un'attività duplicata. | Automatico: mantiene pulito il tuo elenco di attività quando più persone sollevano la stessa lacuna di conoscenza. |

### Strumenti per i contatti

| Strumento | Cosa fa | Quando il bot lo usa |
|------|--------------|----------------------|
| **Etichettatura** | Viene eseguita automaticamente dopo ogni risposta del bot: non è uno strumento che il bot rivolto al cliente decide di chiamare. Il sistema esamina la conversazione recente e applica le etichette pertinenti, riutilizzando le tue etichette esistenti ove possibile (e creandone una nuova solo quando necessario). | Automatico: ogni volta che la conversazione rivela qualcosa su cui vale la pena segmentare, come interesse, intenzione, qualità del lead o lingua. |
| **Aggiorna nome contatto** | Salva il nome e/o il cognome del contatto quando li condivide. | Quando il cliente si presenta o corregge un nome. |
| **Aggiorna email contatto** | Salva l'indirizzo email del contatto quando lo condivide. | Quando il cliente fornisce un'email: per newsletter, ricevute, ricerche account, ecc. |

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

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Verifica fasce orarie disponibili** | Cerca quali orari sono liberi nel tuo calendario collegato per una data o un intervallo di date specifici. | Quando il cliente vuole prenotare e il bot deve offrire la disponibilità reale. |
| **Prenota un appuntamento** | Crea l'appuntamento nel tuo calendario e conferma la prenotazione al cliente. | Dopo che il cliente conferma una data e un orario specifici. |
| **Sposta un appuntamento** | Ripianifica un appuntamento esistente in una nuova data e ora. | Quando il cliente chiede di ripianificare. |
| **Annulla un appuntamento** | Annulla un appuntamento esistente. | Quando il cliente chiede di annullare. |
| **Cerca appuntamenti** | Recupera gli appuntamenti esistenti di un contatto in modo che il bot sappia cosa è già stato fissato. | Quando il cliente chiede "quando è il mio appuntamento?" o prima di offrire di ripianificare. |

### Strumenti di conoscenza e web

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Cerca nel tuo sito web** | Scansiona gli URL che hai aggiunto all'elenco degli URL dinamici della campagna per trovare pagine di prodotto, articoli o altri contenuti che rispondono alla domanda del cliente. Disponibile solo quando la **Ricerca web AI** è attiva e hai aggiunto almeno un URL dinamico. Se la Ricerca web AI è disattivata, il bot non può leggere pagine o link, nemmeno quelli incollati dal cliente nella chat. | Quando il cliente chiede informazioni probabilmente presenti sul tuo sito web: prodotti, prezzi, sedi, politiche. |
| **Controlla un link** | Legge il contenuto di uno specifico URL in modo che il bot possa rispondere a domande su quella pagina. Disponibile solo quando la **Ricerca web AI** è attiva e hai aggiunto almeno un URL dinamico. Se la Ricerca web AI è disattivata, il bot non può leggere pagine o link, nemmeno quelli incollati dal cliente nella chat. | Quando il cliente condivide un link o chiede informazioni su una pagina specifica del tuo sito. |
| **Cerca sul web** | Esegue una ricerca Google pubblica e restituisce i migliori risultati, in modo che il bot possa rispondere a domande al di fuori dei tuoi contenuti. | Quando il cliente chiede informazioni generali (es. indicazioni, informazioni pubbliche) che non sono presenti nella tua knowledge base. Utilizzato solo se la ricerca web è abilitata. |

### Strumenti di follow-up

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

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Pianifica un follow-up intelligente** | Pianifica un messaggio di follow-up intelligente utilizzando la tua sequenza di follow-up: sceglie il modello e la tempistica corretti in base alla conversazione. | Quando il cliente non risponde più o chiede al bot di "ricontattare più tardi". |
| **Pianifica un follow-up** | Pianifica un follow-up di base in un momento specifico. | Quando il bot deve sollecitare la conversazione in un momento definito. |

### Esecutore di funzioni personalizzate

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Esegui una funzione personalizzata** | Esegue una delle funzioni personalizzate che hai creato e assegnato all'Agente (vedi il resto di questa pagina). | Quando la richiesta del cliente corrisponde allo scopo di una delle tue 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.

| Strumento | Cosa fa | Quando lo usa il bot |
|------|--------------|----------------------|
| **Verifica disponibilità ristorante** | Cerca gli slot di prenotazione aperti per una data, un numero di persone e (facoltativamente) un'area di seduta specifici. | Quando un ospite chiede di prenotare un tavolo. |
| **Crea una prenotazione ristorante** | Crea una nuova prenotazione. | Dopo che l'ospite conferma uno slot specifico. |
| **Aggiorna una prenotazione ristorante** | Modifica la data, l'ora, il numero di persone o le note di una prenotazione esistente. | Quando l'ospite chiede di modificare la propria prenotazione. |
| **Annulla o cambia stato prenotazione** | Annulla una prenotazione o ne aggiorna lo stato (es. confermato, mancata presentazione). | Quando l'ospite annulla o quando il bot deve contrassegnare un cambio di stato. |
| **Cerca prenotazioni** | Trova le prenotazioni esistenti che corrispondono a criteri come nome, email o data. | Quando un ospite abituale chiede informazioni su una prenotazione esistente. |
| **Aggiorna profilo ospite** | Aggiorna il profilo dell'ospite nel sistema del ristorante (preferenze, note, informazioni di contatto). | Quando l'ospite condivide preferenze dietetiche, un nuovo numero di telefono o altre informazioni a livello di profilo. |
| **Elenca prodotti ristorante** | Estrae l'elenco di menu, menu fissi o componenti aggiuntivi disponibili per la prenotazione. | Quando l'ospite chiede "quali menu fissi avete?" o il bot deve allegare un menu a una prenotazione. |

### 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](../automations/automations.md#letting-your-ai-agent-call-an-automation).

---

## 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](mcp-servers.md) — un pacchetto di strumenti già pronti invece di una funzione alla volta.
- [Agenti AI](../ai-agents/ai-agents.md) — la pagina principale del gruppo AI Studio in cui risiedono le Funzioni Personalizzate e dove le funzioni personalizzate vengono assegnate a un bot.