Chatbot REST API-referentie

REST API

Stuur een bericht naar je Chatbot en ontvang een door AI gegenereerd antwoord via standaard HTTP. Gebruik dit om een aangepaste chat-UI, een mobiele app of een backend-automatisering te bouwen. Elk eindpunt wordt gehost vanaf dezelfde origin als je Widget-script (https://webchatagent.com).

Hoe een gesprek werkt

1. POST het message van de gebruiker en je chatbotId naar /api/chat.
2. Lees de reply uit de JSON-body. Lees de X-Chat-Session-Id response header, dat is je Sessie-ID.
3. Stuur voor het volgende bericht hetzelfde Sessie-ID mee in de X-Chat-Session-Id request header. De server heeft nu gesprekscontext: berichtgeschiedenis, op bronnen gebaseerde kenniscontext (Retrieval-Augmented Generation, RAG) en de status van Live chat.
4. Herhaal dit. Laat de header weg wanneer je een nieuw gesprek wilt starten.

De server houdt de geschiedenis per sessie bij, waardoor je altijd alleen het laatste bericht verstuurt, nooit het volledige transcript.

Authenticatie

De API gebruikt domeingebaseerde authenticatie: er is geen API-sleutel. Elk verzoek wordt gecontroleerd aan de hand van de geconfigureerde Toegestane domeinen van de Chatbot met behulp van de Origin/Referer van het verzoek. Een verzoek van een domein dat niet is toegestaan, krijgt een 403.

Voor AI Team Wiki-chatbots met beveiligde toegang stuur je 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

Request body

Voorbeeldverzoek

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

Respons

Het Sessie-ID wordt geretourneerd in de X-Chat-Session-Id response header, niet in de body.

Wanneer een menselijke agent het gesprek heeft overgenomen (mode: "human", status: "open"), kan de reply leeg zijn, de agent antwoordt afzonderlijk. Terwijl een overname op waiting staat, is het antwoord een korte melding zoals "Een teamlid sluit zich zo snel mogelijk aan."

Sources-array

Elk bronobject:

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: Als streaming is ingeschakeld voor een Chatbot, ontvangt de Widget het antwoord token voor token via Server-Sent Events. De hier gedocumenteerde gewone JSON-respons is wat je ontvangt bij een standaardverzoek en is het juiste model voor server-naar-server- en de meeste aangepaste UI-integraties.

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 vanwege de AVG/GDPR; een verlopen sessie retourneert 410.

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

Query-parameters

Respons

messages is gesorteerd van oud naar nieuw. sender is bot of user (dit is een weergavewaarde, niet de onderliggende rol). role is de onderliggende user / assistant / system rol, en isAgent is true wanneer een assistant-bericht afkomstig is van een menselijke agent 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 je de Sessie-ID's doorgeven die je al hebt (bijvoorbeeld uit de lokale opslag). Sessies zonder activiteit in de laatste 30 dagen worden niet geretourneerd.

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

Query-parameters

Respons

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

Sessiegeschiedenis resetten

Wis de gesprekscontext in het geheugen voor een sessie, zodat het volgende bericht de AI opnieuw laat beginnen (zonder eerdere interacties). Hiermee worden opgeslagen berichten niet verwijderd, conversation_messages zijn bedrijfsgegevens en blijven in de database (en in /api/chat/history) bewaard.

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

Headers

Respons

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

Foutafhandeling

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.

Body bij foutrespons

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

De body is altijd { reply, sources }, er is geen afzonderlijke fout-envelope. Maak vertakkingen op basis van de HTTP-statuscode en toon reply aan de gebruiker als je een kant-en-klaar bericht wilt weergeven.

Verzoeklimieten (Rate Limiting)

Het overschrijden van een van beide retourneert 429. Daarnaast retourneert het bereiken van het maandelijkse berichtquotum van het Pakket ook 429 (met een melding dat de service 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);

Conversations Export API

Exporteer je chatbotgesprekken als CSV of JSON via HTTP, gefilterd op periode. Gebruik dit om periodieke rapportages te automatiseren: haal alle gesprekken van een chatbot voor een bepaalde maand op, gebruik ze voor je eigen analyses, of archiveer ze.

In tegenstelling tot de bovenstaande chat-endpoints maakt dit deel uit van de dashboard-API. Deze is niet domeingeverifieerd. Je logt in met je accountgegevens en hergebruikt de sessiecookie voor het exportverzoek.

Authenticatie

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

Verstuur je dashboard e-mailadres en wachtwoord als JSON. Het antwoord stelt een sessiecookie in; voeg deze toe aan elk volgend verzoek. Er is geen aparte API-sleutel.

Vereisten:

• Een betaald pakket. Het export-endpoint retourneert 403 op het gratis pakket.
• Teamleden hebben de machtiging Gesprekken nodig.

Gesprekken exporteren

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

Queryparameters

Een gesprek valt "binnen het bereik" wanneer het ten minste één bericht binnen de periode heeft. Overeenkomende gesprekken worden volledig geëxporteerd, inclusief berichten buiten het bereik, 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. Geretourneerd als 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 beperkt tot maximaal 50.000 berichten. Grotere verzoeken retourneren 413; verklein de periode of selecteer één enkele chatbot. Client-IP's worden in beide formaten geanonimiseerd.

Endpoints voor toolgegevens

De andere dashboardtools zijn leesbaar via dezelfde sessiecookie-authenticatie en ondersteunen dezelfde from / to datumfiltering (op de aanmaakdatum van elk record, UTC-daggrenzen, beide inclusief). Ze retourneren alleen JSON; ze accepteren allemaal ook verzoeken zonder datumparameters om alles op te halen.

Op het gratis pakket anonimiseren deze endpoints inhoudsvelden (***) in plaats van een 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