API WebSocket per Chatbot (Chat dal vivo)
WebSocket API
Usa la WebSocket API per la live chat in tempo reale: recapito istantaneo dei messaggi, indicatori di digitazione, presenza, traduzione automatica e ciclo di vita della sessione. Lo stesso socket alimenta sia i widget dei visitatori sia la dashboard dell'agente, permettendo di creare una console per agenti personalizzata o di gestire la live chat dal proprio backend.
Endpoint
wss://webchatagent.com/api/livechat
Tutto il traffico è in formato JSON. Si inviano eventi client:* e il server restituisce eventi livechat:*. Ogni messaggio include un campo type.
Stai creando una chat per visitatori in JavaScript? L'SDK JavaScript gestisce automaticamente l'accesso, la riconnessione, la digitazione e la conclusione di una chat dal vivo:
chat.liveChat().
Ruoli di Connessione
Al momento dell'accesso, dichiara un ruolo con il campo as:
| Ruolo | Descrizione |
|---|---|
user | Un visitatore del sito web in una chat. |
admin | Un agente umano che gestisce le sessioni di chat dal vivo. |
widget | Il widget di chat incorporato in modalità di monitoraggio (prima di una presa in carico). |
Il ruolo determina cosa riceverai: i client admin ricevono lo storico completo dei messaggi e gli eventi riservati agli amministratori; i client user ricevono solo i nuovi eventi dal vivo (i visitatori caricano la propria cronologia tramite l'endpoint REST della cronologia, non tramite il socket).
Flusso rapido
- Apri il socket e invia
client:joinconchatbotId,sessionIdeas. - Il server risponde con
{ "type": "livechat:status", "ok": true }per confermare l'accesso. Gli amministratori ricevono quindi lo storico dei messaggi e un'istantanea attuale dilivechat:status. - Invia
client:messageper pubblicare; ricevilivechat:messageper ogni nuovo messaggio. - Invia
client:typing/ ricevilivechat:typingper gli indicatori di digitazione. - Termina con
client:end, oppure ricevilivechat:endedquando l'altra parte chiude la sessione.
Eventi client (inviati da te)
client:join
Il primo evento dopo la connessione. Consente di entrare nella stanza della sessione (e, per gli amministratori, nella stanza del Chatbot).
{
"type": "client:join",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"as": "user",
"lang": "en",
"translateEnabled": true,
"retranslateBacklog": false
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
chatbotId | string | Sì | L'UUID del tuo Chatbot. Per un amministratore che monitora tutti i bot, il valore speciale "all" esegue l'accesso senza una stanza specifica. |
sessionId | string | Sì | L'ID Sessione della chat. |
as | string | Sì | user, admin o widget. |
lang | string | No | Codice della lingua preferita (es. en, de, fr). Imposta la destinazione della traduzione. |
translateEnabled | boolean | No | Abilita la traduzione automatica per questa sessione (valore predefinito: abilitato). |
retranslateBacklog | boolean | No | Ritraduci i messaggi dello storico esistenti in lang al momento dell'accesso (admin). |
client:message
Invia un messaggio nella sessione. Il server lo memorizza, lo traduce se l'opzione è abilitata e trasmette livechat:message.
{
"type": "client:message",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"sender": "user",
"content": "I need help with my order",
"lang": "en"
}
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
chatbotId | string | Sì | L'UUID del tuo Chatbot. |
sessionId | string | Sì | L'ID Sessione della chat. |
sender | string | Sì | user o admin. |
content | string | Sì | Il testo del messaggio. Un valore di content vuoto o mancante viene scartato. |
lang | string | No | Indicazione della lingua del messaggio per la traduzione. |
Il primo messaggio dell'admin in una sessione in attesa la apre (stato → open) e inserisce automaticamente una notifica di sistema che segnala l'ingresso dell'agente.
client:typing
Trasmette un indicatore di digitazione a tutti i partecipanti alla sessione.
{
"type": "client:typing",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"sender": "user",
"isTyping": true
}
client:meta
Aggiorna i metadati della sessione (pagina corrente), in modo che gli agenti possano vedere dove si trova il visitatore.
{
"type": "client:meta",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"pageUrl": "https://example.com/pricing",
"pageTitle": "Pricing - Example",
"referrer": "https://google.com",
"browserLanguage": "en-US"
}
client:agent_takeover
L'amministratore assume proattivamente il controllo di una sessione IA (impostandola su open / human). Riservato agli amministratori.
{
"type": "client:agent_takeover",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID"
}
client:end
Termina la sessione.
{
"type": "client:end",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"reason": "resolved"
}
client:widget_open / client:widget_close
Inviato dal widget per registrare o annullare la registrazione di una sessione attiva per la visibilità dell'amministratore (questo popola livechat:widget_sessions).
{
"type": "client:widget_open",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"pageUrl": "https://example.com",
"pageTitle": "Home",
"browserLanguage": "en-US"
}
Eventi server (ricevuti da te)
livechat:status
Due formati: una semplice conferma di accesso { "type": "livechat:status", "ok": true } e un'istantanea dello stato della sessione (riportata sotto).
{
"type": "livechat:status",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"status": "open",
"mode": "human",
"userName": "John",
"userEmail": "john@example.com",
"userLanguage": "en"
}
| Campo | Tipo | Descrizione |
|---|---|---|
status | string | waiting (nessun agente presente), open (agente connesso) o closed. |
mode | string | bot o human. |
userName | string | null | Nome del visitatore, se raccolto tramite Lead. |
userEmail | string | null | Email del visitatore, se raccolta. |
userLanguage | string | null | Lingua rilevata del visitatore. |
livechat:message
Un messaggio nuovo (o dello storico).
{
"type": "livechat:message",
"id": 1024,
"sessionId": "SESSION_ID",
"sender": "admin",
"content": "Hello! How can I help you today?",
"country": "DE",
"createdAt": "2025-01-15T10:30:00Z",
"file": null,
"audience": "admin",
"historical": false
}
| Campo | Tipo | Descrizione |
|---|---|---|
id | number | ID del messaggio (corrisponde all'id della cronologia REST). |
sender | string | user, admin o system. |
content | string | Testo del messaggio. Per i client admin con traduzione attiva, questo testo è già tradotto nella lingua dell'amministratore. |
country | string | null | Codice paese del mittente, se rilevato. |
createdAt | string | Timestamp ISO 8601. |
file | object | null | Metadati del file allegato (uploadId, name, mimeType, size, url, isImage) quando il messaggio è un caricamento. |
audience | string | null | "admin" nella copia del messaggio destinata all'amministratore. La copia destinata all'utente lo omette. |
historical | boolean | true per i messaggi dello storico riprodotti all'accesso. |
Messaggi di sistema: quando
senderèsystem,contentè un token che il client deve localizzare e non mostrare letteralmente:__agent_joined__,__livechat_ended__o__livechat_timeout__.
livechat:typing
Indicatore di digitazione da parte di un altro partecipante: { type, chatbotId, sessionId, sender, isTyping }.
livechat:presence
Stato online/offline del visitatore in una sessione: { type, chatbotId, sessionId, online } (boolean).
livechat:meta
Metadati aggiornati della sessione (pagina corrente, titolo, referrer), solo per amministratori.
livechat:ended
La sessione è stata chiusa.
{
"type": "livechat:ended",
"sessionId": "SESSION_ID",
"reason": "admin_closed"
}
Il valore di reason può essere user_closed (il visitatore l'ha terminata tramite POST /api/livechats/end), admin_closed (terminata tramite socket) o already_closed (ti sei unito a una sessione che era già terminata).
Una chat in attesa che nessun agente prende in carico viene chiusa dal server con un evento livechat:status (status: "closed") e senza livechat:ended. Considera entrambi i casi come la fine della chat dal vivo.
Eventi riservati agli amministratori
| Evento | Payload | Scopo |
|---|---|---|
livechat:active_count | { chatbotId, count } | Sessioni attive (in attesa + aperte). |
livechat:waiting_count | { chatbotId, count } | Sessioni in attesa (badge per le chat senza risposta). |
livechat:new_request | { chatbotId, sessionId, status, mode, ... } | Una nuova chat dal vivo richiede un agente. |
livechat:widget_sessions | { chatbotId, chatbotName, sessions } | Elenco attuale delle sessioni del widget attive. |
livechat:notification | { chatbotId, sessionId, content, sender } | Nuovo messaggio mentre l'agente si trova in un'altra sezione della dashboard. |
Traduzione automatica
Il socket può tradurre automaticamente tra la lingua del visitatore e quella dell'agente:
- Esegui l'accesso con
translateEnabled: truee impostalangsulla tua lingua. - I messaggi dell'altra parte arrivano già tradotti nella tua
lang. Ciascuna parte mantiene il proprio testo originale; la copia tradotta viene recapitata alla controparte. - La traduzione viene eseguita tramite Azure OpenAI nell'UE, consentendo all'agente di conversare con un visitatore in qualsiasi lingua senza dover tradurre manualmente.
Esempio: Client di live chat personalizzato
const ws = new WebSocket('wss://webchatagent.com/api/livechat');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'client:join',
chatbotId: 'YOUR_CHATBOT_ID',
sessionId: 'SESSION_ID',
as: 'user',
lang: 'en'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
switch (data.type) {
case 'livechat:status':
// Join ack ({ ok: true }) or a session snapshot ({ status, mode, ... })
if (data.ok) console.log('Joined');
else console.log(`Status: ${data.status}, mode: ${data.mode}`);
break;
case 'livechat:message':
if (data.sender === 'system') {
// Localize tokens like __agent_joined__ / __livechat_ended__
console.log('[system]', data.content);
} else {
console.log(`${data.sender}: ${data.content}`);
}
break;
case 'livechat:typing':
console.log(`${data.sender} is typing: ${data.isTyping}`);
break;
case 'livechat:ended':
console.log(`Session ended: ${data.reason}`);
ws.close();
break;
}
};
function sendMessage(text) {
ws.send(JSON.stringify({
type: 'client:message',
chatbotId: 'YOUR_CHATBOT_ID',
sessionId: 'SESSION_ID',
sender: 'user',
content: text,
lang: 'en'
}));
}
function sendTyping(isTyping) {
ws.send(JSON.stringify({
type: 'client:typing',
chatbotId: 'YOUR_CHATBOT_ID',
sessionId: 'SESSION_ID',
sender: 'user',
isTyping
}));
}
