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ôleDescription
userUn Visiteur du Site web dans un chat.
adminUn agent humain gérant les sessions de Chat en direct.
widgetLe 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

  1. Ouvrez le socket et envoyez client:join avec votre chatbotId, sessionId, et as.
  2. 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é du livechat:status Actuel.
  3. Envoyez client:message pour publier ; recevez livechat:message pour chaque Nouveau message.
  4. Envoyez client:typing / recevez livechat:typing pour les indicateurs de saisie.
  5. Terminez avec client:end, ou recevez livechat:ended lorsque 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
}
FieldTypeObligatoireDescription
chatbotIdstringOuiL'UUID de votre Chatbot. Pour un administrateur surveillant tous les bots, la Valeur spéciale "all" permet de se connecter sans salon spécifique.
sessionIdstringOuiL'ID de session de chat.
asstringOuiuser, admin, ou widget.
langstringNonCode de Langue préférée (par ex. en, de, fr). Définit la cible de Traduction.
translateEnabledbooleanNonActive la Traduction automatique pour cette session (par défaut : Activé).
retranslateBacklogbooleanNonRetraduit 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"
}
FieldTypeObligatoireDescription
chatbotIdstringOuiL'UUID de votre Chatbot.
sessionIdstringOuiL'ID de session de chat.
senderstringOuiuser ou admin.
contentstringOuiLe texte du message. Un content Vide ou manquant est ignoré.
langstringNonIndication 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"
}
FieldTypeDescription
statusstringwaiting (aucun agent pour le moment), open (agent Connecté), ou closed.
modestringbot ou human.
userNamestring | nullNom du Visiteur, si collecté via les Prospects.
userEmailstring | nullE-mail du Visiteur, s'il a été collecté.
userLanguagestring | nullLangue 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
}
FieldTypeDescription
idnumberID du message (correspond à l'id de l'historique REST).
senderstringuser, admin, ou system.
contentstringTexte du message. Pour les clients admin avec Traduction activée, ce texte est déjà traduit dans la Langue de l'administrateur.
countrystring | nullCode pays de l'expéditeur, s'il est détecté.
createdAtstringHorodatage ISO 8601.
fileobject | nullMétadonnées du Fichier joint (uploadId, name, mimeType, size, url, isImage) lorsque le message est un fichier importé.
audiencestring | null"admin" sur la Copie du message destinée à l'administrateur. La Copie destinée à l'utilisateur l'omet.
historicalbooleantrue pour les messages de l'historique rejoués lors de la connexion.

Messages système : lorsque sender vaut system, content est 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

EventPayloadPurpose
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: true et définissez lang sur 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
  }));
}