API WebSocket du Chatbot (Chat en direct)
WebSocket API
Utilisez l'API WebSocket pour le Chat en direct en temps réel : distribution instantanée des messages, indicateurs de saisie, présence, Traduction automatique et cycle de vie de session. Le même socket alimente les widgets pour les visiteurs et le Tableau de bord des agents, vous permettant ainsi de concevoir une console d'agent personnalisée ou de piloter le Chat en direct depuis votre propre backend.
Endpoint
wss://webchatagent.com/api/livechat
L'ensemble des échanges s'effectue en JSON. Vous envoyez des événements client:* ; le Serveur renvoie des événements livechat:*. Chaque message comprend un champ type.
Vous développez un chat pour visiteurs en JavaScript ? Le SDK JavaScript prend en charge pour vous la connexion, la reconnexion, la saisie et la fin d'un Chat en direct :
chat.liveChat().
Connection Roles
Lorsque vous vous connectez, vous déclarez un Rôle avec le champ as :
| Rôle | Description |
|---|---|
user | Un Visiteur du Site web dans un chat. |
admin | Un agent humain gérant les sessions de Chat en direct. |
widget | Le Widget de chat intégré en mode surveillance (avant une reprise en main). |
Le Rôle détermine ce que vous recevez : les clients admin reçoivent l'historique complet des messages ainsi que les événements réservés aux administrateurs ; les clients user reçoivent uniquement les nouveaux événements en direct (les visiteurs chargent leur propre historique via le endpoint d'historique REST, pas via le socket).
Quick flow
- Ouvrez le socket et envoyez
client:joinavec votrechatbotId,sessionId, etas. - Le Serveur répond avec
{ "type": "livechat:status", "ok": true }pour Confirmer la connexion. Les administrateurs reçoivent ensuite l'historique des messages ainsi qu'un instantané dulivechat:statusActuel. - Envoyez
client:messagepour publier ; recevezlivechat:messagepour chaque Nouveau message. - Envoyez
client:typing/ recevezlivechat:typingpour les indicateurs de saisie. - Terminez avec
client:end, ou recevezlivechat:endedlorsque l'autre partie Ferme la session.
Client Events (you send)
client:join
Le premier événement après la Connexion. Permet de rejoindre le salon de session (et, pour les administrateurs, le salon du Chatbot).
{
"type": "client:join",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"as": "user",
"lang": "en",
"translateEnabled": true,
"retranslateBacklog": false
}
| Field | Type | Obligatoire | Description |
|---|---|---|---|
chatbotId | string | Oui | L'UUID de votre Chatbot. Pour un administrateur surveillant tous les bots, la Valeur spéciale "all" permet de se connecter sans salon spécifique. |
sessionId | string | Oui | L'ID de session de chat. |
as | string | Oui | user, admin, ou widget. |
lang | string | Non | Code de Langue préférée (par ex. en, de, fr). Définit la cible de Traduction. |
translateEnabled | boolean | Non | Active la Traduction automatique pour cette session (par défaut : Activé). |
retranslateBacklog | boolean | Non | Retraduit les messages existants de l'historique vers la lang lors de la connexion (admin). |
client:message
Publie un message dans la session. Le Serveur le conserve, le traduit s'il est Activé, et diffuse livechat:message.
{
"type": "client:message",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"sender": "user",
"content": "I need help with my order",
"lang": "en"
}
| Field | Type | Obligatoire | Description |
|---|---|---|---|
chatbotId | string | Oui | L'UUID de votre Chatbot. |
sessionId | string | Oui | L'ID de session de chat. |
sender | string | Oui | user ou admin. |
content | string | Oui | Le texte du message. Un content Vide ou manquant est ignoré. |
lang | string | Non | Indication de la Langue du message pour la Traduction. |
Le premier message admin dans une session en attente l'ouvre (Statut → open) et insère automatiquement une notification Système indiquant qu'un agent a rejoint la session.
client:typing
Diffuse un indicateur de saisie à tous les participants de la session.
{
"type": "client:typing",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"sender": "user",
"isTyping": true
}
client:meta
Met à jour les métadonnées de la session (Page actuelle) pour que les agents puissent voir où se trouve le Visiteur.
{
"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'administrateur prend proactivement le relais d'une session IA (définit le Statut sur open / human). Admin uniquement.
{
"type": "client:agent_takeover",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID"
}
client:end
Met Fin à la session.
{
"type": "client:end",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"reason": "resolved"
}
client:widget_open / client:widget_close
Envoyé par le Widget pour enregistrer ou désinscrire une session active pour la Visibilité de l'administrateur (c'est ce qui alimente 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 (you receive)
livechat:status
Deux formats : un simple accusé de réception { "type": "livechat:status", "ok": true }, et un instantané de Statut de session (ci-dessous).
{
"type": "livechat:status",
"chatbotId": "YOUR_CHATBOT_ID",
"sessionId": "SESSION_ID",
"status": "open",
"mode": "human",
"userName": "John",
"userEmail": "john@example.com",
"userLanguage": "en"
}
| Field | Type | Description |
|---|---|---|
status | string | waiting (aucun agent pour le moment), open (agent Connecté), ou closed. |
mode | string | bot ou human. |
userName | string | null | Nom du Visiteur, si collecté via les Prospects. |
userEmail | string | null | E-mail du Visiteur, s'il a été collecté. |
userLanguage | string | null | Langue détectée du Visiteur. |
livechat:message
Un message Nouveau (ou de l'historique).
{
"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
}
| Field | Type | Description |
|---|---|---|
id | number | ID du message (correspond à l'id de l'historique REST). |
sender | string | user, admin, ou system. |
content | string | Texte du message. Pour les clients admin avec Traduction activée, ce texte est déjà traduit dans la Langue de l'administrateur. |
country | string | null | Code pays de l'expéditeur, s'il est détecté. |
createdAt | string | Horodatage ISO 8601. |
file | object | null | Métadonnées du Fichier joint (uploadId, name, mimeType, size, url, isImage) lorsque le message est un fichier importé. |
audience | string | null | "admin" sur la Copie du message destinée à l'administrateur. La Copie destinée à l'utilisateur l'omet. |
historical | boolean | true pour les messages de l'historique rejoués lors de la connexion. |
Messages système : lorsque
sendervautsystem,contentest un jeton que votre client doit localiser et non afficher tel quel :__agent_joined__,__livechat_ended__, ou__livechat_timeout__.
livechat:typing
Indicateur de saisie d'un autre participant : { type, chatbotId, sessionId, sender, isTyping }.
livechat:presence
Statut En ligne/Hors ligne du Visiteur dans une session : { type, chatbotId, sessionId, online } (booléen).
livechat:meta
Métadonnées de session mises à jour (Page actuelle, Titre, référent), réservé aux administrateurs.
livechat:ended
La session a été fermée.
{
"type": "livechat:ended",
"sessionId": "SESSION_ID",
"reason": "admin_closed"
}
Le reason peut être user_closed (le Visiteur y a mis Fin via POST /api/livechats/end), admin_closed (Fermé via le socket) ou already_closed (vous avez rejoint une session qui était déjà terminée).
Un chat en attente qu'aucun agent ne prend en charge est fermé par le Serveur avec un événement livechat:status (status: "closed") et sans livechat:ended. Considérez ces deux cas comme la Fin du Chat en direct.
Admin-only events
| Event | Payload | Purpose |
|---|---|---|
livechat:active_count | { chatbotId, count } | Sessions actives (en attente + ouvertes). |
livechat:waiting_count | { chatbotId, count } | Sessions en attente (badge pour les discussions Sans réponse). |
livechat:new_request | { chatbotId, sessionId, status, mode, ... } | Un Nouveau Chat en direct nécessite un agent. |
livechat:widget_sessions | { chatbotId, chatbotName, sessions } | Liste actuelle des sessions de Widget actives. |
livechat:notification | { chatbotId, sessionId, content, sender } | Nouveau message alors que l'agent se trouve ailleurs dans le Tableau de bord. |
Auto-Translation
Le socket peut assurer automatiquement la Traduction entre les Langues du Visiteur et de l'agent :
- Rejoignez la session avec
translateEnabled: trueet définissezlangsur Votre langue. - Les messages de l'autre partie arrivent déjà traduits dans votre
lang. Chaque partie conserve son texte d'origine, et la Copie traduite est transmise à l'autre participant. - La Traduction s'exécute via Azure OpenAI dans l'UE, ce qui permet à un agent d'échanger avec un Visiteur dans n'importe quelle Langue sans traduire manuellement.
Example: Custom Live Chat Client
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
}));
}
