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 strömmat via SSE.

Komma igång

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

Bot Talk API-flik

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

API-flik med knappen Create API Key markerad

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 Quick Start (Snabbstart) ger dig ett exempel som är redo att köras.

  1. I dialogrutan Create API Key (Skapa API-nyckel) ger du nyckeln ett namn, ställer valfritt in en IP-vitlista och en hastighetsbegränsning, väljer vilka behörigheter den har 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 den specifika boten, så varje anrop som görs med nyckeln kommunicerar med den boten - boten identifieras av nyckeln och visas aldrig i webbadressen.

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, inställda 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-märken.

Autentisering

Skicka nyckeln i Authorization-headern vid varje anrop:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Anrop 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 blockering på 60 minuter.

Begränsningar

  • Max 5 aktiva Bot Talk-nycklar per bot
  • Max 60 anrop per minut per nyckel (token bucket, kapacitet 60, jämn påfyllning med 1 token per sekund). Konfigurerbar nedåt när nyckeln skapas - ställ in ett lägre rateLimitPerMinute så sänks taket, och påfyllningshastigheten skalas därefter.
  • Maximal meddelandelängd 4000 tecken
  • Samtidiga SSE-strömmar per nyckel omfattas av dina kontobegränsningar

Slutpunkter

POST /v1/chat

Skicka ett meddelande till boten och ta emot hela svaret i ett enskilt JSON-svar.

Förfrågans brödtext

{
  "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 tidigare returnerade för att bygga vidare på en befintlig konversation.
  • metadata - valfritt objekt: {source, userName, userEmail, userPhone}. userEmail används också för att härleda internt klient-id.

Svarsbrödtext (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 är alltid "assistant"; message.content är hela svaret.
  • model är det modell-id som boten kördes på för detta anrop.
  • usage.creditsUsed omfattar användarmeddelandet + botsvaret (vanligtvis 2), plus en extra kredit per kört verktygsanrop.
  • actions listar verktygskörningar som utfördes under denna omgång. För närvarande skickas endast function_call-poster (med type, name, status: "completed").

POST /v1/chat/stream

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

Förfrågans brödtext

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

Svarsbrödtext (SSE-händelser)

  • message.delta - innehållsfragment { "content": "..." }. Flera sådana strömmas i takt med att 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 sådana finns) den slutförda actions-listan.
  • error - skickas om genereringen misslyckas; strömmen avslutas därefter.

Keep-alive-kommentarer via SSE (:keepalive) skickas var 15:e sekund under långa genereringar. Tidsgränser på serversidan: 30 sekunder för den första tokenen, totalt 120 sekunder 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 den bot som är bunden till din nyckel, över alla källor (widget, WhatsApp, API osv.).

Frågeparametrar

  • 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.

Svarsbrödtext (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}

Fullständig konversationshistorik.

Svarsbrödtext (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 rollerna user och assistant 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.

Hastighetsbegränsnings-headers

Svar som når hastighetsbegränsningssteget (dvs. godkänd autentisering och IP-vitlista) innehåller:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - gränsen per nyckel som faktiskt tillämpades 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-epoksekunder 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 inkluderas ä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-*-headrar - begränsaren kontrolleras först efter att autentisering och IP-kontroller har lyckats.

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 (koder: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - saknad nyckel (missing_api_key), okänd nyckel (invalid_api_key) eller återkallad nyckel (revoked_api_key)
  • 402 quota_exceeded_error - meddelandekrediter ä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 anrop (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 användning), se Management API.

Sök bland alla artiklarFråga agenten