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:
| Rol | Beschrijving |
|---|---|
user | Een websitebezoeker in een chat. |
admin | Een menselijke medewerker die livechatsessies beheert. |
widget | De 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
- Open de socket en verstuur
client:joinmet jechatbotId,sessionIdenas. - De server antwoordt met
{ "type": "livechat:status", "ok": true }om de deelname te bevestigen. Admins ontvangen vervolgens de eerdere berichten en een actuelelivechat:status-momentopname. - Verstuur
client:messageom een bericht te plaatsen; ontvanglivechat:messagevoor elk nieuw bericht. - Verstuur
client:typing/ ontvanglivechat:typingvoor type-indicatoren. - Sluit af met
client:end, of ontvanglivechat:endedwanneer 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
}
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
chatbotId | string | Ja | De UUID van je chatbot. Voor een beheerder die alle bots monitort, zorgt de speciale waarde "all" voor deelname zonder specifieke ruimte. |
sessionId | string | Ja | De sessie-ID van de chat. |
as | string | Ja | user, admin of widget. |
lang | string | Nee | Voorkeurstaalcode (bijv. en, de, fr). Bepaalt het vertaaldoel. |
translateEnabled | boolean | Nee | Schakel automatische vertaling in voor deze sessie (standaard: ingeschakeld). |
retranslateBacklog | boolean | Nee | Vertaal 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"
}
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
chatbotId | string | Ja | De UUID van je chatbot. |
sessionId | string | Ja | De sessie-ID van de chat. |
sender | string | Ja | user of admin. |
content | string | Ja | De tekst van het bericht. Een lege of ontbrekende content wordt genegeerd. |
lang | string | Nee | Taalsuggestie 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"
}
| Veld | Type | Beschrijving |
|---|---|---|
status | string | waiting (nog geen medewerker), open (medewerker verbonden) of closed. |
mode | string | bot of human. |
userName | string | null | Naam van de bezoeker, indien verzameld via Leads. |
userEmail | string | null | E-mailadres van de bezoeker, indien verzameld. |
userLanguage | string | null | Gedetecteerde 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
}
| Veld | Type | Beschrijving |
|---|---|---|
id | number | Bericht-ID (komt overeen met het REST-geschiedenis-id). |
sender | string | user, admin of system. |
content | string | Berichttekst. Voor admin-clients waarbij vertaling is ingeschakeld, is dit al vertaald naar de taal van de beheerder. |
country | string | null | Landcode van de afzender, indien gedetecteerd. |
createdAt | string | ISO 8601-tijdstempel. |
file | object | null | Metadata van het bijgevoegde bestand (uploadId, name, mimeType, size, url, isImage) wanneer het bericht een upload is. |
audience | string | null | "admin" op de versie van een bericht die voor de beheerder bestemd is. De versie voor de gebruiker laat dit veld weg. |
historical | boolean | true voor eerdere berichten die opnieuw worden afgespeeld bij deelname. |
Systeemberichten: wanneer
sendergelijk is aansystem, iscontenteen 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
| Event | Payload | Doel |
|---|---|---|
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: trueen stellangin 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
}));
}
