Centrum nápovědy
Chat API

Bot Talk API

Poslední aktualizace:

Bot Talk API

Bot Talk API je REST API pro komunikaci s jedním konkrétním chatbotem z vaší vlastní aplikace - vlastních aplikací, interních nástrojů nebo automatizací, které si sami vytvoříte. Vytvoříte si klíč API na kartě bota API, a poté zavoláte koncový bod chatu s tímto klíčem jako tokenem Bearer, abyste získali odpovědi bota, a to buď jako jednorázovou odpověď, nebo streamovanou přes SSE.

Začínáme

  1. Vyberte svého chatbota a přejděte na záložku API v horní části stránky bota (Select Bot > API (Vybrat bota > API)).

Záložka Bot Talk API

  1. Klikněte na Create API Key (Vytvořit klíč API).

Zvýrazněná záložka API; tlačítko Create API Key je v obsahu stránky

Počítadlo vedle tlačítka ukazuje, kolik klíčů je aktivních („1 of 5 API keys active“). Odkaz View API Documentation (Zobrazit dokumentaci API) otevře tuto referenční příručku a curl ukázka v části Quick Start (Rychlý start) vám poskytne příklad připravený k okamžitému spuštění.

  1. V dialogovém okně Create API Key (Vytvořit klíč API) klíč pojmenujte, volitelně nastavte povolené IP adresy (whitelist) a limit požadavků (rate limit), vyberte příslušná oprávnění a klikněte na Create (Vytvořit).

Dialogové okno Create API Key

  1. Zkopírujte celý klíč z potvrzovacího dialogového okna. Nezašifrovaný text se zobrazí pouze jednou.

Klíč vypadá jako ck_abcdefghijklmnopqrstuvwxyz012345. Každý klíč patří pouze danému botovi, takže každý požadavek odeslaný s tímto klíčem komunikuje přímo s tímto botem - bot je identifikován klíčem a v URL se nikdy neobjevuje.

  1. Ze svého serveru spusťte níže uvedený curl příklad se svým klíčem a krátkou testovací zprávou. Uložte vrácené conversationId a poté ho znovu použijte pro navazující zprávu. Odpověď a konverzaci si ověřte v záložce Chatlogs (Záznamy chatu) daného bota.

Klíče ck_ uchovávejte na svém serveru, nikoli v JavaScriptu na webu nebo v balíčcích mobilních aplikací. Oprávnění Conversations uděluje přístup k uloženým konverzacím tohoto bota napříč návštěvníky, takže vaše aplikace musí každého koncového uživatele před vrácením těchto dat autorizovat. Chcete-li klíč vyřadit, použijte na záložce API možnost Revoke (Odvolat) nebo Delete (Smazat); ani jedna akce znovu nezobrazí jeho nezašifrovaný text.

Než začnete, vytvořte a natrénujte svého chatbota a zkontrolujte, zda váš účet zahrnuje přístup k API a má kredity na zprávy.

Základní URL

https://api.chatlab.com/aichat

Všechny koncové body v tomto článku jsou relativní k této základní adrese URL.

Oprávnění klíče

Každý klíč má jedno nebo obě tato oprávnění, nastavená pomocí přepínačů v dialogovém okně Create API Key:

  • Chat (send messages and receive responses) (odesílat zprávy a přijímat odpovědi) - povoluje koncové body /v1/chat a /v1/chat/stream.
  • Conversation history (list and read past conversations) (zobrazit seznam a číst minulé konverzace) - povoluje koncové body /v1/conversations.

Na kartě API se udělená oprávnění každého klíče zobrazují jako štítky Chat a Conversations.

Ověření

Klíč odešlete v hlavičce Authorization při každém požadavku:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Požadavky bez hlavičky Authorization: Bearer ... vracejí 401 missing_api_key. Neznámé klíče vracejí 401 invalid_api_key; odvolané klíče vracejí 401 revoked_api_key. Pět neplatných pokusů za minutu ze stejné IP adresy spustí blokování na 60 minut.

Limity

  • Maximálně 5 aktivních klíčů Bot Talk na jednoho bota
  • Maximálně 60 požadavků za minutu na klíč (token bucket, kapacita 60, plynulé doplňování rychlostí 1 token za sekundu). Lze nakonfigurovat na nižší hodnotu při vytváření - nastavte nižší rateLimitPerMinute a strop klesne, rychlost doplňování se tomu přizpůsobí.
  • Maximální délka zprávy je 4000 znaků
  • Souběžné streamy SSE na jeden klíč podléhají limitům vašeho účtu

Koncové body (Endpoints)

POST /v1/chat

Odešlete botovi zprávu a získejte kompletní odpověď v jedné JSON odpovědi.

Tělo požadavku (Request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - povinný řetězec, max. 4000 znaků.
  • conversationId - volitelné UUID. U nové konverzace vynechte; pro připojení k existující konverzaci znovu použijte hodnotu, kterou server vrátil dříve.
  • metadata - volitelný objekt přijímající {source, userName, userEmail, userPhone}. V současnosti se zde používá pouze userEmail k odvození identifikátoru klienta; kanál se zaznamenává jako API. Nespoléhejte na to, že se ostatní pole metadat uloží do záznamu leadu.

Tělo odpovědi (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 představuje celou odpověď.
  • model je ID modelu, na kterém bot při tomto volání běžel.
  • usage.creditsUsed v současnosti hlásí 2 plus jeden kredit za každé nahlášené volání nástroje pro dokončený krok (turn). Toto počítadlo v odpovědi nezahrnuje kreditové násobitele modelu/kontextu a nesmí sloužit jako vaše účetní kniha pro fakturaci. Pro spotřebu účtu využijte Využití účtu přes Management API a podívejte se na kredity za zprávy (message credits).
  • actions uvádí spuštění nástrojů, která proběhla během tohoto kroku. V současné době se odesílají pouze položky function_call (s hodnotami type, name, status: "completed").

POST /v1/chat/stream

Streamovací varianta koncového bodu /v1/chat. Vrací Content-Type: text/event-stream pomocí událostí Server-Sent Events (SSE).

Tělo požadavku

Stejná struktura jako u POST /v1/chat. Příznak stream v těle není vyžadován - použití této cesty samo o sobě aktivuje SSE.

Tělo odpovědi (SSE události)

  • message.reset - zahoďte text nashromážděný pro aktuální odpověď a začněte znovu shromažďovat přírůstky (delty). K tomu může dojít při restartování generování; připojení obou verzí by vedlo k duplicitní nebo překonané odpovědi.
  • message.delta - fragment obsahu { "content": "..." }. Těchto událostí přichází více postupně se streamováním tokenů.
  • action - spuštění nástroje { "type", "name", "status": "executing" }. Odesílá se ve chvíli, kdy bot vyvolá volání funkce.
  • message.done - koncová událost obsahující conversationId, model, usage a (případně) dokončený seznam actions.
  • error - odesílá se, pokud generování selže; stream se následně ukončí.

Během dlouhých generování se každých 15 sekund posílají keep-alive SSE komentáře (:keepalive). Časové limity na straně serveru: 30 sekund na první token, celkem 120 sekund na stream.

Příklad pro 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

Zobrazí seznam konverzací bota přiřazeného k vašemu klíči napříč všemi zdroji (widget, WhatsApp, API atd.).

Parametry dotazu (Query parameters)

  • limit - 1-100, výchozí hodnota je 20. Hodnoty mimo tento rozsah se automaticky omezí na mezní hodnoty.
  • cursor - neprůhledná hodnota (opaque value) vrácená v nextCursor na předchozí stránce. U první stránky parametr vynechte.

Tělo odpovědi (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 je zkráceno na 100 znaků a doplněno příponou ....
  • nextCursor má na poslední stránce hodnotu null; pro načtení další stránky předejte tuto hodnotu jako cursor.

GET /v1/conversations/{conversation_id}

Uchovávané zprávy konverzace zpřístupněné tímto koncovým bodem.

Tělo odpovědi (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"}
  ]
}

Vrací se pouze role user a assistant; interní zprávy typu system a zprávy nástrojů se odfiltrují. Pokud konverzace nepatří botovi přiřazenému k vašemu klíči, vrátí se 404 not_found_error.

Pro kontrolu konfigurace bota použijte koncový bod Management API GET /v1/management/bots/{bot_id} s klíčem Management API.

Hlavičky limitu frekvence požadavků

Odpovědi, které dosáhnou fáze ověřování limitu frekvence (tj. ověření totožnosti a seznam povolených IP adres proběhly úspěšně), obsahují:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limit na klíč skutečně použitý pro toto volání (ve výchozím nastavení 60 nebo vámi nakonfigurovaný rateLimitPerMinute, pokud je nižší).
  • X-RateLimit-Remaining - tokeny zbývající v zásobníku bezprostředně po tomto volání.
  • X-RateLimit-Reset - sekundy Unix epochy, kdy bude k dispozici další token (nejedná se o úplné resetování zásobníku; zásobník se doplňuje průběžně). Pokud je zásobník plný, jedná se o aktuální čas.

U odpovědí 429 rate_limit_exceeded se nastavuje také Retry-After, vyjádřený v celých sekundách do uvolnění alespoň jednoho tokenu.

Chyby před ověřením (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) a 403 ip_not_whitelisted neobsahují hlavičky X-RateLimit-* - limiter se uplatňuje až po úspěšném ověření a kontrole IP adresy.

Formát chyb

Všechny chyby sdílejí jednotnou obálku:

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

Běžné HTTP kódy:

  • 400 invalid_request_error - chybný vstup (invalid_parameter)
  • 415 invalid_request_error - nepodporovaný typ obsahu (unsupported_media_type)
  • 401 authentication_error - chybějící klíč (missing_api_key), neznámý klíč (invalid_api_key) nebo odvolaný klíč (revoked_api_key)
  • 402 quota_exceeded_error - vyčerpané kredity zpráv
  • 403 permission_error - zablokovaná IP adresa (ip_blocked), IP adresa není na whitelistu klíče (ip_not_whitelisted) nebo typ klíče tento koncový bod nepovoluje (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - konverzace nepatří tomuto botovi
  • 405 invalid_request_error (method_not_allowed) - chybná HTTP metoda na dané URL
  • 429 rate_limit_error - příliš mnoho požadavků (rate_limit_exceeded) nebo příliš mnoho souběžných streamů (concurrent_streams_exceeded)
  • 500 api_error - interní chyba

Související

Operace na úrovni účtu (vytváření botů, aktualizace botů, získávání údajů o využití) naleznete v části Management API.

Prohledat všechny článkyZeptejte se agenta