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:

RuoloDescrizione
userUn visitatore del sito web in una chat.
adminUn agente umano che gestisce le sessioni di chat dal vivo.
widgetIl 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

  1. Apri il socket e invia client:join con chatbotId, sessionId e as.
  2. 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 di livechat:status.
  3. Invia client:message per pubblicare; ricevi livechat:message per ogni nuovo messaggio.
  4. Invia client:typing / ricevi livechat:typing per gli indicatori di digitazione.
  5. Termina con client:end, oppure ricevi livechat:ended quando 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
}
CampoTipoObbligatorioDescrizione
chatbotIdstringSìL'UUID del tuo Chatbot. Per un amministratore che monitora tutti i bot, il valore speciale "all" esegue l'accesso senza una stanza specifica.
sessionIdstringSìL'ID Sessione della chat.
asstringSìuser, admin o widget.
langstringNoCodice della lingua preferita (es. en, de, fr). Imposta la destinazione della traduzione.
translateEnabledbooleanNoAbilita la traduzione automatica per questa sessione (valore predefinito: abilitato).
retranslateBacklogbooleanNoRitraduci 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"
}
CampoTipoObbligatorioDescrizione
chatbotIdstringSìL'UUID del tuo Chatbot.
sessionIdstringSìL'ID Sessione della chat.
senderstringSìuser o admin.
contentstringSìIl testo del messaggio. Un valore di content vuoto o mancante viene scartato.
langstringNoIndicazione 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"
}
CampoTipoDescrizione
statusstringwaiting (nessun agente presente), open (agente connesso) o closed.
modestringbot o human.
userNamestring | nullNome del visitatore, se raccolto tramite Lead.
userEmailstring | nullEmail del visitatore, se raccolta.
userLanguagestring | nullLingua 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
}
CampoTipoDescrizione
idnumberID del messaggio (corrisponde all'id della cronologia REST).
senderstringuser, admin o system.
contentstringTesto del messaggio. Per i client admin con traduzione attiva, questo testo è già tradotto nella lingua dell'amministratore.
countrystring | nullCodice paese del mittente, se rilevato.
createdAtstringTimestamp ISO 8601.
fileobject | nullMetadati del file allegato (uploadId, name, mimeType, size, url, isImage) quando il messaggio è un caricamento.
audiencestring | null"admin" nella copia del messaggio destinata all'amministratore. La copia destinata all'utente lo omette.
historicalbooleantrue 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

EventoPayloadScopo
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: true e imposta lang sulla 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
  }));
}