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 IA via simple HTTP. Utilisez cette méthode pour créer une interface de chat personnalisée, une application mobile ou une automatisation backend. Chaque endpoint est servi depuis la même origine que le script de votre Widget (https://webchatagent.com).
Vous utilisez JavaScript ou TypeScript ? Le SDK JavaScript (
npm install webchatagent) intègre ces endpoints avec des fonctions typées, le streaming et le Chat en direct.
Déroulement d'une conversation
- Envoyez un POST avec le
messagede l'utilisateur et votrechatbotIdvers/api/chat. - Lisez la
replydans le corps JSON. Lisez l'en-tête de réponseX-Chat-Session-Id, il s'agit de votre ID de session. - 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 documentaire issu de vos sources (Retrieval-Augmented Generation, RAG) et état du Chat en direct. - 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'envoyez donc que le message le plus récent, jamais la transcription complète.
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 à l'aide de l'en-tête Origin/Referer de la requête. Une requête provenant d'un domaine non autorisé renvoie un code 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 avec le jeton d'authentification du wiki (la valeur est wiki_auth_<subdomain>). Sans celui-ci, les wikis protégés renvoient un code 403.
Envoyer un message
POST https://webchatagent.com/api/chat
En-têtes
| En-tête | Obligatoire | Description |
|---|---|---|
Content-Type | Oui | Doit être application/json. |
X-Chat-Session-Id | Non | ID de session (un UUID) pour la continuité de la conversation. À omettre lors de la première requête ; l'en-tête de réponse en renvoie un nouveau. Vous pouvez également générer un UUID aléatoire vous-même. Toute valeur qui n'est pas un UUID est remplacée par une nouvelle session. |
Accept | Non | text/event-stream pour recevoir la réponse sous forme de flux (voir Streaming). |
Accept-Language | Non | Langue préférée pour la réponse, par exemple de. |
Corps de la Requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
message | string | Oui | Le message de l'utilisateur. 700 caractères maximum. Ne peut pas être vide. |
chatbotId | string (UUID) | Oui | L'identifiant de votre Chatbot, présent dans les paramètres du Chatbot. |
pageUrl | string | Non | L'URL complète de la page sur laquelle se trouve le Visiteur (window.location.href). Utilisée pour la recherche contextuelle par page ; validée par rapport à vos domaines autorisés. |
contextData | object | Non | Contexte plat sous forme de paires clé-valeur sur la session du Visiteur (maximum 20 clés, clés de 64 caractères, valeurs string/number/boolean de 500 caractères). Injecté dans le prompt de l'IA pour cette requête uniquement, jamais stocké comme un enregistrement distinct ; l'IA traite les valeurs comme des données et non comme des instructions, et peut les utiliser dans les arguments d'outils et de connecteurs API. Voir Données de contexte de session. |
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.
| Champ | Type | Description |
|---|---|---|
reply | string | La réponse au format Markdown. Elle peut se terminer par un commentaire HTML masqué <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> contenant des suggestions de questions de suivi : affichez label sur un bouton, envoyez text lors d'un clic et supprimez le commentaire avant le rendu. |
sources | array | Sources sur lesquelles la réponse s'est appuyée (voir ci-dessous). Vide si aucune n'a été utilisée. |
mode | string | Mode de conversation : bot (l'IA répond) ou human (un agent humain a pris le relais). Présent lorsque pertinent. |
status | string | Statut du Chat en direct : waiting, open ou closed. Présent uniquement lorsque le Chat en direct est actif pour la session. |
aiGenerated | boolean | true lorsque l'IA a rédigé la réponse. Absent lorsqu'un agent humain gère la conversation. |
conversationTooLong | boolean | La conversation a atteint sa limite de longueur. Démarrez une nouvelle session. |
Lorsqu'un agent humain a pris le relais (mode: "human", status: "open"), reply peut être vide, car l'agent répond séparément. Tant qu'une prise en charge 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 :
| Champ | Type | Description |
|---|---|---|
type | string | web (une page de site web), product (données de produit structurées) ou fileSource (un document provenant d'un stockage de fichiers connecté). |
source | string | Pour web : l'URL de la page. Pour product : l'identifiant du produit. Pour fileSource : l'ID du document. |
data | object | Uniquement pour product. Contient id, dataType, format, data et sourceUrl. |
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
Envoyez Accept: text/event-stream pour recevoir la réponse au fil de sa rédaction. Si le Chatbot a activé le streaming, la réponse est un flux d'événements Server-Sent Events, chacun constitué d'une seule ligne data: avec un objet JSON, séparés par une ligne vide :
data: {"type":"token","data":"Our business hours "}
data: {"type":"token","data":"are Monday to Friday."}
data: {"type":"done","reply":"Our business hours are Monday to Friday.","sources":[],"conversationTooLong":false,"aiGenerated":true}
type | Champs | Signification |
|---|---|---|
token | data | Morceau suivant de la réponse. Ajoutez-le à la suite. Le texte peut contenir du Markdown incomplet ainsi que le début du commentaire de suggestions. |
tool_call | name | Le bot utilise un outil, par exemple une recherche de produit. |
error | data | Un problème est survenu. En général, un événement done suit ; si le flux se termine sans done, traitez data comme l'erreur. |
done | mêmes champs que la réponse JSON | La réponse finale. Remplacez le texte reçu en continu par reply. |
Le serveur répond en JSON standard au lieu d'un flux lorsque le streaming est désactivée pour le Chatbot, lorsqu'un agent humain gère la conversation et en cas d'erreur. Vérifiez le Content-Type de la réponse. Fermer la connexion interrompt la génération.
Historique de chat
Récupérez les messages stockés pour une session (par exemple pour restaurer une conversation après le rechargement d'une page). L'historique datant de plus de 30 jours est supprimé pour le RGPD ; une session expirée renvoie un code 410.
GET https://webchatagent.com/api/chat/history
Paramètres de requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
chatbotId | string (UUID) | Oui | L'identifiant de votre Chatbot. |
sessionId | string (UUID) | Oui | La session dont vous souhaitez obtenir l'historique. |
Réponse
messages est ordonné du plus ancien au plus récent. sender vaut 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 de session
Obtenez le nombre de messages et la dernière activité des sessions connues de ce navigateur. Pour éviter de divulguer les conversations d'autres visiteurs, vous devez transmettre les identifiants de session que vous possédez 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
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
chatbotId | string (UUID) | Oui | L'identifiant de votre Chatbot. |
sessionIds | string | Oui | UUIDs de session séparés par des virgules (5 au maximum ; les identifiants supplémentaires sont ignorés). |
Réponse
{
"sessions": [
{
"sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"messageCount": 12,
"lastActivity": "2025-01-15T10:35:00Z"
}
]
}
Reset Session History
Effacez le contexte de conversation en mémoire d'une session afin que le message suivant démarre l'IA à zéro (aucun échange préalable). Cela ne supprime pas les messages enregistrés, les conversation_messages constituent des données métier et restent dans la base de données (ainsi que dans /api/chat/history).
DELETE https://webchatagent.com/api/chat/session
Headers
| Header | Required | Description |
|---|---|---|
X-Chat-Session-Id | Oui | La session dont l'historique en mémoire doit être effacé. |
Response
{ "success": true, "message": "Chat session cleared." }
Error Handling
La plupart des erreurs de /api/chat renvoient la même structure qu'une réponse normale : un message HTML convivial dans reply et un tableau sources vide. Le code de statut HTTP indique le type réel de l'erreur.
| Status | Meaning |
|---|---|
400 | Corps invalide, champ manquant, message vide ou message de plus de 700 caractères. |
403 | Domaine non autorisé, échec de l'authentification wiki ou restriction liée au forfait. |
404 | Chatbot introuvable. |
429 | Limite de débit atteinte, ou quota mensuel de messages dépassé. |
502 | Le fournisseur d'IA (LLM) a renvoyé une erreur. |
Error Response Body
{
"reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
"sources": []
}
Les requêtes invalides (400), la limite de débit (429) et les adresses IP bloquées (403) renvoient un corps différent : { "error": true, "statusCode": 429, "message": "..." }. Vérifiez d'abord le code de statut HTTP, puis affichez reply ou message à l'utilisateur.
Rate Limiting
| Scope | Limit |
|---|---|
| Par session | 10 requêtes par minute |
| Par adresse IP | 15 requêtes par minute |
| Par session et par adresse IP | au moins 1 seconde entre deux requêtes |
Le dépassement de l'une de ces limites renvoie une erreur 429. De plus, l'atteinte du quota mensuel de messages du forfait renvoie également une erreur 429 (avec un message « temporairement indisponible »).
Code Examples
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);
Conversations Export API
Exportez les conversations de votre chatbot au format CSV ou JSON via HTTP, filtrées par période. Utilisez cette API 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.
À la différence des points de terminaison de chat ci-dessus, cette API 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.
Authentication
POST https://webchatagent.com/api/auth/login
Envoyez l'e-mail et le mot de passe de votre tableau de bord sous forme de JSON. La réponse définit un cookie de session, incluez-le dans chaque requête suivante. Il n'y a pas de clé API distincte.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Oui | Votre e-mail de connexion au tableau de bord. |
password | string | Oui | Votre mot de passe du tableau de bord. |
Conditions requises :
- Disponible sur tous les forfaits.
- Les membres de l'équipe doivent disposer de la permission Conversations.
Export Conversations
GET https://webchatagent.com/api/conversations/export
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | Non | Limite l'exportation à un seul chatbot. Omettez ce paramètre pour exporter tous les chatbots auxquels vous avez accès. |
from | string (YYYY-MM-DD) | Non | Début de la période, inclus (limite du jour UTC). |
to | string (YYYY-MM-DD) | Non | Fin de la période, inclus (limite du jour UTC). |
q | string | Non | Filtre de recherche. Recherche dans l'ID de session, l'IP cliente ou le contenu du message. |
format | string | Non | csv (par défaut) ou json. |
Une conversation est considérée « dans la période » lorsqu'elle contient au moins un message dans cet intervalle. Les conversations correspondantes sont exportées en totalité, y compris les messages hors de la période, de sorte qu'une transcription à cheval sur deux mois n'est 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, pour une ouverture propre dans Excel.
Format JSON : un objet par conversation contenant 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 plafonné à 50 000 messages. Les requêtes plus volumineuses renvoient une erreur 413, réduisez la période ou sélectionnez un seul chatbot. Les adresses IP clientes sont anonymisées dans les deux formats.
Tool Data Endpoints
Les autres outils du tableau de bord sont accessibles 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 de jour UTC, les deux incluses). Ils renvoient uniquement du JSON, tous acceptent également l'absence de paramètres de date pour tout renvoyer.
| Endpoint | Returns | Team permission |
|---|---|---|
GET /api/questions | { success, questions: [...] } | Questions |
GET /api/feedback | { success, data: [...], count } | Feedback |
GET /api/leads | { success, leads: [...] } | Prospects |
GET /api/bookings | [...] (tableau brut), accepte aussi chatbotId | Bookings |
Sur le forfait gratuit, ces points de terminaison masquent les champs de contenu (***) au lieu de renvoyer une erreur 403.
# All leads collected in June
curl -b cookies.txt \
"https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"
Example: Monthly Export with 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"
Error codes
| Status | Meaning |
|---|---|
401 | Non connecté ou session expirée. Connectez-vous à nouveau. |
403 | Forfait gratuit, permission Conversations manquante ou aucun accès au chatbot. |
404 | Le chatbotId indiqué n'existe pas dans votre compte. |
413 | Plus de 50 000 messages trouvés. Réduisez la période ou choisissez un seul chatbot. |
