Jak používat Chat API

Chat API umožňuje programově posílat zprávy botovi a přijímat streamované odpovědi. Je to stejné API, které pohání vložený widget, takže si na něm postavíte vlastní integrace, mobilní aplikace nebo backendové služby.

---

Předpoklady

• Váš bot musí být nastaven na režim soukromí Public.
• Potřebujete své bot ID (najdete ho v záložce Nasazení v Playgroundu).

---

Odeslání zprávy (curl)

curl -N -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": "my-session-123"
  }'

Přepínač -N vypne bufferování výstupu curlu, takže streamovanou odpověď uvidíte v reálném čase.

---

Pochopení streamu odpovědi

Odpověď je stream Server-Sent Events (SSE). Každý řádek má prefix data: následovaný objektem JSON. Každá událost má pole type, které vám říká, jak ji zpracovat:

type	Payload	Co dělat
status	{"type":"status","stage":"retrieving"} poté "generating"	Nápovědy o průběhu. Lze bezpečně ignorovat, nebo zobrazit indikátor “přemýšlím…”.
content	{"type":"content","content":"some text"}	Část odpovědi. Zřetězte pole content pro sestavení úplné odpovědi.
replace	{"type":"replace","content":"full text"}	Odpověď byla dodatečně filtrována. Zahoďte to, co jste dosud zobrazili, a nahraďte to tímto polem content.
notice	{"type":"notice","code":"rag_unavailable",...}	Nefatální varování (např. vyhledávání ve znalostech je dočasně omezené). Zobrazení je volitelné.
done	{"type":"done","conversation_id":"...","assistant_message_id":"...","citations":[...]}	Konec streamu. Uložte conversation_id pro pokračování konverzace. citations je přítomno pouze tehdy, má-li bot povolené citace zdrojů.
error	{"type":"error","error":"content_filtered","message":"..."}	Generování selhalo nebo byla odpověď zablokována. Zobrazte message.

Text odpovědi přichází v poli content událostí typu content: žádné pole token neexistuje a done je typ události, nikoli booleovský příznak. conversation_id a citations se objevují pouze v závěrečné události done.

Objekt citace vypadá takto:

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

---

Odeslání zprávy (JavaScript)

async function chat(botId, message, sessionId, conversationId) {
  const response = await fetch('https://app.chatbotiq.eu/v1/public/chat/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      bot_id: botId,
      message: message,
      session_id: sessionId,
      conversation_id: conversationId
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let fullResponse = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop(); // keep any incomplete trailing line for the next read

    for (const line of lines) {
      if (!line.startsWith('data: ')) continue;
      const event = JSON.parse(line.slice(6));

      switch (event.type) {
        case 'content': // a chunk of the answer
          fullResponse += event.content;
          process.stdout.write(event.content);
          break;
        case 'replace': // post-filtered answer - replaces everything shown so far
          fullResponse = event.content;
          break;
        case 'done': // end of stream
          console.log('\nConversation ID:', event.conversation_id);
          if (event.citations) console.log('Citations:', event.citations);
          break;
        case 'error':
          console.error('\nError:', event.message);
          break;
        // 'status' and 'notice' events can be ignored
      }
    }
  }

  return fullResponse;
}

---

Odeslání zprávy (Python)

import requests
import json

def chat(bot_id, message, session_id, conversation_id=None):
    response = requests.post(
        'https://app.chatbotiq.eu/v1/public/chat/stream',
        json={
            'bot_id': bot_id,
            'message': message,
            'session_id': session_id,
            'conversation_id': conversation_id,
        },
        stream=True
    )

    full_response = ''
    for line in response.iter_lines():
        if not line or not line.startswith(b'data: '):
            continue
        event = json.loads(line[6:])
        etype = event.get('type')

        if etype == 'content':  # a chunk of the answer
            full_response += event['content']
            print(event['content'], end='', flush=True)
        elif etype == 'replace':  # post-filtered answer - replaces what came before
            full_response = event['content']
        elif etype == 'done':  # end of stream
            print(f"\nConversation ID: {event['conversation_id']}")
            if event.get('citations'):
                print(f"\nCitations: {event['citations']}")
            break
        elif etype == 'error':
            print(f"\nError: {event.get('message')}")
            break
        # 'status' and 'notice' events can be ignored

    return full_response

---

Pokračování konverzace

Chcete-li poslat navazující zprávu, přidejte conversation_id z první odpovědi:

curl -N -X POST https://app.chatbotiq.eu/v1/public/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "YOUR-BOT-ID",
    "message": "Tell me more about that",
    "session_id": "my-session-123",
    "conversation_id": "CONVERSATION-ID-FROM-FIRST-RESPONSE"
  }'

---

Zpracování chyb

Existují dva druhy selhání: HTTP chyby vrácené před zahájením streamu a události error doručené uvnitř streamu poté, co začal (HTTP status je v tu chvíli již 200).

HTTP chyby (před streamováním)

Status	Význam	Co dělat
400	Chybějící/neplatné pole nebo nebyl poskytnut požadovaný reCAPTCHA token	Zkontrolujte tělo požadavku.
403	Bot není veřejný, bot je neaktivní, původ požadavku není v povolených doménách bota, vypršela bezplatná zkušební verze, nebo reCAPTCHA selhala	Zkontrolujte režim soukromí bota, jeho aktivní stav a povolené domény.
404	Bot nenalezen	Zkontrolujte bot_id.
429	Překročen limit rychlosti	Počkejte a zkuste to znovu. Zkontrolujte nastavení limitu rychlosti bota.

reCAPTCHA: pokud je nasazení nakonfigurováno s reCAPTCHA, je recaptcha_token povinný: jeho vynechání vrací 400 a neplatný token vrací 403.

Chyby ve streamu (po zahájení streamování)

Jakmile je stream otevřen, selhání přicházejí jako SSE událost error, nikoli jako HTTP status:

data: {"type":"error","error":"content_filtered","message":"..."}
data: {"type":"error","error":"service_unavailable","message":"Service temporarily unavailable"}

service_unavailable pokrývá dočasné potíže backendu, včetně vyčerpání kreditů pracovního prostoru (tento endpoint status 402 nevrací). content_filtered znamená, že odpověď zablokovaly bezpečnostní nebo ukotvovací filtry.

---

Související

• Referenční příručka Chat API: kompletní dokumentace endpointu
• Referenční příručka nastavení bota: limity rychlosti a nastavení soukromí