Le integrazioni API personalizzate consentono al tuo chatbot di richiedere informazioni in tempo reale dal tuo ERP, magazzino, CRM o da un altro servizio. Possono anche apportare modifiche, come la creazione di un appuntamento. Un'integrazione memorizza l'URL di base; ogni operazione definisce una richiesta richiamabile. Puoi quindi collegare le operazioni selezionate a un chatbot come azioni IA.
Prima di iniziare
Verifica che il tuo account includa le integrazioni API personalizzate (Custom API integrations). Ti servono l'URL dell'endpoint, il metodo HTTP, i nomi e i tipi dei parametri, i requisiti di autenticazione e una risposta di esempio. L'endpoint deve essere raggiungibile dai server di ChatLab; localhost sul tuo computer non è un endpoint di produzione.
Usa HTTPS e un servizio di test o record di test per la configurazione. Una richiesta di test chiama effettivamente l'endpoint, quindi una richiesta POST, PATCH o DELETE potrebbe modificare dati esterni. Rendi le operazioni sicure da ripetere quando possibile.
1. Crea un'integrazione
- Apri Custom Integrations (Integrazioni personalizzate) nel menu principale di navigazione.
- Fai clic su + Define API Integration (+ Definisci integrazione API).
- Inserisci il nome dell'API (API name) e l'URL di base dell'API (API Base URL), ad esempio
https://api.example.com. - Fai clic su Create API Integration (Crea integrazione API).
- Nella voce dell'elenco corrispondente, fai clic su View (Visualizza), quindi su + Define API Operation (+ Definisci operazione API).
2. Definisci l'operazione
Assegna all'operazione un'etichetta riconoscibile e un nome leggibile dalla macchina (Operation name), come getProductDetails. Per il nome dell'operazione usa solo lettere e numeri, senza spazi o trattini bassi. Descrivi cosa fa l'operazione e quando il chatbot dovrebbe usarla.
Inserisci l'URI relativo, ad esempio /v1/products/@productId@. L'URL di base e l'URI formano l'indirizzo della richiesta.
Alcune schermate esistenti mostrano nomi di esempio precedenti o segnaposto tra parentesi graffe. Segui la sintassi attuale indicata di seguito: nomi di operazione come getProductDetails e segnaposto dei parametri racchiusi tra @.
Parametri di percorso e di query
Fai clic su Add path variable (Aggiungi variabile di percorso) per definire productId. Imposta il tipo di dati e l'origine del valore, quindi inserisci @productId@ nell'URI. Le variabili di percorso sono obbligatorie e ogni variabile di percorso definita deve comparire nell'URI prima di poter salvare o testare.
Usa Add query parameter (Aggiungi parametro di query) per parametri come limit o language che vanno inseriti dopo il punto interrogativo dell'URL. Inserisci il nome previsto dalla tua API, il tipo, la descrizione e l'origine del valore.
Le origini dei valori disponibili includono:
- Provided by user or chatbot (Fornito dall'utente o dal chatbot): il modello fornisce un valore ricavato dalla conversazione. Spiega il formato previsto e contrassegna i valori obbligatori in modo appropriato.
- Constant (Costante): un valore configurato nell'operazione, come un identificatore di account fisso o una credenziale API a uso limitato.
- Random value (Valore casuale): un valore generato automaticamente.
- Client context (Contesto del client): un valore passato dal sito web host, dove disponibile per il tuo account. Consulta Chat API.
I tipi scalari includono string, integer, double e boolean. I parametri del corpo supportano anche array di stringhe e numeri interi.
3. Configura il metodo e il corpo
Scegli GET, POST, PUT, PATCH o DELETE in base al tuo endpoint. Per i metodi diversi da GET, l'editor offre il contenuto della richiesta in formato raw (grezzo) o form-data.
Per un corpo JSON raw, definisci i parametri del corpo e inserisci i rispettivi segnaposto @name@ nel template. Aggiungi l'intestazione Content-Type corretta richiesta dal tuo endpoint. Ad esempio, con i parametri di tipo stringa name e array di stringhe tags:
{
"name": "@name@",
"tags": @tags@
}
Questo è un template, non JSON letterale fino al momento della sostituzione. I segnaposto degli array non devono essere racchiusi tra virgolette. Ogni parametro del corpo definito deve essere utilizzato nel template quando è attivo l'editor per il corpo raw. Controlla la richiesta visualizzata durante i test, inclusi i testi che contengono virgolette o caratteri speciali.
4. Aggiungi gli header di autenticazione
Usa Add header (Aggiungi intestazione) per definire gli header previsti dall'API. Per un bearer token, usa il nome dell'header Authorization, l'origine del valore Constant (Costante) e il valore Bearer YOUR_RESTRICTED_TOKEN.
Tieni i segreti fuori dai prompt e dagli URL. Evita operazioni che restituiscono token di accesso al modello affidandosi alle istruzioni per nasconderli. Privilegia un endpoint di integrazione lato server che gestisca la propria autenticazione ed esponga solo l'operazione consentita.
5. Salva e testa la richiesta
- Fai clic su Save changes (Salva modifiche) nell'editor delle operazioni. A differenza delle normali impostazioni del chatbot (Settings), questo editor include un pulsante di salvataggio esplicito.
- Fai clic su Test API Operation (Testa operazione API). Il pulsante è disabilitato finché sono presenti modifiche non salvate.
- Inserisci valori di parametro rappresentativi. Per i dati di test di tipo array, usa valori separati da virgole.
- Esegui il test solo su dati che sei autorizzato a leggere o modificare.
- Controlla il codice di stato, il corpo della risposta, l'URL della richiesta, le intestazioni, il corpo e gli eventuali avvisi mostrati nei risultati.
- Correggi gli errori, salva e ripeti secondo necessità.
Non condividere l'output di test se contiene credenziali. Restituisci dati mirati e suddivisi in pagine, ove possibile: le risposte di grandi dimensioni possono essere troncate prima di raggiungere il modello.
6. Collega l'operazione a un chatbot
Apri il tuo chatbot, quindi vai su Settings > Actions (Impostazioni > Azioni). Usa il pulsante più per aggiungere un'azione, trova la tua operazione sotto le API personalizzate e collegala o attivala. La semplice creazione di un'integrazione a livello di account non rende ogni operazione automaticamente disponibile per tutti i chatbot.
Controlla le istruzioni dell'azione e le impostazioni di sicurezza disponibili, quindi attendi che lo stato risulti salvato. Vedi Azioni IA per l'editor delle azioni.
7. Spiega quando usarla
Apri Settings > Role & Behavior (Impostazioni > Ruolo e comportamento).
Se utilizzi istruzioni di ruolo personalizzate, seleziona Custom Role Definition (Definizione del ruolo personalizzata) e aggiungi una regola precisa, ad esempio: "Quando il visitatore chiede se un prodotto è disponibile, chiama getProductDetails con il rispettivo ID prodotto. Comunica la disponibilità restituita. Se la ricerca fallisce, spiega che non è stato possibile verificare la disponibilità."
Conserva le altre istruzioni utili del chatbot. Attendi la conferma di salvataggio, poi usa l'anteprima in Overview (Panoramica) per testare domande realistiche, parametri mancanti, errori e richieste non autorizzate. Le conversazioni nell'anteprima possono eseguire operazioni reali.
L'invocazione dell'operazione da parte dell'IA non è garantita né necessariamente limitata a una sola volta. Esegui i test con il modello selezionato per il tuo chatbot; non dare per scontato che il nome del modello garantisca da solo il corretto utilizzo degli strumenti.
Sicurezza e risoluzione dei problemi
Il tuo endpoint deve autenticare le richieste e autorizzare l'accesso di ciascun utente prima di restituire informazioni sensibili o eseguire una modifica. Un ID client fornito dal browser, un'e-mail, un numero d'ordine o un campo di contesto non costituiscono una prova sufficiente dell'identità. Se trasmetti un token specifico per l'utente tramite il contesto del client, il tuo server deve convalidarlo.
Restituisci solo i campi necessari al chatbot, ad esempio lo stato dell'ordine invece di un profilo cliente completo. Le istruzioni del prompt possono guidare la formulazione del testo, ma non possono garantire che i dati sensibili restituiti al modello rimangano nascosti.
Se la richiesta ha esito positivo nell'editor di test ma non in una conversazione, controlla l'azione collegata, il suo stato di attivazione, le istruzioni, i parametri obbligatori e il contesto disponibile. Se entrambe le opzioni falliscono, esamina l'URL, il metodo HTTP, l'autenticazione, il corpo renderizzato e i log del tuo endpoint. Evita di ripetere continuamente un'operazione di scrittura finché non sai se la richiesta precedente è andata a buon fine.