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 derefter kalder du 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å bot-siden (Select Bot > API (Vælg bot > API)).

Fanen Bot Talk API

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

Fanen API fremhævet; Create API Key findes i sidens indhold

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

  1. I dialogboksen Create API Key giver du nøglen et navn, angiver eventuelt en IP-whitelist og en grænse for hastighed (rate limit), vælger de ønskede tilladelser og klikker derefter 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 den ene bot, så enhver anmodning foretaget med nøglen kommunikerer med den bot - botten identificeres via nøglen og fremgår aldrig i URL'en.

  1. Kør curl-eksemplet herunder fra din server med din nøgle og en kort testbesked. Gem det returnerede conversationId, og genbrug det til en opfølgende besked. Bekræft svaret og samtalen under bottens fane Chatlogs (Samtalelogge).

Opbevar altid ck_-nøgler på din server, ikke i websitets JavaScript eller i mobilapp-pakker. Tilladelsen Conversations giver adgang til denne bots gemte samtaler på tværs af alle besøgende, så din applikation skal godkende hver enkelt slutbruger, før disse data returneres. Brug Revoke (Tilbagekald) eller Delete (Slet) under fanen API for at udfase en nøgle; ingen af handlingerne viser klarteksten igen.

Før du går i gang, skal du oprette og træne din chatbot samt kontrollere, at din konto har API-adgang og besked-credits.

Base-URL

https://api.chatlab.com/aichat

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

Nøgletilladelser

Hver nøgle har en eller begge af følgende tilladelser, som indstilles med kontakterne 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.

Under fanen API vises hver nøgles tildelte tilladelser som mærkaterne Chat og Conversations.

Godkendelse

Send nøglen i Authorization-headeren 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 samme IP-adresse udløser en 60-minutters blokering.

Grænser

  • Maks. 5 aktive Bot Talk-nøgler pr. bot
  • Maks. 60 anmodninger pr. minut pr. nøgle (token bucket, kapacitet 60, løbende genopfyldning med 1 token pr. sekund). Kan konfigureres nedadgående ved oprettelse - angiv en lavere rateLimitPerMinute, så sænkes loftet, og genopfyldningshastigheden tilpasses tilsvarende.
  • Maksimal beskedlængde 4000 tegn
  • Samtidige SSE-streams pr. nøgle afhænger af 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 - obligatorisk streng, maks. 4000 tegn.
  • conversationId - valgfri UUID. Udelad for at starte en ny samtale; genbrug værdien, som serveren returnerede tidligere, for at fortsætte en eksisterende samtale.
  • metadata - valgfrit objekt, der accepterer {source, userName, userEmail, userPhone}. I øjeblikket bruges kun userEmail her til at udlede klient-id'et; kanalen registreres som API. Forlad dig ikke på, at de øvrige metadatafelter gemmes på en lead-post.

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 er altid "assistant"; message.content er det komplette svar.
  • model er id'et for den model, botten kørte på ved dette kald.
  • usage.creditsUsed rapporterer i øjeblikket 2 plus én pr. rapporteret værktøjskald for en fuldført tur. Denne svartæller inkluderer ikke model-/kontekst-credit-multiplikatorer og må ikke bruges som faktureringsgrundlag. Brug Management API usage til kontoens forbrug, og se besked-credits.
  • actions viser værktøjskørsler, der fandt sted under denne tur. I øjeblikket udsendes kun function_call-poster (med type, name, status: "completed").

POST /v1/chat/stream

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

Request body

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

Response body (SSE-hændelser)

  • message.reset - kasser den tekst, der er akkumuleret for det aktuelle svar, og start indsamling af deltas forfra. Dette kan forekomme, når genereringen genstartes; hvis begge versioner tilføjes, vil der blive vist et duplikeret eller forældet svar.
  • 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 fuldførte actions-liste.
  • error - sendes, hvis genereringen mislykkes; streamen afbrydes derefter.

Keep-alive-SSE-kommentarer (:keepalive) sendes hvert 15. sekund under længerevarende genereringer. Server-side timeouts: 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 en liste over 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 afkortes automatisk.
  • cursor - uigennemsigtig værdi returneret i nextCursor på den forrige side. Udelad for at hente 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}

Gemte samtalebeskeder, der gøres tilgængelige via dette endpoint.

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 gennemse 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 frem til hastighedsbegrænsningstrinnet (dvs. godkendelse og IP-whitelist er bestået), inkluderer:

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

Ved 429 rate_limit_exceeded-svar inkluderes også Retry-After, angivet i hele sekunder, indtil mindst ét token frigives.

Fejl forud for godkendelse (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) samt 403 ip_not_whitelisted indeholder ikke X-RateLimit-*-headere - begrænsningsmekanismen aktiveres først efter vellykket godkendelse og IP-kontrol.

Fejlformat

Alle fejl anvender den samme overordnede struktur:

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

Almindelige HTTP-statuskoder:

  • 400 invalid_request_error - forkert formateret input (invalid_parameter)
  • 415 invalid_request_error - ikke-understøttet indholdstype (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 whitelist (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-verb i 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) henvises til Management API.

Søg i alle artiklerSpørg agenten