Chatbot WebSocket API (Live chat)

WebSocket API

Gebruik de WebSocket API voor realtime live chat: directe berichtbezorging, type-indicatoren, aanwezigheid, automatische vertaling en de levenscyclus van sessies. Dezelfde socket stuurt bezoekerswidgets en het dashboard voor medewerkers aan, zodat je een aangepaste medewerkersconsole kunt bouwen of live chat vanuit je eigen backend kunt beheren.

Endpoint

wss://webchatagent.com/api/livechat

Al het verkeer is JSON. Je verstuurt client:*-events; de server stuurt livechat:*-events terug. Elk bericht bevat een type-veld.

Bouw je een bezoekerschat in JavaScript? De JavaScript SDK verzorgt het deelnemen, opnieuw verbinden, typen en het beëindigen van een live chat automatisch voor je: chat.liveChat().

Verbindingsrollen

Wanneer je verbinding maakt, geef je een rol op met het as-veld:

RolBeschrijving
userEen websitebezoeker in een chat.
adminEen menselijke medewerker die livechatsessies beheert.
widgetDe ingesloten chatwidget in monitoringmodus (vóór een overname).

De rol bepaalt wat je ontvangt: admin-clients ontvangen de volledige berichtengeschiedenis en events die alleen voor beheerders bedoeld zijn; user-clients ontvangen alleen nieuwe live-events (bezoekers laden hun eigen geschiedenis via het REST-geschiedenis-endpoint, niet via de socket).

Korte flow

  1. Open de socket en verstuur client:join met je chatbotId, sessionId en as.
  2. De server antwoordt met { "type": "livechat:status", "ok": true } om de deelname te bevestigen. Admins ontvangen vervolgens de eerdere berichten en een actuele livechat:status-momentopname.
  3. Verstuur client:message om een bericht te plaatsen; ontvang livechat:message voor elk nieuw bericht.
  4. Verstuur client:typing / ontvang livechat:typing voor type-indicatoren.
  5. Sluit af met client:end, of ontvang livechat:ended wanneer de andere partij de chat beëindigt.

Client-events (die je verstuurt)

client:join

Het eerste event na het verbinden. Neemt deel aan de sessieruimte (en, voor beheerders, de chatbotruimte).

{
  "type": "client:join",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "as": "user",
  "lang": "en",
  "translateEnabled": true,
  "retranslateBacklog": false
}
VeldTypeVerplichtBeschrijving
chatbotIdstringJaDe UUID van je chatbot. Voor een beheerder die alle bots monitort, zorgt de speciale waarde "all" voor deelname zonder specifieke ruimte.
sessionIdstringJaDe sessie-ID van de chat.
asstringJauser, admin of widget.
langstringNeeVoorkeurstaalcode (bijv. en, de, fr). Bepaalt het vertaaldoel.
translateEnabledbooleanNeeSchakel automatische vertaling in voor deze sessie (standaard: ingeschakeld).
retranslateBacklogbooleanNeeVertaal bestaande eerdere berichten opnieuw naar lang bij deelname (admin).

client:message

Plaats een bericht in de sessie. De server slaat het op, vertaalt het indien ingeschakeld en broadcast livechat:message.

{
  "type": "client:message",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "content": "I need help with my order",
  "lang": "en"
}
VeldTypeVerplichtBeschrijving
chatbotIdstringJaDe UUID van je chatbot.
sessionIdstringJaDe sessie-ID van de chat.
senderstringJauser of admin.
contentstringJaDe tekst van het bericht. Een lege of ontbrekende content wordt genegeerd.
langstringNeeTaalsuggestie van het bericht voor de vertaling.

Het eerste admin-bericht in een sessie met de status waiting opent deze (status → open) en voegt automatisch een systeembericht toe dat de medewerker heeft deelgenomen.

client:typing

Broadcast een type-indicator naar iedereen in de sessie.

{
  "type": "client:typing",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "isTyping": true
}

client:meta

Werk de sessiemetadata bij (huidige pagina), zodat medewerkers zien waar de bezoeker zich bevindt.

{
  "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

Beheerder neemt proactief een AI-sessie over (zet deze op open / human). Alleen voor beheerders.

{
  "type": "client:agent_takeover",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID"
}

client:end

Beëindig de sessie.

{
  "type": "client:end",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "reason": "resolved"
}

client:widget_open / client:widget_close

Verzonden door de widget om een actieve sessie te registreren of af te melden voor beheerderzichtbaarheid (dit vult livechat:widget_sessions).

{
  "type": "client:widget_open",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "pageUrl": "https://example.com",
  "pageTitle": "Home",
  "browserLanguage": "en-US"
}

Server-events (die je ontvangt)

livechat:status

Twee vormen: een eenvoudige { "type": "livechat:status", "ok": true } als bevestiging van deelname, en een momentopname van de sessiestatus (hieronder).

{
  "type": "livechat:status",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "status": "open",
  "mode": "human",
  "userName": "John",
  "userEmail": "john@example.com",
  "userLanguage": "en"
}
VeldTypeBeschrijving
statusstringwaiting (nog geen medewerker), open (medewerker verbonden) of closed.
modestringbot of human.
userNamestring | nullNaam van de bezoeker, indien verzameld via Leads.
userEmailstring | nullE-mailadres van de bezoeker, indien verzameld.
userLanguagestring | nullGedetecteerde taal van de bezoeker.

livechat:message

Een nieuw (of eerder) bericht.

{
  "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
}
VeldTypeBeschrijving
idnumberBericht-ID (komt overeen met het REST-geschiedenis-id).
senderstringuser, admin of system.
contentstringBerichttekst. Voor admin-clients waarbij vertaling is ingeschakeld, is dit al vertaald naar de taal van de beheerder.
countrystring | nullLandcode van de afzender, indien gedetecteerd.
createdAtstringISO 8601-tijdstempel.
fileobject | nullMetadata van het bijgevoegde bestand (uploadId, name, mimeType, size, url, isImage) wanneer het bericht een upload is.
audiencestring | null"admin" op de versie van een bericht die voor de beheerder bestemd is. De versie voor de gebruiker laat dit veld weg.
historicalbooleantrue voor eerdere berichten die opnieuw worden afgespeeld bij deelname.

Systeemberichten: wanneer sender gelijk is aan system, is content een token dat je client moet lokaliseren en niet letterlijk moet tonen: __agent_joined__, __livechat_ended__ of __livechat_timeout__.

livechat:typing

Type-indicator van een andere deelnemer: { type, chatbotId, sessionId, sender, isTyping }.

livechat:presence

Online/offline-status van de bezoeker in een sessie: { type, chatbotId, sessionId, online } (boolean).

livechat:meta

Bijgewerkte sessiemetadata (huidige pagina, titel, referrer), alleen voor beheerders.

livechat:ended

De sessie is gesloten.

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

reason is user_closed (de bezoeker heeft de sessie beëindigd via POST /api/livechats/end), admin_closed (beëindigd via de socket) of already_closed (je nam deel aan een sessie die al afgelopen was).

Een wachtende chat die door geen enkele medewerker wordt aangenomen, wordt door de server gesloten met een livechat:status-event (status: "closed") en zonder livechat:ended. Behandel beide als het einde van de live chat.

Events alleen voor beheerders

EventPayloadDoel
livechat:active_count{ chatbotId, count }Actieve sessies (wachtend + open).
livechat:waiting_count{ chatbotId, count }Wachtende sessies (badge voor onbeantwoorde chats).
livechat:new_request{ chatbotId, sessionId, status, mode, ... }Een nieuwe live chat heeft een medewerker nodig.
livechat:widget_sessions{ chatbotId, chatbotName, sessions }Huidige lijst met actieve widget-sessies.
livechat:notification{ chatbotId, sessionId, content, sender }Nieuw bericht terwijl de medewerker zich elders in het dashboard bevindt.

Automatische vertaling

De socket kan automatisch vertalen tussen de talen van de bezoeker en de medewerker:

  • Neem deel met translateEnabled: true en stel lang in op jouw taal.
  • Berichten van de andere partij komen direct vertaald binnen in jouw lang. Elke partij behoudt de originele tekst; de vertaalde versie wordt afgeleverd bij de andere kant.
  • Vertaling verloopt via Azure OpenAI binnen de EU, zodat een medewerker in elke taal met een bezoeker kan chatten zonder handmatig te vertalen.

Voorbeeld: Aangepaste livechatclient

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
  }));
}