API WebSocket Chatbot (Chat en direct)

API WebSocket

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 des sessions. Le même socket alimente les widgets pour les visiteurs et le Tableau de bord de l'agent, ce qui vous permet de créer 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 du trafic est en JSON. Vous envoyez des événements client:*, le Serveur renvoie des événements livechat:*. Chaque message comprend un champ type.

Rôles de Connexion

Lorsque vous rejoignez la session, vous déclarez un Rôle avec le champ as :

Le Rôle détermine ce que vous recevez : les clients admin obtiennent l'historique complet des messages et les événements réservés aux administrateurs, tandis que les clients user ne reçoivent que les nouveaux événements en direct (les visiteurs chargent leur propre historique via l'endpoint REST d'historique, et non via le socket).

Déroulement rapide

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 jonction. Les administrateurs reçoivent ensuite l'historique des messages ainsi qu'un instantané du livechat:status Actuel.
3. Envoyez client:message pour publier un message, et recevez livechat:message pour chaque Nouveau message.
4. Envoyez client:typing et recevez livechat:typing pour les indicateurs de saisie.
5. Terminez avec client:end, ou recevez livechat:ended lorsque l'autre partie ferme la session.

Événements client (envoyés par vous)

client:join

Le premier événement après la Connexion. Rejoint la salle de session (et, pour les administrateurs, la salle du Chatbot).

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

client:message

Publie un message dans la session. Le Serveur le persiste, le traduit si l'option est activée 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"
}

Le premier message admin dans une session waiting l'ouvre (Statut → open) et insère automatiquement une notification Système "agent joined".

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 session (Page actuelle) pour que les agents voient 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 la main sur une session IA (la passe à open / human). Réservé aux administrateurs.

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

client:end

Termine 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ésenregistrer 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"
}

Événements serveur (reçus par vous)

livechat:status

Deux formats : un accusé de réception simple { "type": "livechat:status", "ok": true } et un instantané du 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"
}

livechat:message

Un Nouveau message (ou issu 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
}

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

reason prend l'une des valeurs suivantes : admin_closed, already_closed ou timeout.

Événements réservés aux administrateurs

Traduction automatique

Le socket peut traduire automatiquement entre les Langues du Visiteur et de l'agent :

• Rejoignez 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, la Copie traduite est distribuée à l'autre partie.
• La Traduction s'appuie sur Gemini, ce qui permet à un agent d'échanger avec un Visiteur dans n'importe quelle Langue sans traduire manuellement.

Exemple : Client de Chat en direct personnalisé

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