Helpcentrum
Chat API

Bot Talk API

Laatst bijgewerkt:

Bot Talk API

De Bot Talk API is een REST-API waarmee je met één specifieke chatbot kunt communiceren vanuit je eigen applicatie - zoals maatwerk-apps, 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, hetzij als één enkel antwoord, hetzij gestreamd via SSE.

Aan de slag

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

Tabblad Bot Talk API

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

Tabblad API met de knop Create API Key gemarkeerd

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

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

Dialoogvenster Create API Key

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

Een sleutel ziet eruit als ck_abcdefghijklmnopqrstuvwxyz012345. Elke sleutel hoort bij die ene specifieke bot. Elk verzoek dat met de sleutel wordt gedaan communiceert dan ook met die bot - de bot wordt geïdentificeerd aan de hand van de sleutel en verschijnt nooit in de URL.

Basis-URL

https://api.chatlab.com/aichat

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

Sleutelrechten

Elke sleutel bevat een of beide van deze rechten, in te stellen 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 /v1/conversations-endpoints.

Het tabblad API toont de toegekende rechten van elke sleutel als badges met de tekst Chat en Conversations.

Authenticatie

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

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Verzoeken zonder een Authorization: Bearer ...-header 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 van 60, gelijkmatige aanvulling met 1 token per seconde). Naar beneden configureerbaar tijdens het aanmaken - stel een lagere rateLimitPerMinute in en het maximum daalt, waarbij de aanvulsnelheid evenredig meeschaalt.
  • 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, maximaal 4000 tekens.
  • conversationId - optionele UUID. Laat leeg voor een nieuw gesprek; hergebruik de waarde die de server eerder retourneerde om aan een bestaand gesprek toe te voegen.
  • metadata - optioneel object: {source, userName, userEmail, userPhone}. userEmail wordt ook gebruikt om de interne client-id af te leiden.

Response body (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "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 telt het gebruikersbericht + botantwoord mee (doorgaans 2), plus één extra credit per uitgevoerde tool-aanroep.
  • actions toont de tool-uitvoeringen die tijdens deze beurt zijn uitgevoerd. Momenteel worden alleen function_call-items geretourneerd (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 verplicht - het gebruik van dit pad activeert automatisch SSE.

Response body (SSE-events)

  • message.delta - inhoudsfragment { "content": "..." }. Meerdere hiervan worden gestreamd naarmate tokens binnenkomen.
  • action - tool-uitvoering { "type", "name", "status": "executing" }. Wordt verzonden wanneer de bot een functie-aanroep activeert.
  • message.done - afrondend event met conversationId, model, usage en (indien van toepassing) de lijst met voltooide actions.
  • error - verzonden als de generatie mislukt; daarna stopt de stream.

Keep-alive SSE-opmerkingen (:keepalive) worden elke 15 seconden verzonden tijdens lange generaties. 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

Overzicht van 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 begrensd.
  • cursor - ondoorzichtige waarde die op de vorige pagina werd geretourneerd in nextCursor. 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 tot 100 tekens met een ...-achtervoegsel.
  • nextCursor is null op de laatste pagina; geef deze mee als cursor om de volgende op te halen.

GET /v1/conversations/{conversation_id}

Volledige gespreksgeschiedenis.

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 daadwerkelijk toegepaste maximum per sleutel voor deze aanroep (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 meegestuurd, uitgedrukt in hele 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 geformatteerde invoer (codes: invalid_parameter, 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 - berichtcredits verbruikt
  • 403 permission_error - IP geblokkeerd (ip_blocked), IP niet aanwezig op de whitelist van de sleutel (ip_not_whitelisted) of 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) - verkeerd HTTP-werkwoord 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 (bots aanmaken, bots bijwerken, verbruik ophalen).

Doorzoek alle artikelenVraag het de agent