Azioni API personalizzate

Le Azioni API personalizzate permettono al tuo agente di chiamare un endpoint HTTP esterno durante una conversazione e usare la risposta per rispondere al visitatore. Usale per verificare lo stato degli ordini, controllare l'inventario, recuperare i dettagli dell'account o interrogare qualsiasi API interna.

Crea un'azione

Vai su Capacità → Azioni API personalizzate e clicca su Aggiungi azione.

Impostazioni generali

• Nome — come l'AI chiama questa azione internamente. Mantienilo breve e descrittivo: Verifica stato ordine, Controlla disponibilità prodotto.
• Quando usare — descrizione in linguaggio comune di quando l'AI dovrebbe attivare questa azione.

Usa questa azione quando il visitatore chiede dello stato del suo ordine o vuole tracciare una spedizione.

Configura la chiamata API

Metodo e URL

Seleziona il metodo HTTP (GET, POST, PUT, PATCH, DELETE) e inserisci l'URL dell'endpoint. Usa i {{segnaposto}} per i valori dinamici:

https://api.iltuonegozio.com/ordini/{{order_id}}

Input dei dati

Definisci le variabili necessarie per URL, intestazioni o corpo. Per ogni input:

Esempio per la ricerca di un ordine:

• Nome: order_id · Descrizione: Il numero d'ordine fornito dal visitatore · Obbligatorio: sì

L'AI estrae i valori automaticamente dal contesto della conversazione. Se manca un valore obbligatorio, l'AI lo chiede al visitatore prima di effettuare la chiamata.

Intestazioni, Parametri, Corpo

Usa le schede per aggiungere intestazioni di autorizzazione, parametri di query o un corpo della richiesta. I segnaposto funzionano ovunque:

Authorization: Bearer {{api_token}}

Per i segreti statici (come i token API) che non vuoi estrarre dalla chat, inseriscili direttamente come valori senza segnaposto — non saranno esposti all'AI o ai visitatori.

Testa l'azione

Nella sezione Risposta di test, inserisci valori di esempio per i tuoi input e clicca su Esegui test. Viene effettuata la vera chiamata HTTP e la risposta viene mostrata. Usala per verificare che URL e autenticazione siano corretti prima di andare live.

Accesso ai dati

Controlla quali parti della risposta API l'AI può vedere:

• Completo — l'intera risposta JSON viene passata all'AI. Usalo per risposte semplici dove tutti i campi sono necessari.
• Limitato — all'AI vengono passati solo i campi che hai inserito nella whitelist. Usalo per proteggere i dati sensibili (ID interni, token, PII) dall'essere inclusi nelle risposte AI.

Inserisci i percorsi dei campi uno per riga usando la notazione a punti:

order.status
order.estimated_delivery
customer.name

Suggerimenti

• Mantieni le risposte concise — l'AI riassume la risposta quando risponde, quindi una risposta mirata dà risultati migliori di un oggetto con 200 campi.
• Usa l'accesso ai dati Limitato per qualsiasi API che restituisce campi sensibili insieme a quelli di cui hai bisogno.
• Se la tua API richiede OAuth, usa un token di servizio a lunga durata anziché un token utente — l'azione viene eseguita sul server di BotChata, non nel browser del visitatore.
• La sintassi {{segnaposto}} funziona in: percorso URL, parametri di query, intestazioni e corpo della richiesta.