API chatbot
Una API chatbot per le tue app, il tuo backend e i tuoi dati
La REST API di intoCHAT permette al tuo server di parlare con l'agente che hai addestrato nella dashboard. Invia un messaggio e ricevi la stessa risposta che darebbe il widget di chat, leggi conversazioni e lead, mantieni sincronizzati i contatti, aggiungi conoscenza e registra webhook, con JSON su HTTPS e una specifica OpenAPI 3.1 che descrive ogni endpoint.
Il tuo chatbot non dovrebbe fermarsi al widget del sito
Il widget copre i visitatori del tuo sito. Ma le stesse domande arrivano anche nella tua app mobile, nel portale clienti, in uno strumento interno o in un modulo di assistenza, e le conversazioni e i lead raccolti dall'agente devono finire nel tuo CRM, nel data warehouse o nel sistema di ticketing, non solo in una dashboard. Ricostruire il bot per ogni canale significa una seconda base di conoscenza e un secondo insieme di regole che col tempo divergono. Con una API chatbot ogni canale che costruisci usa l'unico agente che hai già addestrato, e i tuoi sistemi leggono ciò che ha raccolto.
Cosa ti offre la API chatbot
Un agente, addestrato una volta, che risponde ovunque giri il tuo codice.
Stesso agente, stesse risposte
Una risposta tramite API viene scritta dallo stesso codice di una risposta nel widget, con la stessa conoscenza, le stesse istruzioni e lo stesso modello. Le tue azioni API, i pulsanti personalizzati, i moduli in chat e le prenotazioni funzionano anche nelle chat via API.
Conversazioni che continuano
Passa un tuo sessionId, per esempio l'ID utente, e la stessa persona continua sempre la stessa conversazione. L'agente vede gli ultimi 40 messaggi come cronologia, e ogni chat via API compare nella scheda Conversations accanto alle chat del widget.
I tuoi dati nei tuoi sistemi
Scorri le conversazioni con le trascrizioni complete, i lead con i loro campi personalizzati e i contatti, dai più recenti, con il parametro since per le sincronizzazioni incrementali. L'ordine è fisso, quindi nulla viene letto due volte o saltato mentre arrivano nuove chat.
Una chiave con i suoi scope per ogni compito
Dai a ogni integrazione la sua chiave con solo gli scope che le servono, per esempio conversations:read per un report e chat per la tua app. Le chiavi appartengono all'account, non a una persona, e smettono di funzionare non appena le revochi.
Una specifica OpenAPI da cui partire
Ogni endpoint, campo, errore e contenuto dei webhook è descritto in un unico file OpenAPI 3.1. Importalo in Postman o Insomnia, oppure genera una libreria client con uno strumento come OpenAPI Generator.
Come iniziare con la API chatbot
Addestra il tuo agente
Crea l'agente nella dashboard, aggiungi il tuo sito, file o Q&A e imposta istruzioni e modello. La API usa l'agente esattamente come è configurato lì; gli agenti si creano e si modificano nella dashboard, non tramite la API.
Crea una chiave API
Nella barra laterale, sotto Settings, fai clic su API keys. Dai un nome alla chiave, lascia Every scope, including ones added later oppure scegli Only the scopes I choose, e fai clic su Create key. Copia la chiave, che inizia con ic_live_, in una variabile d’ambiente sul tuo server: viene mostrata una sola volta.
Invia il primo messaggio
Invia il messaggio con una POST a /api/v1/agents/{agentId}/chat, con la chiave come token Bearer nell’intestazione Authorization. La risposta JSON contiene il testo, il conversationId e il sessionId per continuare, le fonti usate ed eventuali domande di follow-up, pulsanti, prodotti, moduli o orari prenotabili. Con stream impostato a true ricevi il testo mentre viene scritto.
Sincronizza e registra webhook
Leggi periodicamente conversazioni, lead e contatti con since, aggiungi testi o coppie Q&A quando i tuoi contenuti cambiano e registra un webhook per eventi come lead.created o handoff.requested, così arrivano al tuo server nel momento in cui accadono.
La API chatbot nel dettaglio
Inviare un messaggio
L'endpoint di chat accetta un messaggio fino a 10.000 caratteri, un conversationId o sessionId facoltativo per continuare, stream per il testo in streaming e timeZone per gli orari delle prenotazioni. Senza nessuno dei due ID, ogni messaggio apre una nuova conversazione.
Campi di risposta strutturati
Oltre alla risposta in Markdown, la response elenca le pagine usate, le domande di follow-up suggerite, i pulsanti personalizzati, le schede prodotto con prezzo e disponibilità, un modulo in chat o di contatto proposto, gli orari liberi, i blocchi di risposte ricche come tabelle e schede e lo stato della live chat.
Consapevole della live chat
Se qualcuno del tuo team ha preso in carico la conversazione nell'inbox della live chat, il tuo messaggio viene salvato, la risposta resta vuota e liveChat vale paused. Leggi le risposte del tuo collega, con il nome, dall'endpoint della conversazione. Questi messaggi non consumano i messaggi del tuo piano.
Conversazioni e Inbox
Elenca le conversazioni di un agente da widget e API con argomenti, sentiment, stato della live chat e voto CSAT, filtrale per stato nell'Inbox e recuperane una con tutti i messaggi. Con conversations:write imposti stato, priorità, tag e assegnatario nell'Inbox.
Lead e contatti
Elenca i lead con nome, email, telefono e i campi personalizzati del tuo modulo. Crea o aggiorna contatti tramite il tuo ID esterno o l'email, ognuno con fino a 50 attributi personalizzati, così i contatti dell'agente corrispondono agli utenti della tua app.
Conoscenza che puoi aggiornare
Elenca le fonti di un agente con il loro stato di addestramento, aggiungi un testo o una coppia Q&A, che viene addestrata subito, ed elimina una fonte insieme a ciò che l'agente ne aveva imparato. Una coppia Q&A con la stessa domanda viene aggiornata invece che duplicata.
Webhook ed eventi
Registra fino a 25 webhook per agente per eventi come lead.created, form.submitted, booking.created, handoff.requested e conversation.status_changed, ognuno firmato con il proprio secret. Oppure interroga gli ultimi eventi di un tipo, strutturati esattamente come una consegna webhook.
Limiti ed errori chiari
Ogni chiave può fare 60 richieste al minuto e ogni risposta riporta le intestazioni X-RateLimit. Gli errori hanno sempre la stessa forma JSON con un codice stabile, come insufficient_scope, rate_limited o message_limit_reached, così il tuo codice può gestire ogni caso.
Domande frequenti
Cos'è una API chatbot?
Una API chatbot permette al tuo software di inviare messaggi a un chatbot e riceverne le risposte, invece che solo tramite una finestra di chat su un sito. La REST API di intoCHAT lo fa per l'agente che hai addestrato nella dashboard, e permette inoltre al tuo server di leggerne conversazioni, lead e contatti, aggiornarne la conoscenza e registrarsi ai suoi eventi.
Quale piano mi serve per la API?
La API è inclusa nei piani Starter, Pro ed Enterprise. Con il piano Free non puoi creare chiavi. Se un account torna a Free, le sue chiavi esistenti rispondono a ogni richiesta con l'errore plan_required e tornano a funzionare non appena l'account passa almeno a Starter.
Le risposte via API contano come messaggi?
Sì. Ogni risposta che l'agente scrive tramite la API conta sul tuo piano esattamente come una risposta nel widget: un messaggio con il modello predefinito, di più con un modello più grande, e conta anche sul tetto mensile dell'agente se ne hai impostato uno. Leggere conversazioni, lead e contatti e aggiungere o eliminare fonti non consuma messaggi.
Posso chiamare la API dal browser o dal codice di incorporamento?
No. La API è pensata per i server: non invia intestazioni CORS, e una chiave in una pagina web potrebbe copiarla chiunque. Per mostrare una chat sul tuo sito usa il tag script o il JavaScript SDK, e chiama la API dal tuo backend. Solo la specifica OpenAPI si può caricare da qualsiasi sito.
Come continuo una conversazione?
Invia il conversationId di una risposta precedente, oppure un tuo sessionId, per esempio l'ID utente: lo stesso sessionId continua sempre la stessa conversazione. Tramite la API si possono continuare solo le conversazioni iniziate tramite la API, e l'agente vede gli ultimi 40 messaggi come cronologia.
Quali sono i limiti di frequenza?
Ogni chiave può fare 60 richieste al minuto su tutti gli endpoint, e un account può avere fino a 20 chiavi attive. Un agente risponde al massimo a 1.000 messaggi l’ora, widget e API insieme, e una risposta deve concludersi entro 55 secondi, altrimenti la richiesta termina con un errore di timeout.
Cosa non può ancora fare la API?
Non ci sono ancora endpoint per creare o modificare agenti, inviare moduli in chat, prenotare appuntamenti o prendere in carico live chat. Tramite la API aggiungi testi e coppie Q&A; pagine web, file e pagine Notion si aggiungono nella dashboard. I messaggi via API non possono contenere file, e le azioni client, che girano nel browser di un visitatore, non vengono offerte nelle chat via API.
In cosa si differenzia dalle azioni AI?
Vanno in direzioni opposte. Con le azioni AI è l'agente a chiamare la tua API durante una chat per cercare qualcosa, come un ordine o un account. Con la API chatbot è il tuo server a chiamare intoCHAT per inviare messaggi e leggere dati. Molte configurazioni usano entrambe.
Costruisci sull'agente che hai già addestrato
Crea gratis il tuo agente e addestralo sul tuo sito, poi passa a Starter, crea una chiave API e invia il primo messaggio con un solo comando curl.
Crea il tuo agente gratisPiano gratuito, nessuna carta di credito.