Chatbot REST API-referentie
REST API
Verstuur een bericht naar uw chatbot en ontvang een door AI gegenereerd antwoord via reguliere HTTP. Gebruik dit voor een eigen chat-UI, een mobiele app of een backend-automatisering. Elk eindpunt wordt gehost vanaf dezelfde origin als uw widget-script (https://webchatagent.com).
Gebruikt u JavaScript of TypeScript? De JavaScript SDK (
npm install webchatagent) bundelt deze eindpunten met getypeerde functies, streaming en live chat.
Hoe een gesprek verloopt
- POST het
messagevan de bezoeker en uwchatbotIdnaar/api/chat. - Lees de
replyuit de JSON-body. Lees deX-Chat-Session-Idresponse-header, dat is uw sessie-ID. - Stuur bij het volgende bericht dezelfde sessie-ID mee in de
X-Chat-Session-Idrequest-header. De server beschikt nu over gesprekscontext: berichtgeschiedenis, op bronnen gebaseerde kenniscontext (Retrieval-Augmented Generation, RAG) en de live-chatstatus. - Herhaal dit. Laat de header weg zodra u een nieuw gesprek wilt starten.
De server houdt de geschiedenis per sessie bij, waardoor u altijd alleen het meest recente bericht verstuurt, nooit het volledige transcript.
Authenticatie
De API maakt gebruik van op domein gebaseerde authenticatie: er is geen API-key. Elk verzoek wordt gecontroleerd aan de hand van de geconfigureerde Allowed Domains van de chatbot via de Origin/Referer van het verzoek. Een verzoek vanaf een niet-toegestaan domein krijgt een 403.
Voor AI Team Wiki chatbots met beveiligde toegang stuurt u ook de X-Wiki-Auth-header mee met het authenticatietoken van de wiki (de waarde is wiki_auth_<subdomain>). Zonder deze header retourneren beveiligde wiki's een 403.
Een bericht versturen
POST https://webchatagent.com/api/chat
Headers
| Header | Verplicht | Beschrijving |
|---|---|---|
Content-Type | Ja | Moet application/json zijn. |
X-Chat-Session-Id | Nee | Sessie-ID (een UUID) om het gesprek voort te zetten. Weglaten bij het eerste verzoek; de response-header retourneert een nieuwe ID. U kunt ook zelf een willekeurige UUID aanmaken. Alles wat geen UUID is, wordt vervangen door een nieuwe sessie. |
Accept | Nee | text/event-stream om het antwoord als stream te ontvangen (zie Streaming). |
Accept-Language | Nee | Voorkeurstaal voor het antwoord, bijvoorbeeld de. |
Request body
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
message | string | Ja | Het bericht van de bezoeker. Maximaal 700 tekens. Mag niet leeg zijn. |
chatbotId | string (UUID) | Ja | De ID van uw chatbot, te vinden in de chatbot-instellingen. |
pageUrl | string | Nee | De volledige pagina-URL waar de bezoeker zich bevindt (window.location.href). Wordt gebruikt voor contextbewuste zoekopdrachten; gevalideerd aan de hand van uw toegestane domeinen. |
contextData | object | Nee | Platte sleutel-waarde-context over de bezoekersessie (maximaal 20 sleutels, sleutels van 64 tekens, string-/number-/boolean-waarden van 500 tekens). Wordt uitsluitend voor dit verzoek in de AI-prompt geïnjecteerd en nooit als een afzonderlijk record opgeslagen; de AI behandelt waarden als data, niet als instructies, en kan deze gebruiken in argumenten voor tools en API-connectors. Zie Session Context Data. |
Voorbeeldverzoek
{
"message": "What are your business hours?",
"chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Respons
De sessie-ID wordt geretourneerd in de X-Chat-Session-Id response-header, niet in de body.
| Veld | Type | Beschrijving |
|---|---|---|
reply | string | Het antwoord als Markdown. Dit kan eindigen met een verborgen HTML-commentaar <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> met voorgestelde vervolgvragen: toon label op een knop, verstuur text wanneer erop wordt geklikt, en verwijder het commentaar vóór het renderen. |
sources | array | Bronnen waarop het antwoord is gebaseerd (zie hieronder). Leeg als er geen bronnen zijn gebruikt. |
mode | string | Gespreksmodus: bot (AI antwoordt) of human (een live medewerker heeft overgenomen). Aanwezig wanneer relevant. |
status | string | Live-chatstatus: waiting, open of closed. Alleen aanwezig wanneer Live chat actief is voor de sessie. |
aiGenerated | boolean | true wanneer de AI het antwoord heeft geschreven. Ontbreekt zolang een menselijke medewerker het gesprek afhandelt. |
conversationTooLong | boolean | Het gesprek heeft de maximale lengte bereikt. Start een nieuwe sessie. |
Wanneer een menselijke medewerker heeft overgenomen (mode: "human", status: "open"), kan reply leeg zijn, de medewerker antwoordt afzonderlijk. Zolang een overname waiting is, is het antwoord een korte melding zoals "A team member will join shortly."
Sources-array
Elk bronobject:
| Veld | Type | Beschrijving |
|---|---|---|
type | string | web (een websitepagina), product (gestructureerde productdata) of fileSource (een document uit gekoppelde bestandsopslag). |
source | string | Voor web: de pagina-URL. Voor product: de productidentificator. Voor fileSource: de document-ID. |
data | object | Alleen voor product. Bevat id, dataType, format, data en sourceUrl. |
Voorbeeldrespons
{
"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
Stuur Accept: text/event-stream mee om het antwoord te ontvangen terwijl het wordt gegenereerd. Als streaming is ingeschakeld voor de chatbot, is de respons een stream van Server-Sent Events, elk bestaande uit een enkele data:-regel met een JSON-object, gescheiden door een lege regel:
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 | Velden | Betekenis |
|---|---|---|
token | data | Volgende deel van het antwoord. Voeg dit toe. De tekst kan onvolledige Markdown en het begin van het suggestie-commentaar bevatten. |
tool_call | name | De bot gebruikt een tool, bijvoorbeeld een zoekopdracht naar producten. |
error | data | Een probleem. Meestal volgt een done; als de stream eindigt zonder done, behandel data dan als de fout. |
done | dezelfde velden als de JSON-respons | Het definitieve antwoord. Vervang de gestreamde tekst door reply. |
De server antwoordt met gewone JSON in plaats van een stream wanneer streaming is uitgeschakeld voor de chatbot, wanneer een menselijke medewerker het gesprek afhandelt en bij fouten. Controleer de Content-Type van de respons. Het sluiten van de verbinding stopt het genereren.
Chatgeschiedenis
Haal de opgeslagen berichten voor een sessie op (bijvoorbeeld om een gesprek te herstellen na het herladen van de pagina). Geschiedenis ouder dan 30 dagen wordt verwijderd conform de AVG; een verlopen sessie retourneert een 410.
GET https://webchatagent.com/api/chat/history
Queryparameters
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
chatbotId | string (UUID) | Ja | De ID van uw chatbot. |
sessionId | string (UUID) | Ja | De sessie waarvan u de geschiedenis wilt ophalen. |
Respons
messages is gesorteerd van oud naar nieuw. sender is bot of user (dit is een weergavewaarde, niet de ruwe rol). role is de onderliggende rol user, assistant of system, en isAgent is true wanneer een assistant-bericht afkomstig is van een menselijke medewerker in plaats van de AI.
{
"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 is alleen aanwezig wanneer een bericht bronnen bevat.
Sessie-informatie
Haal het aantal berichten en de laatste activiteit op voor sessies die bekend zijn bij deze browser. Om te voorkomen dat chats van andere bezoekers uitlekken, moet u de sessie-ID's doorgeven die u al bezit (bijvoorbeeld via lokale opslag). Sessies zonder activiteit in de laatste 30 dagen worden niet geretourneerd.
GET https://webchatagent.com/api/chat/sessions
Queryparameters
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
chatbotId | string (UUID) | Ja | De ID van uw chatbot. |
sessionIds | string | Ja | Door komma's gescheiden sessie-UUID's (maximaal 5; extra sessies worden genegeerd). |
Respons
{
"sessions": [
{
"sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"messageCount": 12,
"lastActivity": "2025-01-15T10:35:00Z"
}
]
}
Sessiegeschiedenis resetten
Wis de in-memory gesprekscontext van een sessie, zodat het volgende bericht de AI opnieuw start (zonder eerdere gespreksbeurten). Dit verwijdert geen opgeslagen berichten, want conversation_messages zijn bedrijfsgegevens en blijven in de database bewaard (en in /api/chat/history).
DELETE https://webchatagent.com/api/chat/session
Headers
| Header | Required | Description |
|---|---|---|
X-Chat-Session-Id | Ja | De sessie waarvan de in-memory geschiedenis moet worden gewist. |
Respons
{ "success": true, "message": "Chat session cleared." }
Foutafhandeling
De meeste fouten van /api/chat retourneren dezelfde structuur als een normaal antwoord: een gebruiksvriendelijk HTML-bericht in reply en een lege sources-array. De HTTP-statuscode geeft het daadwerkelijke fouttype aan.
| Status | Betekenis |
|---|---|
400 | Ongeldige body, ontbrekend veld, leeg bericht of bericht van meer dan 700 tekens. |
403 | Domein niet toegestaan, wiki-authenticatie mislukt of er geldt een pakketbeperking. |
404 | Chatbot niet gevonden. |
429 | Rate limit bereikt of het maandelijkse berichtentegoed is op. |
502 | De AI-provider (LLM) heeft een fout geretourneerd. |
Respons-body bij fouten
{
"reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
"sources": []
}
Ongeldige verzoeken (400), de rate limit (429) en geblokkeerde IP-adressen (403) retourneren in plaats daarvan een andere body: { "error": true, "statusCode": 429, "message": "..." }. Maak eerst een vertakking op basis van de HTTP-statuscode en toon vervolgens reply of message aan de gebruiker.
Rate limiting
| Bereik | Limiet |
|---|---|
| Per sessie | 10 verzoeken per minuut |
| Per IP-adres | 15 verzoeken per minuut |
| Per sessie en per IP-adres | minimaal 1 seconde tussen twee verzoeken |
Overschrijding hiervan retourneert 429. Daarnaast retourneert het bereiken van het maandelijkse berichtentegoed van het pakket ook 429 (met de melding dat de dienst tijdelijk niet beschikbaar is).
Codevoorbeelden
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);
Export-API voor Gesprekken
Exporteer je chatbotgesprekken als CSV of JSON via HTTP, gefilterd op periode. Gebruik dit voor geautomatiseerde periodieke rapportages: haal alle gesprekken van een chatbot voor een bepaalde maand op, stuur ze door naar je eigen analysesysteem of archiveer ze.
In tegenstelling tot de bovenstaande chat-endpoints maakt dit deel uit van de dashboard-API. De authenticatie verloopt niet via het domein. Je logt in met je accountgegevens en gebruikt de sessiecookie opnieuw voor het exportverzoek.
Authenticatie
POST https://webchatagent.com/api/auth/login
Verstuur je dashboard-e-mailadres en -wachtwoord als JSON. De respons stelt een sessiecookie in; voeg deze toe aan elk volgend verzoek. Er is geen afzonderlijke API-sleutel.
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
email | string | Ja | Het e-mailadres waarmee je inlogt op het dashboard. |
password | string | Ja | Je dashboardwachtwoord. |
Vereisten:
- Beschikbaar binnen elk pakket.
- Teamleden hebben de machtiging Gesprekken nodig.
Gesprekken exporteren
GET https://webchatagent.com/api/conversations/export
Queryparameters
| Parameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
chatbotId | string (UUID) | Nee | Beperk de export tot één chatbot. Laat dit weg om alle chatbots te exporteren waartoe je toegang hebt. |
from | string (YYYY-MM-DD) | Nee | Begin van de periode, inclusief (UTC-daggrens). |
to | string (YYYY-MM-DD) | Nee | Einde van de periode, inclusief (UTC-daggrens). |
q | string | Nee | Zoekfilter. Zoekt op sessie-ID, client-IP of berichtinhoud. |
format | string | Nee | csv (standaard) of json. |
Een gesprek valt binnen het bereik zodra het minstens één bericht binnen de periode bevat. Overeenkomende gesprekken worden volledig geëxporteerd, inclusief berichten buiten de periode, zodat een transcript dat over een maandgrens heen loopt nooit wordt afgekapt.
CSV-formaat: één rij per bericht, waarbij de metagegevens van het gesprek (chatbotnaam, sessie-ID, aantal berichten, laatste activiteit) op elke rij worden herhaald. Dit wordt geleverd als een bestandsbijlage met een UTF-8 BOM, zodat het direct goed opent in Excel.
JSON-formaat: één object per gesprek met de bijbehorende berichten genest:
{
"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"
}
]
}
]
}
Limieten: een export is gemaximeerd op 50.000 berichten. Grotere verzoeken retourneren 413; verklein de periode of selecteer één enkele chatbot. Client-IP-adressen worden in beide formaten geanonimiseerd.
Endpoints voor toolgegevens
De overige dashboardtools kunnen via dezelfde sessiecookie-authenticatie worden uitgelezen en ondersteunen dezelfde from / to datumfiltering (op de aanmaakdatum van elk record, UTC-daggrenzen, beide inclusief). Ze retourneren uitsluitend JSON; ze accepteren ook allemaal verzoeken zonder datumparameters om alles op te halen.
| Endpoint | Retourneert | Teammachtiging |
|---|---|---|
GET /api/questions | { success, questions: [...] } | Vragen |
GET /api/feedback | { success, data: [...], count } | Feedback |
GET /api/leads | { success, leads: [...] } | Leads |
GET /api/bookings | [...] (reguliere array), accepteert ook chatbotId | Boekingen |
Binnen het gratis pakket maken deze endpoints inhoudsvelden onleesbaar (***) in plaats van 403 te retourneren.
# All leads collected in June
curl -b cookies.txt \
"https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"
Voorbeeld: Maandelijkse export met 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"
Foutcodes
| Status | Betekenis |
|---|---|
401 | Niet ingelogd of sessie verlopen. Log opnieuw in. |
403 | Gratis pakket, ontbrekende machtiging voor Gesprekken of geen chatbot-toegang. |
404 | De opgegeven chatbotId bestaat niet binnen je account. |
413 | Meer dan 50.000 berichten gevonden. Verklein de periode of kies één chatbot. |
