Azioni API personalizzate: chiama la tua API in chat

Un'azione API personalizzata permette all'agente di chiamare un endpoint HTTP durante la conversazione, per esempio per controllare disponibilità o prezzi aggiornati, e di rispondere in base alla risposta ricevuta. Le azioni si creano nella scheda Actions (azioni) dell'agente. Se vuoi che l'agente offra un link invece di chiamare un'API, vedi Pulsanti personalizzati.

Creare un'azione

Fai clic su Add Action, oppure su Import a request per partire da un comando cURL. L'editor ha quattro passaggi e si salva una sola volta alla fine con Create action. Il test è facoltativo ma consigliato.

1. The request (la richiesta)

• Method: GET, POST, PUT, PATCH o DELETE.
• HTTPS URL: l'endpoint. Una query string incollata nell'URL viene spostata nella scheda Parameters.
• Parameters, Headers e Body accettano coppie chiave e valore. Body è disponibile per tutti i metodi tranne GET e viene inviato come JSON.
• Collect data inputs for action (optional): valori che l'agente ricava dalla conversazione. Ogni input ha un Name (lettere, numeri e trattini bassi), un Type (Text, Number o Boolean), una Description e le opzioni Required e Array. Fino a 25 input per azione.

Usa un input in qualsiasi punto della richiesta come {{name}}: nel percorso dell'URL, in un parametro, in un header o nel body.

GET https://api.example.com/products/{{productId}}/stock

L'agente trova il valore nella conversazione o lo chiede al visitatore. Un input Required impedisce all'agente di chiamare l'azione prima di avere quel valore. Le variabili usate ma non dichiarate come input vengono tolte dalla richiesta; l'editor ti avvisa e propone Add them.

Autenticazione

Importare una richiesta

Incolla l'esempio cURL dalla documentazione della tua API, oppure usa "Copy as cURL" su una richiesta negli strumenti di rete del browser. Metodo, URL, parametri, header e body vengono compilati, e la credenziale finisce nel selettore Authentication. L'importazione sostituisce la richiesta ma mantiene nome e descrizione. Gli upload multipart (-F) vengono saltati e un body in formato form viene importato come campi JSON.

2. Try it (prova)

Inserisci valori di prova per gli input e fai clic su Send test request. La richiesta viene costruita esattamente come la costruirà l'agente. La Response Preview mostra lo stato, il corpo della risposta e l'URL chiamato.

3. When the AI should use it (quando usarla)

• Action Name: fino a 60 caratteri.
• When to use: che cosa fa l'azione, quali dati restituisce ed esempi di domande che devono attivarla. Il modello legge i primi 1.024 caratteri.
• Server-side action viene eseguita sui server di intoCHAT ed è l'impostazione predefinita. Client-side action viene eseguita nel browser del visitatore; vedi Azioni lato client.
• Enable this action: disattiva un'azione senza eliminarla.

4. What the AI can see (che cosa vede l'AI)

Full data access passa al modello tutta la risposta. Limited data access passa solo i campi che selezioni in Visible; esegui prima un test per caricare l'elenco dei campi. Se la risposta è un elenco, i campi vengono letti dal primo elemento e il filtro vale per tutti. Finché non selezioni almeno un campo, passa la risposta completa.

Limiti e sicurezza

• Fino a 25 azioni per agente, compresi i pulsanti personalizzati e le azioni create da Collega il tuo negozio.
• L'URL deve puntare a un host pubblico. Localhost, reti private, indirizzi link-local ed endpoint di metadati cloud vengono rifiutati, anche quando un nome host si risolve in uno di questi. L'editor mostra allora "URL points to a blocked or internal host".
• I reindirizzamenti non vengono seguiti. Se il test mostra "This address redirects somewhere else", fai clic su Use this address.
• Ogni chiamata scade dopo 30 secondi.
• Le risposte oltre 40.000 caratteri vengono troncate. Con Limited data access restano piccole.
• Le azioni lato server inviano le tue credenziali dai server di intoCHAT, mai attraverso il browser del visitatore.