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 kartu API v horní části stránky bota (Select Bot > API (Vybrat bota > API)).

Karta Bot Talk API

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

Karta API se zvýrazněným tlačítkem Create API Key

Počítadlo vedle tlačítka zobrazuje, 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 fragment kódu curl Quick Start (Rychlý start) vám poskytne ukázku připravenou k okamžitému spuštění.

  1. V dialogovém okně Create API Key pojmenujte klíč, volitelně nastavte seznam povolených IP adres a limit frekvence požadavků, vyberte oprávnění, která má mít, a poté klikněte na Create (Vytvořit).

Dialogové okno Create API Key

  1. Zkopírujte celý klíč z dialogového okna s potvrzením úspěchu. V nezašifrovaném textu se zobrazí pouze jednou.

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

Base 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

POST /v1/chat

Odešle zprávu botovi a obdrží kompletní odpověď v jediné odpovědi JSON.

Tělo požadavku

{
  "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. Vynechejte pro novou konverzaci; použijte hodnotu, kterou server vrátil dříve, chcete-li navázat na existující.
  • metadata - volitelný objekt: {source, userName, userEmail, userPhone}. Hodnota userEmail se také používá k odvození interního ID klienta.

Tělo odpovědi (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 je vždy "assistant"; message.content je kompletní odpověď.
  • model je ID modelu, na kterém bot při tomto volání běžel.
  • usage.creditsUsed započítává zprávu uživatele + odpověď bota (obvykle 2) a navíc jeden extra kredit za každé provedené volání nástroje.
  • actions uvádí spuštění nástrojů, která proběhla během tohoto kola. V současnosti jsou emitovány pouze položky function_call (s hodnotami type, name, status: "completed").

POST /v1/chat/stream

Streamovací varianta /v1/chat. Vrací Content-Type: text/event-stream se Server-Sent Events (SSE).

Tělo požadavku

Stejná struktura jako POST /v1/chat. Příznak stream v těle není vyžadován - SSE spouští samotné použití této cesty.

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

  • message.delta - fragment obsahu { "content": "..." }. Několik z nich se postupně streamuje podle toho, jak přicházejí tokeny.
  • action - provedení nástroje { "type", "name", "status": "executing" }. Emituje se, když bot vyvolá volání funkce.
  • message.done - závěrečná událost s conversationId, model, usage a (pokud existuje) seznamem dokončených akcí actions.
  • error - odesílá se, pokud generování selže; stream se poté ukončí.

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

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

  • limit - 1-100, výchozí hodnota 20. Hodnoty mimo rozsah jsou automaticky omezeny na mezní hodnotu.
  • cursor - neprůhledná hodnota vrácená v nextCursor na předchozí stránce. Pro první stránku vynechejte.

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ácen na 100 znaků s příponou ....
  • nextCursor je na poslední stránce null; předejte jej jako parametr cursor k načtení další stránky.

GET /v1/conversations/{conversation_id}

Úplná historie konverzace.

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í systémové zprávy (system) a zprávy nástrojů jsou odfiltrovány. Pokud konverzace nepatří botovi přiřazenému k vašemu klíči, vrátí se 404 not_found_error.

Chcete-li zkontrolovat konfiguraci 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 strukturu:

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

Běžné stavové kódy HTTP:

  • 400 invalid_request_error - neplatný vstup (kódy: invalid_parameter, 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čerpání kreditů pro zprávy
  • 403 permission_error - blokovaná IP adresa (ip_blocked), IP adresa není na seznamu povolených adres daného 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) - nesprávná metoda HTTP na dané adrese 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