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

  1. POST het message van de bezoeker en uw chatbotId naar /api/chat.
  2. Lees de reply uit de JSON-body. Lees de X-Chat-Session-Id response-header, dat is uw sessie-ID.
  3. Stuur bij het volgende bericht dezelfde sessie-ID mee in de X-Chat-Session-Id request-header. De server beschikt nu over gesprekscontext: berichtgeschiedenis, op bronnen gebaseerde kenniscontext (Retrieval-Augmented Generation, RAG) en de live-chatstatus.
  4. 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

HeaderVerplichtBeschrijving
Content-TypeJaMoet application/json zijn.
X-Chat-Session-IdNeeSessie-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.
AcceptNeetext/event-stream om het antwoord als stream te ontvangen (zie Streaming).
Accept-LanguageNeeVoorkeurstaal voor het antwoord, bijvoorbeeld de.

Request body

VeldTypeVerplichtBeschrijving
messagestringJaHet bericht van de bezoeker. Maximaal 700 tekens. Mag niet leeg zijn.
chatbotIdstring (UUID)JaDe ID van uw chatbot, te vinden in de chatbot-instellingen.
pageUrlstringNeeDe volledige pagina-URL waar de bezoeker zich bevindt (window.location.href). Wordt gebruikt voor contextbewuste zoekopdrachten; gevalideerd aan de hand van uw toegestane domeinen.
contextDataobjectNeePlatte 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.

VeldTypeBeschrijving
replystringHet 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.
sourcesarrayBronnen waarop het antwoord is gebaseerd (zie hieronder). Leeg als er geen bronnen zijn gebruikt.
modestringGespreksmodus: bot (AI antwoordt) of human (een live medewerker heeft overgenomen). Aanwezig wanneer relevant.
statusstringLive-chatstatus: waiting, open of closed. Alleen aanwezig wanneer Live chat actief is voor de sessie.
aiGeneratedbooleantrue wanneer de AI het antwoord heeft geschreven. Ontbreekt zolang een menselijke medewerker het gesprek afhandelt.
conversationTooLongbooleanHet 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:

VeldTypeBeschrijving
typestringweb (een websitepagina), product (gestructureerde productdata) of fileSource (een document uit gekoppelde bestandsopslag).
sourcestringVoor web: de pagina-URL. Voor product: de productidentificator. Voor fileSource: de document-ID.
dataobjectAlleen 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}
typeVeldenBetekenis
tokendataVolgende deel van het antwoord. Voeg dit toe. De tekst kan onvolledige Markdown en het begin van het suggestie-commentaar bevatten.
tool_callnameDe bot gebruikt een tool, bijvoorbeeld een zoekopdracht naar producten.
errordataEen probleem. Meestal volgt een done; als de stream eindigt zonder done, behandel data dan als de fout.
donedezelfde velden als de JSON-responsHet 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

ParameterTypeVerplichtBeschrijving
chatbotIdstring (UUID)JaDe ID van uw chatbot.
sessionIdstring (UUID)JaDe 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

ParameterTypeVerplichtBeschrijving
chatbotIdstring (UUID)JaDe ID van uw chatbot.
sessionIdsstringJaDoor 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

HeaderRequiredDescription
X-Chat-Session-IdJaDe 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.

StatusBetekenis
400Ongeldige body, ontbrekend veld, leeg bericht of bericht van meer dan 700 tekens.
403Domein niet toegestaan, wiki-authenticatie mislukt of er geldt een pakketbeperking.
404Chatbot niet gevonden.
429Rate limit bereikt of het maandelijkse berichtentegoed is op.
502De 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

BereikLimiet
Per sessie10 verzoeken per minuut
Per IP-adres15 verzoeken per minuut
Per sessie en per IP-adresminimaal 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.

VeldTypeVerplichtBeschrijving
emailstringJaHet e-mailadres waarmee je inlogt op het dashboard.
passwordstringJaJe dashboardwachtwoord.

Vereisten:

  • Beschikbaar binnen elk pakket.
  • Teamleden hebben de machtiging Gesprekken nodig.

Gesprekken exporteren

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

Queryparameters

ParameterTypeVerplichtBeschrijving
chatbotIdstring (UUID)NeeBeperk de export tot één chatbot. Laat dit weg om alle chatbots te exporteren waartoe je toegang hebt.
fromstring (YYYY-MM-DD)NeeBegin van de periode, inclusief (UTC-daggrens).
tostring (YYYY-MM-DD)NeeEinde van de periode, inclusief (UTC-daggrens).
qstringNeeZoekfilter. Zoekt op sessie-ID, client-IP of berichtinhoud.
formatstringNeecsv (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.

EndpointRetourneertTeammachtiging
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 chatbotIdBoekingen

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

StatusBetekenis
401Niet ingelogd of sessie verlopen. Log opnieuw in.
403Gratis pakket, ontbrekende machtiging voor Gesprekken of geen chatbot-toegang.
404De opgegeven chatbotId bestaat niet binnen je account.
413Meer dan 50.000 berichten gevonden. Verklein de periode of kies één chatbot.