Référence de l'API REST du Chatbot

REST API

Envoyez un message à votre chatbot et recevez une réponse générée par l'IA via une simple requête HTTP. Utilisez cette fonctionnalité pour concevoir une interface de chat personnalisée, une application mobile ou une automatisation back-end. Chaque point de terminaison est servi depuis la même origine que le script de votre widget (https://webchatagent.com).

Déroulement d'une conversation

1. Envoyez une requête POST avec le message de l'utilisateur et votre chatbotId vers /api/chat.
2. Lisez la valeur reply dans le corps JSON. Lisez l'en-tête de réponse X-Chat-Session-Id, il s'agit de votre ID de session.
3. Pour le message suivant, envoyez ce même ID de session dans l'en-tête de requête X-Chat-Session-Id. Le serveur dispose désormais du contexte de conversation : historique des messages, contexte de connaissances basé sur les sources (Retrieval-Augmented Generation, RAG) et état du Live Chat.
4. Répétez l'opération. Omettez l'en-tête dès que vous souhaitez démarrer une nouvelle conversation.

Le serveur suit l'historique par session, vous n'avez donc qu'à envoyer le dernier message, jamais l'intégralité de la transcription.

Authentification

L'API utilise une authentification basée sur le domaine : il n'y a pas de clé API. Chaque requête est vérifiée par rapport aux Domaines autorisés configurés pour le chatbot en utilisant les en-têtes Origin/Referer de la requête. Une requête provenant d'un domaine non autorisé reçoit une erreur 403.

Pour les chatbots de type Wiki d'équipe IA avec un accès protégé, envoyez également l'en-tête X-Wiki-Auth contenant le jeton d'authentification du wiki (la valeur est wiki_auth_<subdomain>). Sans cela, les wikis protégés renvoient un code 403.

Envoyer un message

POST https://webchatagent.com/api/chat

Headers

Corps de la Requête

Exemple de requête

{
  "message": "What are your business hours?",
  "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Réponse

L'ID de session est renvoyé dans l'en-tête de réponse X-Chat-Session-Id, et non dans le corps.

Lorsqu'un agent humain a pris le relais (mode: "human", status: "open"), le champ reply peut être vide, l'agent répondant séparément. Pendant qu'une prise de relais est waiting, la réponse est une courte notification comme "Un membre de l'équipe va vous répondre sous peu."

Tableau des sources

Chaque objet source :

Exemple de réponse

{
  "reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
  "sources": [
    {
      "type": "web",
      "source": "https://example.com/contact"
    }
  ],
  "mode": "bot"
}

Streaming : Si un chatbot a activé le streaming, le widget reçoit la réponse jeton par jeton via Server-Sent Events. La réponse JSON simple documentée ici est celle que vous obtenez pour une requête standard et représente le modèle adapté pour les intégrations de serveur à serveur et la plupart des interfaces personnalisées.

Historique des discussions

Récupérez les messages stockés pour une session (par exemple pour restaurer une conversation après un rechargement de page). L'historique datant de plus de 30 jours est supprimé conformément au RGPD ; une session expirée renvoie une erreur 410.

GET https://webchatagent.com/api/chat/history

Paramètres de requête

Réponse

messages est ordonné du plus ancien au plus récent. sender prend la valeur bot ou user (il s'agit d'une valeur d'affichage, pas du rôle brut). role correspond au rôle sous-jacent user / assistant / system, et isAgent vaut true lorsqu'un message assistant provient d'un agent humain plutôt que de l'IA.

{
  "messages": [
    {
      "id": 123,
      "sender": "user",
      "role": "user",
      "isAgent": false,
      "text": "What are your hours?",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": 124,
      "sender": "bot",
      "role": "assistant",
      "isAgent": false,
      "text": "Our hours are Monday to Friday, 9 AM to 5 PM.",
      "sources": [{ "type": "web", "source": "https://example.com/contact" }],
      "createdAt": "2025-01-15T10:30:01Z"
    }
  ]
}

sources est présent uniquement lorsqu'un message en contient.

Informations sur la session

Obtenez le nombre de messages et la dernière activité pour les sessions connues de ce navigateur. Pour éviter de divulguer les conversations d'autres visiteurs, vous devez transmettre les ID de session que vous détenez déjà (par exemple depuis le stockage local). Les sessions sans activité au cours des 30 derniers jours ne sont pas renvoyées.

GET https://webchatagent.com/api/chat/sessions

Paramètres de requête

Réponse

{
  "sessions": [
    {
      "sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "messageCount": 12,
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Réinitialiser l'historique de session

Effacez le contexte de conversation en mémoire pour une session afin que le message suivant redémarre l'IA à zéro (aucun échange antérieur). Cela ne supprime pas les messages stockés, les conversation_messages constituent des données d'activité et restent dans la base de données (ainsi que dans /api/chat/history).

DELETE https://webchatagent.com/api/chat/session

Headers

Réponse

{ "success": true, "message": "Chat session cleared." }

Gestion des erreurs

Les erreurs renvoyées par /api/chat ont la même structure qu'une réponse normale : un message HTML compréhensible dans reply et un tableau sources vide. Le code de statut HTTP indique le type réel de l'erreur.

Corps de réponse d'erreur

{
  "reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
  "sources": []
}

Le corps est toujours { reply, sources }, il n'y a pas d'enveloppe d'erreur distincte. Appliquez votre logique selon le code de statut HTTP et affichez reply à l'utilisateur si vous souhaitez un message prêt à l'emploi.

Limite de débit

Tout dépassement de l'une de ces limites renvoie un code 429. De plus, atteindre le quota mensuel de messages du forfait renvoie également un code 429 (avec un message "temporairement indisponible").

Exemples de code

cURL

# Send a message (capture the session id from the response header)
curl -i -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you offer?",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

# Continue the conversation (reuse the session id from above)
curl -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Chat-Session-Id: SESSION_ID_FROM_FIRST_RESPONSE" \
  -d '{
    "message": "Tell me more about the premium plan",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

JavaScript / TypeScript

async function chat(message, chatbotId, sessionId = null) {
  const headers = { 'Content-Type': 'application/json' };
  if (sessionId) headers['X-Chat-Session-Id'] = sessionId;

  const response = await fetch('https://webchatagent.com/api/chat', {
    method: 'POST',
    headers,
    body: JSON.stringify({ message, chatbotId })
  });

  const data = await response.json();
  // The session id lives in the response header — keep it for follow-up messages.
  const newSessionId = response.headers.get('X-Chat-Session-Id');

  return { ...data, sessionId: newSessionId || sessionId };
}

// First message
const result = await chat('Hello!', 'YOUR_CHATBOT_ID');
console.log(result.reply);

// Follow-up in the same conversation
const followUp = await chat('Tell me more', 'YOUR_CHATBOT_ID', result.sessionId);
console.log(followUp.reply);

Python

import requests

CHATBOT_ID = "YOUR_CHATBOT_ID"
URL = "https://webchatagent.com/api/chat"

# First message
response = requests.post(URL, json={
    "message": "What are your business hours?",
    "chatbotId": CHATBOT_ID,
})

data = response.json()
session_id = response.headers.get("X-Chat-Session-Id")
print("Reply:", data["reply"])
print("Sources:", data["sources"])

# Continue the conversation
response = requests.post(
    URL,
    json={"message": "And on weekends?", "chatbotId": CHATBOT_ID},
    headers={"X-Chat-Session-Id": session_id},
)
print("Reply:", response.json()["reply"])

PHP

<?php
$chatbotId = 'YOUR_CHATBOT_ID';
$url = 'https://webchatagent.com/api/chat';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'message'   => 'What are your business hours?',
        'chatbotId' => $chatbotId,
    ]),
    CURLOPT_HEADER => true, // include headers so we can read the session id
]);

$response   = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers    = substr($response, 0, $headerSize);
$body       = json_decode(substr($response, $headerSize), true);

echo 'Reply: ' . $body['reply'] . PHP_EOL;

// Pull the session id from the response headers for follow-up messages
preg_match('/X-Chat-Session-Id:\s*(.+)/i', $headers, $matches);
$sessionId = trim($matches[1] ?? '');

curl_close($ch);

API d'exportation des conversations

Exportez les conversations de votre chatbot au format CSV ou JSON via HTTP, filtrées par période. Utilisez cette fonctionnalité pour automatiser vos rapports périodiques : récupérez toutes les conversations d'un chatbot pour un mois donné, intégrez-les dans vos propres outils d'analyse ou archivez-les.

Contrairement aux points de terminaison de chat ci-dessus, cette fonctionnalité fait partie de l'API du tableau de bord. Elle n'est pas authentifiée par domaine. Vous vous connectez avec les identifiants de votre compte et réutilisez le cookie de session pour la requête d'exportation.

Authentification

POST https://webchatagent.com/api/auth/login

Envoyez l'e-mail et le mot de passe de votre tableau de bord au format JSON. La réponse définit un cookie de session ; incluez-le dans chaque requête ultérieure. Il n'existe pas de clé API distincte.

Prérequis :

• Un forfait payant. Le point de terminaison d'exportation renvoie 403 avec le forfait gratuit.
• Les membres de l'équipe doivent disposer de la permission Conversations.

Exporter les conversations

GET https://webchatagent.com/api/conversations/export

Paramètres de requête

Une conversation est considérée comme "dans la période" lorsqu'elle contient au moins un message dans l'intervalle spécifié. Les conversations correspondantes sont exportées intégralement, y compris les messages situés en dehors de la période, afin qu'une transcription à cheval sur deux mois ne soit jamais tronquée.

Format CSV : une ligne par message, avec les métadonnées de la conversation (nom du chatbot, ID de session, nombre de messages, dernière activité) répétées sur chaque ligne. Renvoyé sous forme de fichier joint avec un BOM UTF-8, facilitant son ouverture dans Excel.

Format JSON : un objet par conversation avec ses messages imbriqués :

{
  "range": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" },
  "sessionsCount": 42,
  "messagesCount": 314,
  "sessions": [
    {
      "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatbotName": "Support Bot",
      "sessionId": "sess_abc123",
      "messagesCount": 6,
      "lastActivity": "2026-06-12T09:41:22.000Z",
      "lastLanguage": "de",
      "lastIp": "203.0.113.* (anon)",
      "messages": [
        {
          "role": "user",
          "content": "What are your business hours?",
          "sources": null,
          "browserLanguage": "de",
          "clientIp": "203.0.113.* (anon)",
          "referer": "https://example.com/contact",
          "createdAt": "2026-06-12T09:40:01.000Z"
        }
      ]
    }
  ]
}

Limites : un export est limité à 50 000 messages. Les requêtes plus volumineuses renvoient 413 ; réduisez la période ou sélectionnez un seul chatbot. Les adresses IP des clients sont anonymisées dans les deux formats.

Points de terminaison pour les données d'outils

Les autres outils du tableau de bord sont accessibles en lecture avec la même authentification par cookie de session et prennent en charge le même filtrage par date from / to (sur la date de création de chaque enregistrement, limites du jour UTC, les deux incluses). Ils renvoient uniquement du JSON ; ils acceptent également l'absence de paramètres de date pour tout renvoyer.

Avec le forfait gratuit, ces points de terminaison masquent les champs de contenu (***) au lieu de renvoyer 403.

# All leads collected in June
curl -b cookies.txt \
  "https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"

Exemple : Exportation mensuelle avec cURL

# 1. Log in once and store the session cookie
curl -c cookies.txt -X POST https://webchatagent.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'

# 2. Download all June conversations of one chatbot as CSV
curl -b cookies.txt -o conversations_june.csv \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30"

# Or as JSON for automated processing
curl -b cookies.txt \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30&format=json"

Codes d'erreur