Hjälpcenter
Chat API

Bot Talk API

Senast uppdaterad:

Bot Talk API

Bot Talk API är ett REST API för att kommunicera med en specifik chattbot från din egen applikation - anpassade appar, interna verktyg eller automatiseringar du bygger själv. Du skapar en API-nyckel på botens API-flik och anropar sedan chatt-slutpunkten med nyckeln som en Bearer-token för att få botens svar, antingen som ett enskilt svar eller streamat via SSE.

Kom igång

  1. Välj din chattbot och navigera till API-fliken högst upp på botsidan (Select Bot > API (Välj bot > API)).

Fliken Bot Talk API

  1. Klicka på Create API Key (Skapa API-nyckel).

API-fliken markerad; Create API Key finns i sidans innehåll

Räknaren bredvid knappen visar hur många nycklar som är aktiva ("1 of 5 API keys active"). Länken View API Documentation (Visa API-dokumentation) öppnar denna referens, och curl-kodfragmentet under Quick Start (Snabbstart) ger dig ett färdigt exempel att köra.

  1. I dialogrutan Create API Key anger du ett namn för nyckeln, ställer valfritt in en IP-vitlista och en hastighetsbegränsning (rate limit), väljer vilka behörigheter den ska ha och klickar sedan på Create (Skapa).

Dialogrutan Create API Key

  1. Kopiera hela nyckeln från framgångsdialogen. Klartexten visas bara en gång.

En nyckel ser ut som ck_abcdefghijklmnopqrstuvwxyz012345. Varje nyckel tillhör just den boten, så varje förfrågan som görs med nyckeln kommunicerar med den boten - boten identifieras av nyckeln och visas aldrig i webbadressen.

  1. Kör curl-exemplet nedan från din server med din nyckel och ett kort testmeddelande. Spara det returnerade conversationId och återanvänd det sedan för en uppföljning. Bekräfta svaret och konversationen på botens Chatlogs-flik (Chattloggar).

Förvara ck_-nycklar på din server, inte i webbplatsens JavaScript eller i mobilapp-paket. En Conversations-behörighet ger åtkomst till denna bots sparade konversationer över alla besökare, så din applikation måste auktorisera varje slutanvändare innan dessa data returneras. Använd Revoke (Återkalla) eller Delete (Ta bort) på API-fliken för att ta en nyckel ur bruk; ingen av åtgärderna visar dess klartext igen.

Innan du börjar bör du skapa och träna din chattbot samt kontrollera att ditt konto inkluderar API-åtkomst och har meddelandekrediter.

Bas-URL

https://api.chatlab.com/aichat

Alla slutpunkter i denna artikel är relativa till denna bas-URL.

Nyckelbehörigheter

Varje nyckel har en eller båda av dessa behörigheter, vilka ställs in med reglagen i dialogrutan Create API Key:

  • Chat (send messages and receive responses) - tillåter slutpunkterna /v1/chat och /v1/chat/stream.
  • Conversation history (list and read past conversations) - tillåter slutpunkterna /v1/conversations.

API-fliken visar varje nyckels beviljade behörigheter som Chat- och Conversations-brickor.

Autentisering

Skicka nyckeln i Authorization-headern vid varje förfrågan:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Förfrågningar utan en Authorization: Bearer ...-header returnerar 401 missing_api_key. Okända nycklar returnerar 401 invalid_api_key; återkallade nycklar returnerar 401 revoked_api_key. Fem ogiltiga försök under en minut från samma IP-adress utlöser en 60-minuters blockering.

Gränser

  • Max 5 aktiva Bot Talk-nycklar per bot
  • Max 60 förfrågningar per minut per nyckel (token bucket, kapacitet 60, jämn påfyllning med 1 token per sekund). Kan konfigureras nedåt när den skapas - ställ in ett lägre rateLimitPerMinute så sänks taket, och påfyllningshastigheten skalas med det.
  • Max meddelandelängd 4000 tecken
  • Samtidiga SSE-strömmar per nyckel omfattas av dina kontogränser

Slutpunkter

POST /v1/chat

Skicka ett meddelande till boten och ta emot hela svaret i ett enda 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 sträng, max 4000 tecken.
  • conversationId - valfritt UUID. Utelämna för en ny konversation; återanvänd värdet som servern returnerade tidigare för att bygga vidare på en befintlig.
  • metadata - valfritt objekt som accepterar {source, userName, userEmail, userPhone}. För närvarande används endast userEmail här, för att härleda klientidentifieraren; kanalen registreras som API. Förlita dig inte på att de andra metadatafälten sparas i 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 är alltid "assistant"; message.content är hela svaret.
  • model är modell-id som boten kördes på för detta anrop.
  • usage.creditsUsed rapporterar för närvarande 2 plus en per rapporterat verktygsanrop för en slutförd omgång. Denna svarsräknare inkluderar inte kreditmultiplikatorer för modell/kontext och får inte användas som din faktureringsbokföring. Använd Management API usage för kontoförbrukning och se meddelandekrediter.
  • actions listar verktygskörningar som kördes under denna omgång. Idag skickas endast function_call-poster (med type, name, status: "completed").

POST /v1/chat/stream

Streamande variant av /v1/chat. Returnerar Content-Type: text/event-stream med Server-Sent Events.

Request body

Samma struktur som POST /v1/chat. Flaggan stream i bodyn krävs inte - det är valet av denna sökväg som utlöser SSE.

Response body (SSE-händelser)

  • message.reset - kasta bort texten som samlats för det aktuella svaret och börja samla deltan igen. Detta kan inträffa när genereringen startar om; att lägga till båda versionerna skulle visa ett duplicerat eller ersatt svar.
  • message.delta - innehållsfragment { "content": "..." }. Flera av dessa strömmas allteftersom tokens anländer.
  • action - verktygskörning { "type", "name", "status": "executing" }. Skickas när boten utlöser ett funktionsanrop.
  • message.done - avslutande händelse med conversationId, model, usage och (om några finns) den slutförda actions-listan.
  • error - skickas om genereringen misslyckas; strömmen avslutas därefter.

Keep-alive SSE-kommentarer (:keepalive) skickas var 15:e sekund under långa genereringar. Timeouts på serversidan: 30 sekunder för den första tokenn, 120 sekunder totalt per ström.

Curl-exempel

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

Lista konversationer för boten som är kopplad till din nyckel, från alla källor (widget, WhatsApp, API osv.).

Query-parametrar

  • limit - 1-100, standardvärde 20. Värden utanför intervallet justeras till gränsvärdena.
  • cursor - ogenomskinligt värde som returnerades i nextCursor på föregående sida. Utelämna för den första sidan.

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 trunkeras till 100 tecken med ett ...-suffix.
  • nextCursor är null på den sista sidan; skicka det som cursor för att hämta nästa.

GET /v1/conversations/{conversation_id}

Sparade konversationsmeddelanden som exponeras av denna slutpunkt.

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

Endast user- och assistant-roller returneras; interna system- och verktygsmeddelanden filtreras bort. Returnerar 404 not_found_error om konversationen inte tillhör boten som är kopplad till din nyckel.

För att granska botkonfigurationen använder du Management API-slutpunkten GET /v1/management/bots/{bot_id} med en Management-nyckel.

Headers för hastighetsbegränsning

Svar som når steget för hastighetsbegränsning (dvs. autentisering och IP-vitlista har godkänts) inkluderar:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - taket per nyckel som faktiskt tillämpas på detta anrop (60 som standard, eller ditt konfigurerade rateLimitPerMinute om det är lägre).
  • X-RateLimit-Remaining - återstående tokens i hinken direkt efter detta anrop.
  • X-RateLimit-Reset - Unix epoch-sekunder då nästa token blir tillgänglig (inte en fullständig återställning av hinken; hinken fylls på kontinuerligt). När hinken är full är detta den aktuella tiden.

Vid 429 rate_limit_exceeded-svar sätts även Retry-After, uttryckt i hela sekunder tills minst en token frigörs.

Fel före autentisering (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) och 403 ip_not_whitelisted innehåller inte X-RateLimit-*-headers - hastighetsbegränsaren kontrolleras först efter att autentisering och IP-kontroller har godkänts.

Felformat

Alla fel delar samma struktur:

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

Vanliga HTTP-koder:

  • 400 invalid_request_error - felaktig indata (invalid_parameter)
  • 415 invalid_request_error - innehållstyp som inte stöds (unsupported_media_type)
  • 401 authentication_error - nyckel saknas (missing_api_key), okänd nyckel (invalid_api_key) eller återkallad nyckel (revoked_api_key)
  • 402 quota_exceeded_error - meddelandekrediterna är slut
  • 403 permission_error - IP blockerad (ip_blocked), IP finns inte i nyckelns vitlista (ip_not_whitelisted) eller nyckeltypen tillåter inte denna slutpunkt (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - konversationen tillhör inte denna bot
  • 405 invalid_request_error (method_not_allowed) - fel HTTP-verb på webbadressen
  • 429 rate_limit_error - för många förfrågningar (rate_limit_exceeded) eller för många samtidiga strömmar (concurrent_streams_exceeded)
  • 500 api_error - internt fel

Relaterat

För åtgärder på kontonivå (skapa botar, uppdatera botar, hämta förbrukning), se Management API.

Sök bland alla artiklarFråga agenten