Helpcentrum
Chat API

Bot Talk API

Laatst bijgewerkt:

Bot Talk API

De Bot Talk API is een REST-API waarmee je communiceert met één specifieke chatbot vanuit je eigen applicatie - denk aan maatwerkapps, interne tools of zelfgebouwde automatiseringen. Je maakt een API-sleutel aan op het tabblad API van de bot en roept vervolgens het chat-endpoint aan met de sleutel als Bearer-token om de antwoorden van de bot te ontvangen, als eenmalige respons of gestreamd via SSE.

Aan de slag

  1. Selecteer je chatbot en ga naar het tabblad API boven aan de botpagina (Select Bot > API (Bot selecteren > API)).

Tabblad Bot Talk API

  1. Klik op Create API Key (API-sleutel aanmaken).

Tabblad API gemarkeerd; Create API Key bevindt zich in de pagina-inhoud

De teller naast de knop toont hoeveel sleutels actief zijn ("1 of 5 API keys active"). De link View API Documentation (API-documentatie bekijken) opent deze handleiding en het curl-fragment onder Quick Start (Snelle start) biedt een direct bruikbaar voorbeeld.

  1. Geef de sleutel in het dialoogvenster Create API Key een naam, stel eventueel een IP-whitelist en een snelheidslimiet in, kies welke machtigingen deze krijgt en klik vervolgens op Create (Aanmaken).

Dialoogvenster Create API Key

  1. Kopieer de volledige sleutel uit het bevestigingsvenster. De tekst zonder opmaak wordt slechts één keer weergegeven.

Een sleutel ziet eruit als ck_abcdefghijklmnopqrstuvwxyz012345. Elke sleutel hoort bij die ene bot, dus elk verzoek met deze sleutel communiceert met die bot - de bot wordt geïdentificeerd door de sleutel en verschijnt nooit in de URL.

  1. Voer vanaf je server het onderstaande curl-voorbeeld uit met je sleutel en een kort testbericht. Sla de geretourneerde conversationId op en gebruik deze opnieuw voor een vervolgbericht. Controleer het antwoord en het gesprek op het tabblad Chatlogs (Gesprekslogboeken) van de bot.

Bewaar ck_-sleutels op je server, niet in JavaScript op de website of in de code van mobiele apps. De machtiging Conversations verleent toegang tot de bewaarde gesprekken van deze bot van alle bezoekers. Je applicatie moet daarom elke eindgebruiker autoriseren voordat deze gegevens worden geretourneerd. Gebruik Revoke (Intrekken) of Delete (Verwijderen) op het tabblad API om een sleutel buiten gebruik te stellen; bij geen van beide acties wordt de sleutel opnieuw in platte tekst getoond.

Voordat je begint, kun je je chatbot aanmaken en trainen en controleren of je account API-toegang heeft en over bericht-credits beschikt.

Basis-URL

https://api.chatlab.com/aichat

Alle endpoints in dit artikel zijn relatief ten opzichte van deze basis-URL.

Sleutelmachtigingen

Elke sleutel bevat een of beide van deze machtigingen, ingesteld met de schakelaars in het dialoogvenster Create API Key:

  • Chat (send messages and receive responses) - geeft toegang tot de endpoints /v1/chat en /v1/chat/stream.
  • Conversation history (list and read past conversations) - geeft toegang tot de endpoints /v1/conversations.

Het tabblad API toont de toegekende machtigingen van elke sleutel als badges voor Chat en Conversations.

Authenticatie

Stuur de sleutel mee in de header Authorization bij elk verzoek:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Verzoeken zonder de header Authorization: Bearer ... retourneren 401 missing_api_key. Onbekende sleutels retourneren 401 invalid_api_key; ingetrokken sleutels retourneren 401 revoked_api_key. Vijf ongeldige pogingen binnen een minuut vanaf hetzelfde IP-adres leiden tot een blokkade van 60 minuten.

Limieten

  • Maximaal 5 actieve Bot Talk-sleutels per bot
  • Maximaal 60 verzoeken per minuut per sleutel (token bucket, capaciteit 60, geleidelijke aanvulling met 1 token per seconde). Naar beneden configureerbaar bij het aanmaken - stel een lagere rateLimitPerMinute in om de limiet te verlagen; de aanvulsnelheid schaalt evenredig mee.
  • Maximale berichtlengte 4000 tekens
  • Gelijktijdige SSE-streams per sleutel zijn afhankelijk van je accountlimieten

Endpoints

POST /v1/chat

Stuur een bericht naar de bot en ontvang het volledige antwoord in één JSON-respons.

Request body

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - verplichte string, max. 4000 tekens.
  • conversationId - optionele UUID. Laat leeg voor een nieuw gesprek; hergebruik de waarde die de server eerder heeft geretourneerd om toe te voegen aan een bestaand gesprek.
  • metadata - optioneel object dat {source, userName, userEmail, userPhone} accepteert. Momenteel wordt hier alleen userEmail gebruikt om de client-identificatie af te leiden; het kanaal wordt geregistreerd als API. Vertrouw er niet op dat de overige metadata-velden worden opgeslagen in een lead-record.

Response body (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role is altijd "assistant"; message.content is het volledige antwoord.
  • model is de model-ID waarop de bot voor deze aanroep draaide.
  • usage.creditsUsed rapporteert momenteel 2 plus één per gerapporteerde tool-aanroep voor een voltooide beurt. Deze responsteller bevat geen credit-vermenigvuldigers voor model/context en mag niet worden gebruikt als je facturatie-overzicht. Gebruik het verbruik van de Management API voor accountverbruik en bekijk bericht-credits.
  • actions toont tool-uitvoeringen die tijdens deze beurt zijn uitgevoerd. Momenteel worden alleen function_call-items gerapporteerd (met type, name, status: "completed").

POST /v1/chat/stream

Streamingvariant van /v1/chat. Retourneert Content-Type: text/event-stream met Server-Sent Events.

Request body

Zelfde structuur als POST /v1/chat. De vlag stream in de body is niet vereist - het gebruik van dit pad activeert automatisch SSE.

Response body (SSE-events)

  • message.reset - verwerpt de verzamelde tekst voor het huidige antwoord en begint opnieuw met het verzamelen van delta's. Dit kan gebeuren wanneer het genereren opnieuw start; het samenvoegen van beide versies zou een dubbel of achterhaald antwoord tonen.
  • message.delta - inhoudsfragment { "content": "..." }. Meerdere van deze worden gestreamd naarmate tokens binnenkomen.
  • action - tool-uitvoering { "type", "name", "status": "executing" }. Wordt verzonden wanneer de bot een functieaanroep activeert.
  • message.done - eindgebeurtenis met conversationId, model, usage en (indien aanwezig) de voltooide lijst met actions.
  • error - wordt verzonden als het genereren mislukt; de stream wordt daarna beëindigd.

Keep-alive SSE-opmerkingen (:keepalive) worden elke 15 seconden verzonden tijdens lange generatiesessies. Time-outs aan de serverzijde: 30 seconden voor het eerste token, 120 seconden in totaal per stream.

Curl-voorbeeld

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Toon een lijst met gesprekken voor de bot die aan je sleutel is gekoppeld, over alle bronnen heen (widget, WhatsApp, API, enz.).

Query parameters

  • limit - 1-100, standaard 20. Waarden buiten het bereik worden afgekapt.
  • cursor - ondoorzichtige waarde die op de vorige pagina in nextCursor werd geretourneerd. Laat leeg voor de eerste pagina.

Response body (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview wordt afgekapt op 100 tekens met het achtervoegsel ....
  • nextCursor is null op de laatste pagina; geef dit door als cursor om de volgende op te halen.

GET /v1/conversations/{conversation_id}

Bewaarde gespreksberichten die door dit endpoint worden getoond.

Response body (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Alleen de rollen user en assistant worden geretourneerd; interne system- en tool-berichten worden weggefilterd. Retourneert 404 not_found_error als het gesprek niet hoort bij de bot die aan je sleutel is gekoppeld.

Gebruik het Management API-endpoint GET /v1/management/bots/{bot_id} met een Management-sleutel om de botconfiguratie te inspecteren.

Rate limit-headers

Antwoorden die de rate-limit-fase bereiken (d.w.z. geslaagd voor authenticatie en IP-whitelist) bevatten:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - het limiet per sleutel dat daadwerkelijk op deze aanroep is toegepast (standaard 60, of je geconfigureerde rateLimitPerMinute indien lager).
  • X-RateLimit-Remaining - resterende tokens in de bucket direct na deze aanroep.
  • X-RateLimit-Reset - Unix epoch-seconden waarop het volgende token beschikbaar komt (geen volledige bucket-reset; de bucket wordt continu aangevuld). Wanneer de bucket vol is, is dit de huidige tijd.

Bij 429 rate_limit_exceeded-antwoorden wordt ook Retry-After meegegeven, uitgedrukt in gehele seconden totdat er ten minste één token vrijkomt.

Fouten vóór authenticatie (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) en 403 ip_not_whitelisted bevatten de X-RateLimit-*-headers niet - de limiter wordt pas geraadpleegd nadat de authenticatie en IP-controles zijn geslaagd.

Foutindeling

Alle fouten delen één vaste structuur:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Veelvoorkomende HTTP-codes:

  • 400 invalid_request_error - onjuist opgemaakte invoer (invalid_parameter)
  • 415 invalid_request_error - niet-ondersteund inhoudstype (unsupported_media_type)
  • 401 authentication_error - ontbrekende sleutel (missing_api_key), onbekende sleutel (invalid_api_key) of ingetrokken sleutel (revoked_api_key)
  • 402 quota_exceeded_error - bericht-credits verbruikt
  • 403 permission_error - IP-adres geblokkeerd (ip_blocked), IP-adres niet in de whitelist van de sleutel (ip_not_whitelisted) of het sleuteltype staat dit endpoint niet toe (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - gesprek hoort niet bij deze bot
  • 405 invalid_request_error (method_not_allowed) - onjuiste HTTP-methode op de URL
  • 429 rate_limit_error - te veel verzoeken (rate_limit_exceeded) of te veel gelijktijdige streams (concurrent_streams_exceeded)
  • 500 api_error - interne fout

Gerelateerd

Zie de Management API voor bewerkingen op accountniveau (zoals bots aanmaken, bots bijwerken en verbruik ophalen).

Doorzoek alle artikelenVraag het de agent