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

Záložka Bot Talk API

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

Zvýraznená záložka API; Create API Key je v obsahu stránky

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 príkazu curl v sekcii Quick Start (Rýchly štart) vám poskytne príklad pripravený na okamžité spustenie.

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

Dialógové okno Create API Key

  1. Skopírujte si celý kľúč z potvrdzovacieho dialógového okna. Kľúč v nezašifrovanej podobe sa zobrazí iba raz.

Kľúč vyzerá ako ck_abcdefghijklmnopqrstuvwxyz012345. Každý kľúč patrí 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 adrese URL sa nikdy neuvádza.

  1. Zo svojho servera spustite nižšie uvedený príklad príkazu curl s vaším kľúčom a krátkou testovacou správou. Uložte si vrátený parameter conversationId a potom ho znova použite pre nadväzujúcu správu. Odpoveď a konverzáciu si overte v karte Chatlogs (História konverzácií) daného bota.

Kľúče ck_ uchovávajte na svojom serveri, nie v kóde JavaScript na webe ani v balíčkoch mobilných aplikácií. Oprávnenie Conversations (Konverzácie) udeľuje prístup k uloženým konverzáciám tohto bota naprieč všetkými návštevníkmi, takže vaša aplikácia musí každého koncového používateľa pred vrátením týchto údajov autorizovať. Ak chcete kľúč vyradiť z prevádzky, použite možnosť Revoke (Odvolať) alebo Delete (Odstrániť) na karte API; žiadna z týchto akcií už nezašifrovaný kľúč znova nezobrazí.

Pred začatím vytvorte a natrénujte svojho chatbota a skontrolujte, či váš účet zahŕňa prístup k API a obsahuje kredity na správy.

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) (Chat - odosielanie správ a prijímanie odpovedí) - povoľuje koncové body /v1/chat a /v1/chat/stream.
  • Conversation history (list and read past conversations) (História konverzácií - zobrazenie zoznamu a čítanie minulých konverzácií) - 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 kompletnú odpoveď v jedinej JSON odpovedi.

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. Pre novú konverzáciu vynechajte; ak chcete nadviazať na existujúcu konverzáciu, použite hodnotu, ktorú server vrátil predtým.
  • metadata - voliteľný objekt prijímajúci {source, userName, userEmail, userPhone}. V súčasnosti sa tu používa iba userEmail na odvodenie identifikátora klienta; kanál sa zaznamenáva ako API. Nespoliehajte sa na to, že ostatné polia metadát budú uložené do záznamu leadu.

Telo odpovede (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 je vždy "assistant"; message.content predstavuje úplnú odpoveď.
  • model je ID modelu, na ktorom bot pri tomto volaní bežal.
  • usage.creditsUsed v súčasnosti hlási hodnotu 2 plus jeden kredit za každé nahlásené volanie nástroja pre dokončenú interakciu. Toto počítadlo odpovedí nezahŕňa kreditové multiplikátory modelov/kontextu a nesmie sa používať ako vaša fakturačná kniha. Pre spotrebu účtu použite údaje o spotrebe cez Management API a pozrite si kredity na správy.
  • actions uvádza spustenia nástrojov, ktoré prebehli počas tejto interakcie. V súčasnosti sa odosielajú iba položky function_call (s type, name, status: "completed").

POST /v1/chat/stream

Streamovací variant koncového bodu /v1/chat. Vracia Content-Type: text/event-stream pomocou Server-Sent Events (SSE).

Telo požiadavky

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

Telo odpovede (udalosti SSE)

  • message.reset - zahoďte naakumulovaný text pre aktuálnu odpoveď a začnite znova zbierať delty. Môže k tomu dôjsť pri reštartovaní generovania; spojenie oboch verzií by viedlo k duplicitnej alebo prekonanej odpovedi.
  • message.delta - fragment obsahu { "content": "..." }. Týchto udalostí prichádza viacero podľa toho, ako prichádzajú tokeny.
  • action - spustenie nástroja { "type", "name", "status": "executing" }. Odosiela sa vtedy, keď bot vyvolá volanie funkcie.
  • message.done - ukončujúca udalosť s conversationId, model, usage a (ak existuje) dokončeným zoznamom actions.
  • error - odosiela sa v prípade zlyhania generovania; stream sa následne ukončí.

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

Príklad pre 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 je 20. Hodnoty mimo rozsahu sa automaticky upravia na hraničné hodnoty.
  • cursor - nepriehľadná hodnota (opaque value) vrátená v parametri nextCursor na predchádzajúcej stránke. Pre prvú stránku 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 ....
  • nextCursor má na poslednej stránke hodnotu null; odovzdajte ju ako cursor na načítanie nasledujúcej stránky.

GET /v1/conversations/{conversation_id}

Uchovávané správy konverzácie sprístupnené týmto koncovým bodom.

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é. Vráti kód 404 not_found_error, ak konverzácia nepatrí botovi priradenému k vášmu kľúču.

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ú obálku:

{
  "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 - neplatný vstup (invalid_parameter)
  • 415 invalid_request_error - nepodporovaný typ obsahu (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 HTTP metóda na 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