Hjælpecenter
Chat API

Bot Talk API

Sidst opdateret:

Bot Talk API

Bot Talk API er et REST API til at kommunikere med en specifik chatbot fra din egen applikation - tilpassede apps, interne værktøjer eller automatiseringer, du selv bygger. Du opretter en API-nøgle under bottens fane API, og kalder derefter chat-endpointet med nøglen som et Bearer-token for at modtage bottens svar, enten som et enkelt svar eller streamet via SSE.

Kom godt i gang

  1. Vælg din chatbot, og gå til fanen API øverst på bottens side (Select Bot > API (Vælg bot > API)).

Fanen Bot Talk API

  1. Klik på Create API Key (Opret API-nøgle).

Fanen API med knappen Create API Key fremhævet

Tælleren ved siden af knappen viser, hvor mange nøgler der er aktive ("1 of 5 API keys active"). Linket View API Documentation (Vis API-dokumentation) åbner denne reference, og curl-kodestykket under Quick Start (Hurtig start) giver dig et eksempel, der er lige til at køre.

  1. I dialogboksen Create API Key giver du nøglen et navn, angiver eventuelt en IP-whiteliste og en hastighedsgrænse (rate limit), vælger dens tilladelser og klikker på Create (Opret).

Dialogboksen Create API Key

  1. Kopiér hele nøglen fra bekræftelsesdialogen. Nøglen i klartekst vises kun én gang.

En nøgle ser ud som ck_abcdefghijklmnopqrstuvwxyz012345. Hver nøgle tilhører netop denne ene bot, så enhver anmodning foretaget med nøglen kommunikerer med denne bot - botten identificeres via nøglen og optræder aldrig i URL'en.

Base-URL

https://api.chatlab.com/aichat

Alle endpoints i denne artikel er relative til denne base-URL.

Nøgletilladelser

Hver nøgle har en eller begge af disse tilladelser, som konfigureres med til/fra-knapperne i dialogboksen Create API Key:

  • Chat (send messages and receive responses) - giver adgang til endpoints /v1/chat og /v1/chat/stream.
  • Conversation history (list and read past conversations) - giver adgang til /v1/conversations-endpoints.

Fanen API viser hver nøgles tildelte tilladelser som Chat- og Conversations-badges.

Godkendelse

Send nøglen i headeren Authorization ved hver anmodning:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Anmodninger uden en Authorization: Bearer ...-header returnerer 401 missing_api_key. Ukendte nøgler returnerer 401 invalid_api_key; tilbagekaldte nøgler returnerer 401 revoked_api_key. Fem ugyldige forsøg inden for et minut fra den samme IP-adresse udløser en 60 minutters blokering.

Grænser

  • Maks. 5 aktive Bot Talk-nøgler pr. bot
  • Maks. 60 anmodninger i minuttet pr. nøgle (token bucket, kapacitet på 60, løbende genopfyldning med 1 token i sekundet). Kan konfigureres til en lavere værdi ved oprettelse - angiv en lavere rateLimitPerMinute, hvorefter loftet sænkes, og genopfyldningshastigheden skaleres tilsvarende.
  • Maks. beskedlængde på 4000 tegn
  • Samtidige SSE-streams pr. nøgle er underlagt dine kontogrænser

Endpoints

POST /v1/chat

Send en besked til botten, og modtag hele svaret i et enkelt JSON-svar.

Request body

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - påkrævet streng, maks. 4000 tegn.
  • conversationId - valgfri UUID. Udelad ved en ny samtale; genbrug værdien, som serveren returnerede tidligere, for at bygge videre på en eksisterende samtale.
  • metadata - valgfrit objekt: {source, userName, userEmail, userPhone}. userEmail bruges også til at udlede det interne kunde-id.

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 er altid "assistant"; message.content er hele svaret.
  • model er det model-id, botten kørte på under dette kald.
  • usage.creditsUsed medregner brugerbeskeden + bottens svar (typisk 2) samt én ekstra Credit pr. udført værktøjskald (tool call).
  • actions viser de værktøjskørsler, der blev afviklet under denne tur. I øjeblikket udsendes kun function_call-elementer (med type, name, status: "completed").

POST /v1/chat/stream

Streamingvariant af /v1/chat. Returnerer Content-Type: text/event-stream med Server-Sent Events.

Request body

Samme struktur som POST /v1/chat. Parameteren stream i bodyen er ikke påkrævet - selve brugen af denne sti udløser SSE.

Response body (SSE-hændelser)

  • message.delta - indholdsfragment { "content": "..." }. Flere af disse streames løbende, efterhånden som tokens ankommer.
  • action - værktøjskørsel { "type", "name", "status": "executing" }. Udsendes, når botten udløser et funktionskald.
  • message.done - sluthændelse med conversationId, model, usage og (hvis relevant) den afsluttede actions-liste.
  • error - sendes, hvis genereringen mislykkes; derefter afbrydes streamen.

Keep-alive SSE-kommentarer (:keepalive) sendes hvert 15. sekund under lange genereringer. Timeouts på serversiden: 30 sekunder for det første token, 120 sekunder i alt pr. stream.

Curl-eksempel

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

Vis samtaler for den bot, der er knyttet til din nøgle, på tværs af alle kilder (widget, WhatsApp, API osv.).

Query-parametre

  • limit - 1-100, standardværdi er 20. Værdier uden for intervallet tilpasses automatisk grænserne.
  • cursor - uigennemsigtig værdi, der returneres i nextCursor på den forrige side. Udelad den på første side.

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 afkortes til 100 tegn med et efterfølgende ....
  • nextCursor er null på den sidste side; send den med som cursor for at hente den næste.

GET /v1/conversations/{conversation_id}

Fuld samtalehistorik.

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"}
  ]
}

Kun rollerne user og assistant returneres; interne system- og værktøjsbeskeder filtreres fra. Returnerer 404 not_found_error, hvis samtalen ikke tilhører den bot, der er knyttet til din nøgle.

For at undersøge bottens konfiguration kan du bruge Management API-endpointet GET /v1/management/bots/{bot_id} med en Management-nøgle.

Rate limit-headere

Svar, der når rate limit-stadiet (dvs. godkendelse og IP-whiteliste er bestået), indeholder:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - loftet pr. nøgle, der rent faktisk anvendes for dette kald (som standard 60 eller din konfigurerede rateLimitPerMinute, hvis den er lavere).
  • X-RateLimit-Remaining - tilbageværende tokens i spanden umiddelbart efter dette kald.
  • X-RateLimit-Reset - Unix epoch-sekunder, hvor det næste token bliver tilgængeligt (ikke en fuldstændig nulstilling af spanden; spanden genopfyldes kontinuerligt). Når spanden er fuld, er dette det aktuelle tidspunkt.

Ved 429 rate_limit_exceeded-svar angives Retry-After også, udtrykt i hele sekunder, indtil mindst ét token frigøres.

Fejl før godkendelse (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) og 403 ip_not_whitelisted indeholder ikke X-RateLimit-*-headere - hastighedsbegrænseren konsulteres først, når godkendelsen og IP-kontrollerne er bestået.

Fejlformat

Alle fejl deler den samme struktur:

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

Almindelige HTTP-koder:

  • 400 invalid_request_error - forkert formateret input (koder: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - manglende nøgle (missing_api_key), ukendt nøgle (invalid_api_key) eller tilbagekaldt nøgle (revoked_api_key)
  • 402 quota_exceeded_error - besked-Credits er opbrugt
  • 403 permission_error - IP blokeret (ip_blocked), IP ikke på nøglens whiteliste (ip_not_whitelisted), eller nøgletypen tillader ikke dette endpoint (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - samtalen tilhører ikke denne bot
  • 405 invalid_request_error (method_not_allowed) - forkert HTTP-metode på URL'en
  • 429 rate_limit_error - for mange anmodninger (rate_limit_exceeded) eller for mange samtidige streams (concurrent_streams_exceeded)
  • 500 api_error - intern fejl

Relateret

For handlinger på kontoniveau (oprettelse af bots, opdatering af bots, hentning af forbrug), se Management API.

Søg i alle artiklerSpørg agenten