Referenční přehled Chat API

Veřejné chat API umožňuje programově vést streamované konverzace s botem ChatbotIQ. Běží na stejném endpointu, který pohání vložený widget.

Praktického průvodce s příklady kódu najdete v článku Použití Chat API.

---

Základní URL

https://app.chatbotiq.eu/v1/public

---

Streamovaný chat

Odešlete zprávu a obdržíte streamovanou odpověď přes Server-Sent Events (SSE).

Endpoint

POST /v1/public/chat/stream

Autentizace

Není potřeba žádná. Bot musí být v režimu soukromí Public.

Tělo požadavku

Pole	Typ	Povinné	Popis
bot_id	UUID	Ano	Jedinečný identifikátor bota. Najdete jej v záložce Nasazení v Playgroundu.
message	String	Ano	Zpráva nebo otázka uživatele.
session_id	String	Ano	Anonymní identifikátor relace. Ke sledování relace konverzace použijte libovolný jedinečný řetězec, například UUID.
conversation_id	String	Ne	ID konverzace vrácené v předchozí odpovědi. Uveďte jej, chcete-li pokračovat v existující konverzaci.
recaptcha_token	String	Ne	Token Google reCAPTCHA k ochraně proti botům (pokud je nastavena).
image_data	String	Ne	Data obrázku zakódovaná v Base64 (bez prefixu data:). Jen pro multimodální modely.
image_media_type	String	Ne	MIME typ obrázku: image/jpeg, image/png nebo image/webp. Povinné, pokud uvádíte image_data.

Příklad požadavku

curl -X POST https://app.chatbotiq.eu/v1/public/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your-bot-id",
    "message": "How do I get started?",
    "session_id": "unique-session-id"
  }'

Odpověď

Odpověď je stream Server-Sent Events (SSE). Každá událost je řádek s prefixem data: , za nímž následuje objekt JSON. Každá událost nese rozlišovací pole type.

Typy událostí

type	Tvar	Popis
status	{"type":"status","stage":"retrieving"}	Informace o průběhu (retrieving, poté generating). Pouze informativní.
content	{"type":"content","content":"text"}	Část odpovědi. Spojením polí content sestavíte celou odpověď.
replace	{"type":"replace","content":"full text"}	Odpověď prošla dodatečným filtrem. Zahoďte dosavadní content a nahraďte jej touto hodnotou.
notice	{"type":"notice","code":"rag_unavailable","level":"warning","message_key":"..."}	Varování, které nepřeruší stream (např. zhoršené vyhledávání).
done	{"type":"done","conversation_id":"uuid","assistant_message_id":"uuid","citations":[...]}	Konec streamu. Pole citations se objeví, jen když má bot zapnuté citace zdrojů.
error	{"type":"error","error":"code","message":"..."}	Generování selhalo nebo bylo zablokováno. Časté kódy: content_filtered, service_unavailable, internal_error.

Žádné pole token ani booleovské pole done se nepoužívá. Text odpovědi je vždy v poli content událostí content (a replace); pole conversation_id a citations se objeví jen u závěrečné události done.

Objekt citace

{
  "page_title": "Getting Started",
  "source_url": "https://docs.example.com/start",
  "source_id": "…",
  "score": 0.92,
  "from_web_search": false
}

Pokud má bot odkazy vypnuté (include_links_in_responses = false), vrací se source_url jako prázdný řetězec.

Příklad SSE streamu

data: {"type":"status","stage":"retrieving"}
data: {"type":"status","stage":"generating"}
data: {"type":"content","content":"To"}
data: {"type":"content","content":" get started,"}
data: {"type":"content","content":" you need to..."}
data: {"type":"done","conversation_id":"abc-123","assistant_message_id":"def-456","citations":[{"page_title":"Getting Started","source_url":"https://docs.example.com/start","source_id":"…","score":0.92,"from_web_search":false}]}

Chybové odpovědi

Selhání před otevřením streamu vrací HTTP stavové kódy; selhání po jeho zahájení dorazí jako událost error uvnitř streamu (HTTP status je v tu chvíli už 200).

Status	Důvod
400	Chybějící nebo neplatné pole, případně nedodaný povinný token reCAPTCHA.
403	Bot není veřejný, je neaktivní, doména původu není mezi povolenými, vypršela bezplatná zkušební verze nebo selhalo ověření reCAPTCHA.
404	Bot nenalezen.
429	Překročen limit požadavků (na IP i případné limity na bota).

Nedostatek kreditů pracovního prostoru nevrací 402; projeví se uprostřed streamu jako {"type":"error","error":"service_unavailable"}.

Limity požadavků

Veřejný chat je omezen limity podle IP klienta a podle bota:

• Základní limit (na IP): 15 zpráv za minutu a 120 za hodinu.
• Platí také limit chatu na úrovni pracovního prostoru, navázaný na plán.
• Další limity pro jednotlivé boty nastavíte v Nastavení bota. Ve výchozím stavu jsou vypnuté, a pokud je zapnete, uplatní se vždy ten přísnější.

---

Získání konfigurace widgetu

Načte konfiguraci potřebnou k vykreslení widgetu konkrétního bota.

Endpoint

GET /v1/public/bots/{bot_id}/config

Autentizace

Není vyžadována.

Odpověď

Pole	Typ	Popis
bot_id	UUID	Identifikátor bota.
bot_name	String	Zobrazovaný název bota.
widget_settings	Object	Veškerá nastavení vzhledu widgetu (barvy, umístění a další).
suggested_questions	Array of strings	Předem připravené navržené otázky.
show_suggested_questions	Boolean	Zda se mají navržené otázky zobrazovat.
suggested_questions_count	Integer	Kolik návrhů zobrazit.
welcome_message	String or null	Úvodní uvítací zpráva.
warning_message	String or null	Vlastní upozornění při dosažení limitu požadavků.
recaptcha_site_key	String or null	Site key reCAPTCHA, pokud je reCAPTCHA zapnutá.
include_links	Boolean	Zda odpovědi obsahují odkazy.
language	String	Kód jazyka, ve kterém bot odpovídá.
mcp_url	String or null	Endpoint integrace MCP, pokud je nastavený.
handoff_enabled	Boolean	Zda je dostupné předání člověku.
handoff_trigger	String	Režim spuštění předání: “button”, “auto” nebo “both”.
handoff_offline_message	String or null	Zpráva zobrazená, když není online žádný operátor.
handoff_agent_label	String or null	Zobrazovaný popisek lidského operátora.
handoff_available	Boolean	Zda jsou operátoři právě online.
allow_user_images	Boolean	Zda mohou uživatelé nahrávat obrázky.
contact_form_enabled	Boolean	Zda je zapnutý kontaktní formulář.
contact_form_trigger	String	Režim spuštění kontaktního formuláře.
contact_form_fields	Array or null	Definice polí kontaktního formuláře.
contact_form_success_message	String or null	Zpráva zobrazená po úspěšném odeslání.
contact_form_button_display	String	Kdy zobrazit tlačítko kontaktního formuláře (např. after_response).

---

Získání historie konverzace

Načte historii zpráv existující konverzace.

Endpoint

GET /v1/public/conversations/{conversation_id}/messages?session_id={session_id}

Parametry dotazu

Pole	Povinné	Popis
session_id	Ano	Musí odpovídat relaci, která konverzaci vytvořila (ověření vlastnictví).
after	Ne	Vrátí pouze zprávy vytvořené po zprávě s tímto ID. Hodí se pro pravidelné dotazování.

Autentizace

Není potřeba žádná. session_id musí odpovídat tomu, se kterým byla konverzace vytvořena. Samotný endpoint je omezen na 30 požadavků za minutu na jednu IP.

Odpověď

{
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "How do I get started?",
      "citations": null,
      "feedback": null,
      "image_preview": null,
      "created_at": "2026-03-30T12:00:00Z"
    },
    {
      "id": "uuid",
      "role": "assistant",
      "content": "To get started, you need to...",
      "citations": [
        {
          "page_title": "Getting Started",
          "source_url": "https://docs.example.com/start",
          "source_id": "…",
          "score": 0.92,
          "from_web_search": false
        }
      ],
      "feedback": "positive",
      "image_preview": null,
      "created_at": "2026-03-30T12:00:01Z"
    }
  ],
  "conversation_status": "open"
}

---

Související

• Použití Chat API - praktický průvodce s příklady kódu
• Nastavení bota - konfigurace limitů požadavků a režimu soukromí