Azioni API personalizzate: chiama la tua API in chat
Fai chiamare la tua API HTTP all'agente intoCHAT durante la chat: richiesta e autenticazione, import da cURL, input presi dalla conversazione e test.
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.
Segnaposto per i visitatori verificati
Con la verifica dell'identità configurata, un'azione lato server può usare anche {{user.id}}, {{user.email}}, {{user.name}} e {{user.metadata.<key>}} nell'URL, nei parametri, negli header e nel body:
GET https://api.example.com/customers/{{user.id}}/orders
Non sono input di dati: intoCHAT li compila sui propri server a partire dal visitatore che il tuo sito ha fatto accedere e verificato, e li lascia vuoti per tutti gli altri e in Send test request. L'AI non li vede mai e non può sceglierli. Qualsiasi altro segnaposto {{user.…}} non si può salvare. Vedi Segnaposto nelle azioni lato server.
Segnaposto per i contatti
Un'azione lato server può leggere anche il contatto del visitatore: {{contact.email}}, {{contact.name}}, {{contact.phone}}, {{contact.external_id}} e {{contact.<attribute>}}, come {{contact.plan}}:
GET https://api.example.com/accounts/{{contact.external_id}}?plan={{contact.plan}}
Per un visitatore verificato è il contatto con il suo ID utente; per tutti gli altri, il contatto del lead salvato nella conversazione, a meno che quel contatto abbia un external ID. intoCHAT li compila sui propri server e l'AI non li vede mai. A differenza di {{user.*}}, non viene inviato nulla di vuoto: se non c'è un contatto o manca un valore, l'azione non viene eseguita e all'agente viene detto che qui non può farlo. I segnaposto sconosciuti come {{contact.Plan}} non si possono salvare, Send test request non può compilarli e le azioni lato client non li ricevono mai. Vedi Usare i contatti nelle azioni.
Autenticazione
| Opzione | Che cosa viene inviato |
|---|---|
| No authentication | Niente |
| Bearer token / access token | Un header Authorization: Bearer con il tuo token |
| API key in a header | La chiave nell'header che indichi, per esempio X-API-Key |
| API key in the URL | La chiave come parametro di query con il nome che indichi, per esempio api_key |
| Username and password | Autenticazione HTTP basic |
| Custom — I'll set the headers myself | Ciò che aggiungi nella scheda Headers |
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.
- Only inside procedures (solo azioni lato server): l'agente può chiamare l'azione solo in un passo di una procedura che la chiama, mai di sua iniziativa. Una chiamata in qualsiasi altro momento viene rifiutata e non viene inviato nulla. Usalo per le azioni che modificano qualcosa, come un rimborso. Nell'elenco l'azione mostra allora il badge Procedure only.
- Requires team approval (solo azioni lato server, Pro ed Enterprise): quando l'agente chiama l'azione, non viene ancora inviato nulla. La chiamata, con i suoi input, resta in attesa nella pagina Approvals finché qualcuno che può modificare questo agente non la approva (allora viene eseguita esattamente con quegli input) o la rifiuta, e al visitatore viene comunicato l'esito in chat. Scegli quando scade una richiesta senza decisione: 1 ora, 4 ore, 24 ore o 3 giorni. Nell'elenco l'azione mostra il badge Needs approval. Vedi Approvazione del team per le azioni.
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.
- I moduli in chat, le procedure, la prenotazione con Cal.com o Calendly e la ricerca web non contano in questo limite.
- Un'azione chiamata da un passo di una procedura non si può eliminare né trasformare in un'azione lato client o in un pulsante finché non la togli dalla procedura. Il messaggio indica le procedure.
- Un'azione API o un pulsante con il nome di uno strumento integrato, come "search web" o "show booking slots", viene rinominato dietro le quinte con un numero (
search_web_2), così la ricerca web e la prenotazione continuano a funzionare. Un'azione lato client mantiene il suo nome esatto, perché il gestore della tua pagina è registrato con quel nome: non chiamarne unasearch_web, altrimenti l'agente non può usare la ricerca web finché quell'azione è attiva. - 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.