Integrazione API Chatbot
Integra WebChatAgent in app desktop, terminali e strumenti interni via REST API — e passa a WebSocket per un live chat reale.
Porta la chat nella tua app, non solo sul sito.
Non tutto è un browser. Con la nostra Chatbot API puoi creare UX conversazionali direttamente nel tuo software — client desktop, strumenti CLI e portali interni.
Quali problemi risolve la Chatbot API?
Ostacoli tipici di integrazione — e come un'API li risolve in modo pulito.
Un widget web non basta
Le app desktop, gli strumenti interni o i terminali richiedono un'integrazione nativa — non un widget web incorporato.
Esperienze chat incoerenti
Senza un'API chiara, la chat diventa un caso speciale. Con endpoint dedicati mantieni l'UX coerente nei tuoi flussi e componenti.
Il live chat richiede tempo reale
Quando un umano prende il controllo, conta il real-time: stato, messaggi e file devono arrivare subito — per questo serve WebSocket.
Come l'API risolve questi problemi?
Inizia con REST per il bot chat — e passa a WebSocket per l'human takeover.
REST API per qualsiasi frontend
Invia messaggi via POST a /api/chat e renderizza la risposta nella tua UI. Perfetto per desktop, mobile, backoffice e CLI.
WebSocket per Live Chat (human takeover)
Quando il mode passa a human, connettiti via WebSocket e scambia messaggi in tempo reale — con session guard.
Esempi di codice
Parti in pochi minuti: cURL per test rapidi, JavaScript per integrazioni in produzione.
# 1) First request (no session id). Use -i to see response headers.
curl -i -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Hello, how can you help me?",
"chatbotId": "<your-chatbot-id>"
}'
# 2) Reuse the X-Chat-Session-Id from the response header for the conversation.
curl -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-H "X-Chat-Session-Id: <session-id-from-response>" \
-d '{
"message": "Continue the conversation.",
"chatbotId": "<your-chatbot-id>"
}'async function sendChatMessage({ baseUrl, chatbotId, message, sessionId }) {
const res = await fetch(`${baseUrl}/api/chat`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Chat-Session-Id': sessionId || ''
},
body: JSON.stringify({ message, chatbotId })
});
const nextSessionId = res.headers.get('X-Chat-Session-Id') || sessionId || '';
if (!res.ok) throw new Error(await res.text());
const data = await res.json();
// data: { reply, sources, mode, status }
// If mode === 'human' and status === 'waiting' or 'open', switch to WebSocket
if (data.mode === 'human' && (data.status === 'waiting' || data.status === 'open')) {
// Switch to WebSocket for live chat
connectToLiveChat(nextSessionId, chatbotId);
}
return { data, sessionId: nextSessionId };
}Gestione sessione: se non invii X-Chat-Session-Id, il server crea una nuova sessione e restituisce la session id nell'header di risposta. Salvala e inviala nelle richieste successive.
Esempio di risposta quando si passa al live chat: [ "reply": "...", "sources": [], "mode": "human", "status": "waiting" ] — poi passa a WebSocket.
Cosa considerare per il Live Chat
Il Live Chat funziona via WebSocket. Dopo la connessione, fai join con chatbotId + sessionId e invia messaggi come client:message. Gestisci solo gli eventi della sessione corrente.
// Use the same base URL as your REST calls (WebChatAgent domain).
const ws = new WebSocket('wss://webchatagent.com/api/livechat');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'client:join',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
as: 'user'
}));
};
function sendLiveChatMessage(text) {
ws.send(JSON.stringify({
type: 'client:message',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
sender: 'user',
content: text
}));
}
ws.onmessage = (event) => {
const data = JSON.parse(event.data || '{}');
// data.type === 'livechat:message'
// data.sessionId guard recommended (handle only current session)
};Usa REST (/api/chat) finché la conversazione è in modalità bot.
Controlla la risposta: Se mode='human' e status='waiting' o 'open' viene restituito, passa a WebSocket (/api/livechat).
Implementa un session guard: ignora eventi senza sessionId o con una sessionId diversa.
Use case tipici
Esempi di come i team integrano supporto e workflow direttamente nel software.
Supporto in app desktop
Aiuto in-app, troubleshooting e onboarding — senza cambiare contesto nel browser.
Assistente Terminal / CLI
Risposte e istruzioni nel terminale — ideale per DevOps, IT e strumenti interni.
Portali interni & backoffice
Self-service per dipendenti: policy, processi e knowledge — direttamente nell'intranet.
Escalation al live chat
Automatizza con il bot — e passa a un umano quando serve (WebSocket).
Integra la chat dove sono già i tuoi utenti.
Inizia con REST e aggiungi il live chat quando serve. Pensato per integrazioni in produzione: veloce, stabile e manutenibile.
Crea un account