Centrum pomoci
Chat API

Bot Talk API

Posledná aktualizácia:

Bot Talk API

Bot Talk API je rozhranie REST API na komunikáciu s jedným konkrétnym chatbotom z vašej vlastnej aplikácie - vlastných aplikácií, interných nástrojov alebo automatizácií, ktoré si sami vytvoríte. Na karte bota API vygenerujete kľúč API a potom voláte koncový bod chatu s týmto kľúčom ako Bearer tokenom, aby ste získali odpovede bota, a to buď ako samostatnú odpoveď, alebo streamovanú cez SSE.

Začíname

  1. Vyberte svojho chatbota a prejdite na kartu API v hornej časti stránky bota (Select Bot > API (Vybrať bota > API)).

Karta Bot Talk API

  1. Kliknite na Create API Key (Vytvoriť kľúč API).

Karta API so zvýrazneným tlačidlom Create API Key

Počítadlo vedľa tlačidla zobrazuje, koľko kľúčov je aktívnych („1 of 5 API keys active"). Odkaz View API Documentation (Zobraziť dokumentáciu API) otvorí túto referenčnú príručku a úryvok curl v časti Quick Start (Rýchly štart) vám poskytne príklad pripravený na spustenie.

  1. V dialógovom okne Create API Key zadajte názov kľúča, voliteľne nastavte zoznam povolených IP adries a limit frekvencie požiadaviek (rate limit), zvoľte oprávnenia a kliknite na Create (Vytvoriť).

Dialógové okno Create API Key

  1. Skopírujte celý kľúč z potvrdzujúceho dialógového okna. Nezašifrovaný text sa zobrazí iba raz.

Kľúč vyzerá ako ck_abcdefghijklmnopqrstuvwxyz012345. Každý kľúč patrí jednému konkrétnemu botovi, takže každá požiadavka odoslaná s týmto kľúčom komunikuje s daným botom - bot je identifikovaný kľúčom a v URL adrese sa nikdy neuvádza.

Základná URL adresa

https://api.chatlab.com/aichat

Všetky koncové body v tomto článku sú relatívne k tejto základnej URL adrese.

Oprávnenia kľúča

Každý kľúč má jedno alebo obe nasledujúce oprávnenia, ktoré sa nastavujú prepínačmi v dialógovom okne Create API Key:

  • Chat (send messages and receive responses) - povoľuje koncové body /v1/chat a /v1/chat/stream.
  • Conversation history (list and read past conversations) - povoľuje koncové body /v1/conversations.

Na karte API sa udelené oprávnenia každého kľúča zobrazujú ako odznaky Chat a Conversations.

Autentifikácia

Kľúč odošlite v hlavičke Authorization pri každej požiadavke:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Požiadavky bez hlavičky Authorization: Bearer ... vrátia chybu 401 missing_api_key. Neznáme kľúče vrátia 401 invalid_api_key; odvolané kľúče vrátia 401 revoked_api_key. Päť neplatných pokusov za minútu z rovnakej IP adresy vyvolá blokovanie na 60 minút.

Limity

  • Maximálne 5 aktívnych kľúčov Bot Talk na bota
  • Maximálne 60 požiadaviek za minútu na kľúč (token bucket, kapacita 60, plynulé dopĺňanie rýchlosťou 1 token za sekundu). Možnosť znížiť pri vytváraní - nastavte nižšiu hodnotu rateLimitPerMinute, čím sa zníži limit a rýchlosť dopĺňania sa podľa toho upraví.
  • Maximálna dĺžka správy je 4000 znakov
  • Súbežné streamy SSE na kľúč podliehajú limitom vášho účtu

Koncové body

POST /v1/chat

Odošlite správu botovi a získajte celú odpoveď v jedinej odpovedi JSON.

Telo požiadavky

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - povinný reťazec, max. 4000 znakov.
  • conversationId - voliteľné UUID. Vynechajte pre novú konverzáciu; na pripojenie k existujúcej konverzácii použite hodnotu, ktorú server vrátil predtým.
  • metadata - voliteľný objekt: {source, userName, userEmail, userPhone}. Hodnota userEmail sa používa aj na odvodenie interného ID klienta.

Telo odpovede (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": []
}
  • Pole message.role má vždy hodnotu "assistant"; message.content obsahuje celú odpoveď.
  • Pole model je ID modelu, na ktorom bot pri tomto volaní bežal.
  • Hodnota usage.creditsUsed započítava správu používateľa + odpoveď bota (zvyčajne 2), plus jeden dodatočný kredit za každé vykonané volanie nástroja.
  • Pole actions uvádza vykonania nástrojov, ktoré prebehli počas tohto ťahu. V súčasnosti sa odosielajú iba položky function_call (s hodnotami type, name, status: "completed").

POST /v1/chat/stream

Streamovaný variant koncového bodu /v1/chat. Vracia hlavičku Content-Type: text/event-stream s udalosťami Server-Sent Events.

Telo požiadavky

Rovnaká štruktúra ako POST /v1/chat. Príznak stream v tele požiadavky nie je povinný - použitie tejto cesty je to, čo spúšťa SSE.

Telo odpovede (udalosti SSE)

  • message.delta - fragment obsahu { "content": "..." }. Pri príchode tokenov sa ich streamuje niekoľko.
  • action - vykonanie nástroja { "type", "name", "status": "executing" }. Odošle sa, keď bot spustí volanie funkcie.
  • message.done - koncová udalosť s údajmi conversationId, model, usage a (ak existuje) zoznamom dokončených actions.
  • error - odošle sa, ak generovanie zlyhá; stream sa následne ukončí.

Počas dlhého generovania sa každých 15 sekúnd odosielajú komentáre SSE na udržanie spojenia (:keepalive). Časové limity na strane servera: 30 sekúnd na prvý token, celkovo 120 sekúnd na stream.

Príklad curl

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

Zoznam konverzácií pre bota priradeného k vášmu kľúču zo všetkých zdrojov (widget, WhatsApp, API atď.).

Parametre dopytu

  • limit - 1-100, predvolená hodnota 20. Hodnoty mimo rozsahu sa ohraničia.
  • cursor - nepriehľadná hodnota vrátená v nextCursor na predchádzajúcej stránke. Pri prvej stránke vynechajte.

Telo odpovede (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
}
  • Pole lastMessagePreview je skrátené na 100 znakov s príponou ....
  • Pole nextCursor má na poslednej stránke hodnotu null; odovzdajte ho ako cursor na načítanie ďalšej stránky.

GET /v1/conversations/{conversation_id}

Úplná história konverzácie.

Telo odpovede (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"}
  ]
}

Vracajú sa iba roly user a assistant; interné správy system a správy nástrojov sú odfiltrované. Ak konverzácia nepatrí botovi priradenému k vášmu kľúču, vráti sa chyba 404 not_found_error.

Ak chcete skontrolovať konfiguráciu bota, použite koncový bod Management API GET /v1/management/bots/{bot_id} s kľúčom Management.

Hlavičky obmedzenia frekvencie požiadaviek (rate limit)

Odpovede, ktoré dosiahnu fázu kontroly frekvencie požiadaviek (t. j. overenie autentifikácie a zoznamu povolených IP adries prebehlo úspešne), obsahujú:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limit na kľúč, ktorý sa skutočne uplatnil pri tomto volaní (predvolene 60, alebo vami nakonfigurovaná hodnota rateLimitPerMinute, ak je nižšia).
  • X-RateLimit-Remaining - zostávajúce tokeny v zásobníku bezprostredne po tomto volaní.
  • X-RateLimit-Reset - čas v sekundách Unix epoch, kedy bude k dispozícii ďalší token (nejde o úplné obnovenie zásobníka; zásobník sa dopĺňa priebežne). Keď je zásobník plný, ide o aktuálny čas.

Pri odpovediach 429 rate_limit_exceeded sa nastavuje aj hlavička Retry-After, vyjadrená v celých sekundách, kým sa neuvoľní aspoň jeden token.

Chyby pred overením (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) a 403 ip_not_whitelisted neobsahujú hlavičky X-RateLimit-* - obmedzovač sa uplatňuje až po úspešnom overení totožnosti a kontrole IP adresy.

Formát chýb

Všetky chyby používajú jednotný obal:

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

Bežné kódy HTTP:

  • 400 invalid_request_error - nesprávny formát vstupu (kódy: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - chýbajúci kľúč (missing_api_key), neznámy kľúč (invalid_api_key) alebo odvolaný kľúč (revoked_api_key)
  • 402 quota_exceeded_error - vyčerpané kredity na správy
  • 403 permission_error - zablokovaná IP adresa (ip_blocked), IP adresa nie je na zozname povolených adries kľúča (ip_not_whitelisted) alebo typ kľúča nepovoľuje tento koncový bod (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - konverzácia nepatrí tomuto botovi
  • 405 invalid_request_error (method_not_allowed) - nesprávna metóda HTTP na danej URL adrese
  • 429 rate_limit_error - príliš veľa požiadaviek (rate_limit_exceeded) alebo príliš veľa súbežných streamov (concurrent_streams_exceeded)
  • 500 api_error - interná chyba

Súvisiace

Operácie na úrovni účtu (vytváranie botov, aktualizácia botov, získavanie štatistík využitia) nájdete v časti Management API.

Prehľadávať všetky článkySpýtajte sa agenta