API WebSocket di Chatbot (Chat dal vivo)

WebSocket API

Usa l'API WebSocket per la Chat dal vivo in tempo reale: recapito istantaneo dei messaggi, indicatori di digitazione, presenza, traduzione automatica e ciclo di vita della sessione. Lo stesso socket alimenta i widget per i visitatori e la dashboard dell'agente, consentendo di creare una console agente personalizzata o di gestire la Chat dal vivo dal proprio backend.

Endpoint

wss://webchatagent.com/api/livechat

Tutto il traffico è in formato JSON. Invii eventi client:*; il server risponde con eventi livechat:*. Ogni messaggio include un campo type.

Ruoli di Connessione

Quando ti connetti, dichiari un Ruolo tramite il campo as:

Il Ruolo determina cosa ricevi: i client admin ricevono l'intero storico dei messaggi e gli eventi riservati agli amministratori; i client user ricevono solo i nuovi eventi in tempo reale (i visitatori caricano la propria cronologia tramite l'endpoint di cronologia REST, non tramite il socket).

Flusso rapido

1. Apri il socket e invia client:join indicando 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 uno snapshot dello Stato livechat:status attuale.
3. Invia client:message per pubblicare un messaggio; 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 accedere alla stanza della sessione (e, per gli amministratori, alla stanza del Chatbot).

{
  "type": "client:join",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "as": "user",
  "lang": "en",
  "translateEnabled": true,
  "retranslateBacklog": false
}

client:message

Invia un Messaggio nella sessione. Il server lo memorizza, lo traduce se l'opzione è attiva 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"
}

Il primo Messaggio inviato da admin in una sessione in attesa la apre (Stato → open) e inserisce automaticamente un avviso di Sistema "agente connesso".

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 subentra in modo proattivo a una sessione AI (impostandola su open / human). Solo per admin.

{
  "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/annullare la registrazione di una sessione attiva per la Visibilità dell'amministratore (questo evento 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 uno snapshot dello Stato della sessione (riportato di seguito).

{
  "type": "livechat:status",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "status": "open",
  "mode": "human",
  "userName": "John",
  "userEmail": "john@example.com",
  "userLanguage": "en"
}

livechat:message

Un Messaggio nuovo (o proveniente dallo 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
}

Messaggi di Sistema: quando sender è system, content è un token che il client deve localizzare e non mostrare alla lettera: __agent_joined__, __livechat_ended__ o __livechat_timeout__.

livechat:typing

Indicatore di digitazione proveniente da 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 di sessione aggiornati (Pagina corrente, Titolo, referrer), solo per admin.

livechat:ended

La sessione è stata chiusa.

{
  "type": "livechat:ended",
  "sessionId": "SESSION_ID",
  "reason": "admin_closed"
}

Il campo reason assume uno dei seguenti valori: admin_closed, already_closed o timeout.

Eventi riservati agli amministratori

Traduzione automatica

Il socket può tradurre automaticamente i messaggi tra la Lingua del Visitatore e quella dell'agente:

• Accedi con translateEnabled: true e imposta lang sulla tua Lingua.
• I messaggi dell'interlocutore arrivano già tradotti nella tua Lingua indicata in lang. Ciascuna parte conserva il testo originale; la Copia tradotta viene recapitata all'altra parte.
• La Traduzione viene elaborata tramite Gemini, consentendo all'agente di chattare con un Visitatore in qualsiasi Lingua senza dover tradurre manualmente.

Esempio: Client di Chat dal vivo 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
  }));
}