Lo strumento è disponibile per tutti i canali: Chat, Telefono ed Email.
Da non confondere con la richiesta HTTP nelle Automazioni. Nelle Automazioni, la richiesta HTTP è un passaggio del flusso che viene eseguito in un momento preciso. Questo strumento appartiene invece all'Agente IA stesso: è lui a decidere durante la conversazione se e quando effettuare la richiesta, e a continuare a lavorare con la risposta.
Requisiti: un Agente IA su Superchat e un'API che vuoi richiamare (URL, metodo, eventuali credenziali).
Aggiungere lo strumento
Apri il tuo Agente IA e passa a sinistra alla sezione Strumenti e Azioni.
Clicca in alto a destra su Aggiungi strumento.
Seleziona la scheda Richieste HTTP e clicca su Aggiungi.
Si apre l'editor dello strumento con sei schede: Generale, Parametri, Richiesta, Corpo, Credenziali e Test.
Generale: nome e regola di utilizzo
Nome dello strumento: Un nome breve che descrive cosa fa lo strumento, ad es. "Verifica stato ordine" o "Crea appuntamento". Il nome compare nell'elenco sotto Strumenti e Azioni.
Quando deve usare lo strumento l'agente? Questa descrizione è il punto più importante dello strumento. L'Agente IA decide in base a questo testo se effettuare la richiesta. Descrivi in modo concreto in quale situazione deve usare lo strumento, cosa troverà nella risposta e come deve utilizzarla. Indica anche quando non deve usarlo.
Esempio: "Usa questo strumento quando il cliente chiede lo stato del suo ordine. Nella risposta trovi lo stato attuale e la data di consegna prevista, che devi comunicare al cliente. Non usare lo strumento se il cliente non ha indicato un numero d'ordine."
Parametri: quali valori fornisce l'agente
I parametri sono i valori che cambiano da una richiesta all'altra, ad esempio un numero d'ordine o il numero di telefono del contatto. Li definisci qui e poi li inserisci tramite il pulsante { } nell'URL, nei parametri di query, negli header o nel corpo.
Clicca su Aggiungi e compila per ogni parametro:
Nome: Il nome con cui inserirai in seguito il valore.
Origine: Da dove proviene il valore.
Agente IA: L'agente ricava il valore dalla conversazione, ad es. un numero d'ordine indicato dal cliente.
Attributo del contatto: Il valore proviene dai dati esistenti del contatto in Superchat, ad es. il numero cliente.
Tipo: Tipo di dato del valore, ad es. testo.
Descrizione: Cos'è il valore e da dove proviene. Con origine "Agente IA", la descrizione aiuta l'agente a ricavare il valore corretto dalla conversazione.
Obbligatorio: Se la richiesta necessita obbligatoriamente del valore.
La colonna Utilizzo mostra se il parametro è già stato inserito da qualche parte nella richiesta. Se indica "Non collegato", il valore non viene ancora inviato da nessuna parte.
Suggerimento su "Obbligatorio": Disattiva "Obbligatorio" per tutto ciò che proviene dalla conversazione. Se il valore non è disponibile, l'agente ometterà semplicemente il campo, invece di bloccare la richiesta o chiedere inutilmente al cliente.
Richiesta: metodo, URL, parametri di query e header
Metodo e URL: Scegli a sinistra il metodo HTTP (ad es. POST) e inserisci a destra l'URL della tua API o del tuo webhook.
Parametri di query: Coppie nome-valore aggiunte all'URL. Usa Aggiungi per crearne altre.
Header: Coppie nome-valore per gli header HTTP, ad es.
Content-Type. Le credenziali non vanno qui, ma nella scheda Credenziali.Timeout: Secondi dopo i quali la richiesta viene interrotta (predefinito: 30). Al telefono, il chiamante attende nel frattempo; mantieni il valore più basso possibile in base a quanto consente la tua API.
In tutti i campi puoi inserire un parametro tramite il pulsante { }.
Corpo: contenuto della richiesta
Scegli cosa invia la richiesta:
Nessun corpo: La richiesta non invia alcun contenuto. Adatto per query semplici.
JSON: Dati strutturati, lo standard per la maggior parte delle API e dei webhook.
Dati modulo: Campi modulo classici.
Testo semplice: Un contenuto testuale libero.
Anche qui inserisci i parametri tramite { }, ad es. {"numero_ordine": {{numero_ordine}}}.
Credenziali: autenticare l'API in modo sicuro
Se la tua API richiede una chiave API o un token, lo salvi qui. Seleziona credenziali esistenti dal menu a tendina oppure clicca su Crea nuove credenziali. Una volta create, le credenziali sono disponibili anche per altri strumenti.
Le credenziali vengono salvate in modo sicuro. L'Agente IA non vede né imposta mai questi valori, quindi non può nemmeno rivelarli accidentalmente durante la conversazione.
Test: eseguire una volta la richiesta reale
Prima di salvare, verifica la richiesta nella scheda Test. Inserisci un valore di esempio per ogni parametro e clicca su "Invia richiesta di test". La richiesta viene effettivamente inviata alla tua API, quindi usa dati di prova.
L'avviso "Non vengono utilizzati parametri da nessuna parte: questo strumento richiama sempre la stessa richiesta" significa che hai creato dei parametri ma non li hai inseriti da nessuna parte tramite { }, oppure che lo strumento funziona senza alcun parametro. Per una query fissa va bene così; non appena l'agente deve inviare valori dalla conversazione, inseriscili nell'URL, nell'header o nel corpo.
Clicca poi su Salva. Lo strumento compare nell'elenco sotto Strumenti e Azioni come Richieste HTTP: <Nome>.
Testare nella conversazione
Apri a destra l'Ambiente di test, scegli il canale (Chat, Telefono o Email) e poni al tuo Agente IA la domanda che dovrebbe attivare lo strumento. Così vedi se lo utilizza al momento giusto e se usa la risposta in modo sensato.
Se l'agente non usa lo strumento, affina prima il testo in Quando deve usare lo strumento l'agente? e menziona inoltre lo strumento in Attività e Regole sotto "Cosa deve fare il tuo agente?", ad es.: "Se un cliente chiede del suo ordine, verifica lo stato dell'ordine tramite lo strumento e comunicagli stato e data di consegna."
Importante: Nell'Ambiente di test non vengono condivisi gli attributi del contatto. Nell'Ambiente di test è possibile lavorare solo con i parametri che l'agente ricava dalla conversazione in corso. Usa una conversazione reale, avviata da te stesso, per testare con gli attributi del contatto.
Best practice
Formula la regola di utilizzo in modo positivo e negativo. Quando sì, quando no.
Mantieni le risposte snelle. L'agente legge la risposta della tua API. Più è chiara e breve, più precisa sarà la sua comunicazione al cliente.
Mantieni il timeout il più basso possibile. Il contatto percepisce ogni secondo di attesa. Al telefono consigliamo al massimo 10 secondi, in chat 30 secondi.
Testa con dati di prova. La richiesta di test e i test nell'Ambiente di test richiamano effettivamente la tua API.