← Zpět do aplikace

API & MCP

Ovládejte svého chatbota z vlastního kódu nebo z AI asistentů.

Přehled#

Chatbotty lze používat a spravovat mimo dashboard dvěma způsoby: pomocí REST API pro váš vlastní kód a pomocí konektoru MCP pro AI asistenty, například Claude. Oba pracují vždy s jedním chatbotem a používají stejné API klíče. Začněte Autentizací.

Základy

PoložkaHodnota
Základní URL RESThttps://www.chatbotty.ai/api/v1
URL serveru MCPhttps://www.chatbotty.ai/api/mcp
FormátJSON přes HTTPS
AutentizaceAuthorization: Bearer YOUR_API_KEY
Rozsah klíčeJeden klíč patří právě jednomu chatbotovi; chatbot se v požadavku nikdy neposílá, odvozuje se z klíče

Co použít

  • REST API - píšete kód, který odesílá chatové zprávy nebo spravuje dokumenty, konverzace, tikety a webhook akce. Viz Chatbot a následující sekce s koncovými body.
  • Konektor MCP - připojíte AI asistenta a necháte jej pracovat s chatbotem bez programování. Viz Konektor MCP a Klienti MCP.

Tarify

API klíče, REST API a konektor MCP jsou dostupné ve všech tarifech: Free, Evaluation, Support a Automate. Jednotlivé funkce závisejí na tarifu.

FunkceFreeEvaluationSupportAutomate
Chat, dokumenty, konverzace, analytikaAnoAnoAnoAno
TiketyNeAnoAnoAno
Webhook akceNeAnoNeAno
Import dokumentu z webové URLNeAnoAnoAno

Volání funkce, která není ve vašem tarifu, vrátí 403 FORBIDDEN. Konektor MCP takové nástroje vůbec nenabízí. Změna tarifu se uplatní při dalším požadavku.

Kvóta

  • Do měsíční kvóty zpráv se počítají pouze zprávy odeslané přes chat (REST POST /chat nebo nástroj MCP send_message), přesně jako zprávy z widgetu.
  • Ostatní volání (dokumenty, konverzace, analytika, tikety, webhook akce) kvótu nespotřebovávají.
  • Když je kvóta vyčerpána, chatové volání vrátí 403 QUOTA_EXCEEDED. Zbývající kvótu zkontrolujete pomocí GET /chatbot.
  • Klíče fungují bez ohledu na povolené domény chatbota a i když je chatbot pro widget neaktivní (kromě odesílání chatových zpráv, které neaktivní chatbot odmítne s 404 NOT_FOUND).

Formát odpovědi

Každá odpověď REST používá stejnou obálku. Chyby jsou popsány v části Chyby.

{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }

Autentizace#

Každý požadavek musí nést API klíč chatbota jako Bearer token. Stejný klíč funguje pro REST API i pro konektor MCP.

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot

API klíče

PoložkaHodnota
FormátNáhodný 64znakový hexadecimální řetězec
RozsahJeden chatbot na klíč
LimitAž 50 klíčů na chatbota (počítají se i neaktivní klíče)
UloženíUkládá se pouze hash; celý klíč se zobrazí jednou, hned po vytvoření

S klíči zacházejte jako s hesly: nikdy je nesdílejte a nikdy je nevkládejte do kódu na straně klienta.

Správa klíčů v dashboardu

  1. Otevřete API a MCP v postranním panelu.
  2. Na kartě svého chatbota klikněte na Vytvořit nový API klíč, zadejte název (například „Produkční aplikace“) a klikněte na Vytvořit.
  3. Klíč okamžitě zkopírujte. Znovu jej zobrazit nelze („Zkopírujte tento klíč nyní. Už ho nebudete moci zobrazit.“).

Poté seznam ukazuje název klíče, jeho prvních 12 znaků a Naposledy použito.

AkceÚčinek
DeaktivovatKlíč okamžitě přestane fungovat; Aktivovat jej znovu zapne
SmazatKlíč se trvale odstraní; aplikace, které jej používají, okamžitě přestanou fungovat

Klíče vytvořené připojením AI asistenta jsou označeny MCP konektor. Smazáním takového klíče se asistent odpojí. Opětovné připojení stejného asistenta ke stejnému chatbotovi jeho starý klíč nahradí.

Chyby autentizace

SituaceOdpověď
Chybějící nebo chybně utvořená hlavička401 UNAUTHORIZED "Missing or invalid Authorization header"
Neznámý nebo deaktivovaný klíč401 UNAUTHORIZED "Invalid or inactive API key"

Všechny kódy najdete v části Chyby a limity požadavků v části Limity požadavků.

Limity požadavků#

Limity platí na jeden API klíč a za minutu. Každá třída koncových bodů má vlastní počítadlo, takže množství zápisů nevyčerpá rozpočet pro čtení.

REST API

TřídaKoncové bodyLimit za minutu
ChatPOST /chat60
ČteníVšechny ostatní koncové body GET kromě analytiky (včetně GET /chatbot)120
ZápisKoncové body POST, PATCH, DELETE60
AnalytikaGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Test webhookuPOST /webhooks/{id}/test20

Další limit: POST /documents/upload-url vydá nejvýše 50 URL pro nahrání na chatbota během 2 hodin.

Konektor MCP

Koncový bod MCP povoluje 300 požadavků za minutu na klíč. Každé volání nástroje pak podléhá také limitu REST koncového bodu, který používá, a send_message spotřebovává kvótu zpráv.

Když limit překročíte

API vrátí 429 RATE_LIMITED se zprávou například "Rate limit exceeded. Maximum 60 requests per minute per API key." Počkejte na další minutu a zkuste znovu, ideálně s narůstající prodlevou.

Limity požadavků jsou oddělené od měsíční kvóty zpráv; viz Přehled a Chyby.

Chatbot#

Zjistěte, kterému chatbotovi váš API klíč patří, a před zahájením práce zkontrolujte jeho tarif a kvótu.

GET /chatbot

PoložkaHodnota
Metoda a cestaGET https://www.chatbotty.ai/api/v1/chatbot
ParametryŽádné
Limit požadavkůTřída čtení (viz Limity požadavků)
KvótaNespotřebovává se
Nástroj MCPget_chatbot_info

Odpověď

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "CycleZone",
    "description": "Customer care chatbot",
    "is_active": true,
    "language": "auto",
    "timezone": "America/New_York",
    "handoff_contact": "info@example.com",
    "created_at": "2026-01-01T10:00:00.000Z",
    "dashboard_url": "https://www.chatbotty.ai/dashboard/chatbots/uuid",
    "plan": "Automate",
    "message_quota": { "used": 622, "monthly_limit": 9000, "extra_messages": 0 },
    "features": { "tickets": true, "upload_from_url": true, "webhook_actions": true },
    "knowledge_base": {
      "documents_total": 1,
      "documents_by_status": { "pending": 0, "processing": 0, "completed": 1, "failed": 0 },
      "last_updated_at": "2026-01-01T10:00:00.000Z"
    }
  }
}

Poznámky

  • plan a message_quota patří vlastníkovi účtu; kvótu sdílejí všichni chatboti účtu.
  • features ukazuje, které funkce závislé na tarifu může tento klíč používat.
  • handoff_contact je kontakt, který chatbot uvede, když odpověď nezná (zde jen pro čtení; null, pokud není nastaven).
  • last_updated_at je čas nejnovějšího nahraného dokumentu.

Chat#

Odešlete chatbotovi zprávu a získejte jeho odpověď, přesně jako návštěvník ve widgetu.

POST /chat

PoložkaHodnota
Metoda a cestaPOST https://www.chatbotty.ai/api/v1/chat
Limit požadavkůTřída chat: 60 za minutu
KvótaJedna zpráva na volání; po překročení kvóty volání vrátí 403 QUOTA_EXCEEDED
Nástroj MCPsend_message

Tělo požadavku

PolePovinnéPopis
messageAnoOtázka návštěvníka (neprázdný text)
conversation_idNePokračuje ve stávající konverzaci; pro zahájení nové jej vynechte
optionsNeVolitelný objekt; při běžném použití není potřeba

Pokud conversation_id neexistuje nebo patří jinému chatbotovi, volání vrátí 400 CONVERSATION_NOT_FOUND. Chatbot, který není aktivní, vrátí 404 NOT_FOUND.

Odpověď

{
  "success": true,
  "data": {
    "message": "Our warranty is two years.",
    "conversation_id": "uuid",
    "sources": [{ "content": "...", "similarity": 0.87 }],
    "metadata": {
      "tokensUsed": 312,
      "cached": false,
      "responseTime": 1240,
      "searchResults": 3,
      "quality": "answered",
      "confidence": 0.87,
      "tools_executed": [{ "name": "get_weather", "ok": true }]
    }
  }
}

Kontext konverzace

První volání vytvoří konverzaci a vrátí její conversation_id. Toto id posílejte s každou další zprávou, aby se zachoval kontext. Konverzace vytvořené přes API se v dashboardu zobrazují se zdrojem api.

tools_executed

metadata.tools_executed uvádí nástroje, které chatbot při odpovídání zavolal (webhook akce, vytvoření tiketu podpory). Každá položka má name, ok a při selhání krátký code, například webhook_timeout, webhook_redirect, webhook_blocked nebo invalid_args. Prázdný seznam znamená, že nebyl zavolán žádný nástroj. Použijte jej k ověření, že webhook akce skutečně proběhla.

Dokumenty#

Spravujte znalostní bázi chatbota: nahrávejte, čtěte, upravujte, vypisujte a mažte dokumenty. Tato volání nespotřebovávají kvótu zpráv.

Koncové body

Metoda a cestaPopisKlíčové parametryNástroj MCP
GET /documentsVýpis dokumentůlimit (výchozí 20, max 100), offset, statuslist_documents
POST /documentsNahrání dokumentu; vrací 202Viz nížeupload_document
POST /documents/upload-urlZískání podepsané URL pro velký nebo lokální souborfilenamecreate_upload_url
GET /documents/{id}Stav a podrobnosti jednoho dokumentu-get_document
DELETE /documents/{id}Smazání dokumentu-delete_document
GET /documents/{id}/contentČtení textu po stránkáchoffset, limit (výchozí 20000, max 50000)read_document
PATCH /documents/{id}/contentÚprava dokumentu .md nebo .txtedits, append, expected_hashedit_document, append_to_document

Limity: volání GET používají limit čtení, ostatní limit zápisu (viz Limity požadavků).

Nahrání

Povolené typy: .pdf, .docx, .txt, .md, až 10 MB. Odešlete buď multipart/form-data, nebo JSON.

PolePopis
fileSoubor (pouze multipart)
contentText dokumentu .md nebo .txt (JSON; vyžaduje se filename)
content_base64Binární soubor v base64 (JSON; použijte do asi 3 MB)
urlVeřejná URL souboru, který server stáhne (JSON; pouze tarify s importem z webové URL)
upload_idId z POST /documents/upload-url po nahrání souboru
filenameNázev souboru s příponou
descriptionVolitelný popis
replace_existingVýchozí true: soubor se stejným názvem se nahradí novou verzí

V JSON odešlete právě jedno z content, content_base64, url, upload_id.

{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }

Velké nebo lokální soubory

  1. POST /documents/upload-url s { "filename": "price-list.pdf" }. Odpověď obsahuje upload_id, upload_url a hlavičky; URL platí 2 hodiny a funguje jednou.
  2. Odešlete surový soubor pomocí PUT na upload_url.
  3. POST /documents s { "upload_id": "...", "filename": "price-list.pdf" }.

Zpracování a stav

Zpracování je asynchronní. Stav prochází od pending přes processing do completed, nebo končí jako failed s error_message. Selhaný dokument zůstává v seznamu; smažte jej nebo nahrajte znovu. Dotazujte GET /documents/{id}, dokud není completed.

Úprava a nahrazení

  • PATCH /documents/{id}/content posílá jen změnu: edits (seznam old_text a new_text, každý old_text se musí vyskytovat právě jednou, až 100) a/nebo append (text, volitelně after_heading).
  • expected_hash (z GET .../content) chrání před přepsáním novější verze (409 CONFLICT).
  • Upravovat lze pouze dokumenty UTF-8 .md a .txt (jinak 400 NOT_EDITABLE).
  • Každá úprava nebo nahrazení vytvoří nové document_id; stará verze odpovídá, dokud není nová completed.
  • Druhá změna, zatímco se dokument stále zpracovává, vrátí 409 REPLACE_IN_PROGRESS.

Konverzace#

Čtěte historii konverzací chatbota, včetně konverzací vytvořených ve widgetu. Tato volání jsou jen pro čtení a nespotřebovávají kvótu zpráv.

Koncové body

Metoda a cestaPopisKlíčové parametryNástroj MCP
GET /conversationsVýpis konverzacíViz níželist_conversations
GET /conversations/{id}Jedna konverzace-get_conversation
GET /conversations/{id}/messagesZprávy v chronologickém pořadílimit (výchozí 50, max 200), offsetget_conversation_messages

Všechna tři používají limit čtení 120 požadavků za minutu (viz Limity požadavků). Konverzace jiného chatbota vrátí 404 NOT_FOUND.

Filtry výpisu

ParametrPopis
limit, offsetStránkování (výchozí 20, max 100)
statusactive, completed nebo ticket_created
sourcewidget nebo api
from, toData ve formátu ISO 8601; filtrují podle začátku konverzace
qualityKonverzace s alespoň jednou otázkou tohoto druhu: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qFulltextové hledání v textu zpráv (2 až 200 znaků)

Odpověď

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "uuid",
        "started_at": "2026-01-01T10:00:00Z",
        "last_activity_at": "2026-01-01T10:15:00Z",
        "message_count": 5,
        "status": "active",
        "source": "widget",
        "email": "visitor@example.com",
        "phone": null
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "total": 42 }
  }
}

V tarifech s tikety detail konverzace obsahuje také tickets v ní vytvořené. Zprávy mají id, role (user nebo assistant), content a created_at.

Tip

Chcete-li najít otázky, na které chatbot nedokázal odpovědět, použijte GET /analytics/top-queries?quality=not_answered (viz Analytika) a související konverzace otevřete přes conversation_ids.

Analytika#

Agregované statistiky chatbota. Analytika je dostupná ve všech tarifech, včetně Free. Tato volání nespotřebovávají kvótu zpráv.

Koncové body

Metoda a cestaPopisNástroj MCP
GET /analytics/summarySoučty za obdobíget_analytics_summary
GET /analytics/timeseriesPočty za hodinu, den nebo týdenget_analytics_timeseries
GET /analytics/top-queriesNejčastější otázkyget_top_queries, list_knowledge_gaps

Všechna tři používají limit analytiky 60 požadavků za minutu (viz Limity požadavků).

Společné parametry

ParametrPopis
periodtoday (výchozí), week, month nebo quarter, vyhodnocováno v časovém pásmu chatbota
from, toData ve formátu ISO 8601; nahrazují period; rozsah je nejvýše 366 dní
sourcewidget nebo api

Další parametry

Koncový bodParametrPopis
timeseriesgranularityauto (výchozí), hour, day nebo week; hour s quarter je odmítnuto
top-querieslimit, offsetStránkování (výchozí 20, max 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Odpověď souhrnu

{
  "period": "week",
  "total_queries": 7,
  "answered_queries": 5,
  "not_answered_queries": 1,
  "conversation_queries": 1,
  "off_topic_queries": 0,
  "ticket_created_queries": 0,
  "tool_call_queries": 0,
  "success_rate": 83.3,
  "widget_queries": 6,
  "api_queries": 1
}

success_rate je počet zodpovězených dělený součtem zodpovězených a nezodpovězených, v procentech.

Nezodpovězené otázky

GET /analytics/top-queries?quality=not_answered&period=month vrací otázky, na které chatbot nedokázal odpovědět, od nejčastější. Každá položka má content, count, last_asked a až 5 conversation_ids, které můžete otevřít přes konverzace. Doplňte chybějící fakta do znalostní báze a výsledek ověřte pomocí chatu.

Tikety#

Čtěte tikety podpory, měňte jejich stav a přidávejte interní poznámky. Tikety jsou dostupné v tarifech Evaluation, Support a Automate; Free vrací 403 FORBIDDEN. Tikety nelze vytvářet přes API: vytváří je chatbot během konverzace.

Koncové body

Metoda a cestaPopisKlíčové parametryNástroj MCP
GET /ticketsVýpis tiketů, nejnovější prvnílimit (výchozí 20, max 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Jeden tiket-get_ticket
PATCH /tickets/{id}Změna stavustatus v těleupdate_ticket_status
GET /tickets/{id}/notesInterní poznámky, nejstarší první-list_ticket_notes
POST /tickets/{id}/notesPřidání poznámky; vrací 201content v těleadd_ticket_note

Volání GET používají limit čtení (120 za minutu), PATCH a POST limit zápisu (60 za minutu); viz Limity požadavků.

Hodnoty

PoložkaHodnota
Stavopen, in_progress, resolved, closed
PoznámkaNeprázdný text, až 5000 znaků

Neplatný stav vrátí 400 INVALID_REQUEST. Tiket jiného chatbota vrátí 404 NOT_FOUND.

Objekt tiketu

{
  "id": "uuid",
  "ticket_number": "TKT-000015",
  "conversation_id": "uuid",
  "email": "visitor@example.com",
  "phone": null,
  "summary": "The visitor asked to speak with a person.",
  "status": "open",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:00:00Z"
}

Příklad

curl -X PATCH https://www.chatbotty.ai/api/v1/tickets/TICKET_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Webhook akce#

Spravujte webhook akce chatbota: externí API nebo automatizační webhooky (například n8n), které chatbot při odpovídání volá jako nástroje. Dostupné v tarifu Automate (10 webhooků a 10 nástrojů na chatbota) a ve zkušební době Evaluation (5 webhooků a 5 nástrojů na chatbota). Ostatní tarify dostanou 403 FORBIDDEN; překročení limitů vrací 403 LIMIT_EXCEEDED. Volání nespotřebovávají kvótu zpráv.

Koncové body

Metoda a cestaPopisNástroj MCP
GET /webhooksVýpis webhooků a využití vašich limitůlist_webhook_actions
POST /webhooksVytvoření webhooku, volitelně s nástroji; vrací 201create_webhook_action
GET /webhooks/{id}Jeden webhook s jeho nástrojiget_webhook_action
PATCH /webhooks/{id}Změna webhookuupdate_webhook_action
DELETE /webhooks/{id}Smazání webhooku s jeho nástrojidelete_webhook_action
POST /webhooks/{id}/toolsPřidání nástroje; vrací 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Změna nástrojeupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Smazání nástrojedelete_webhook_tool
POST /webhooks/{id}/testZavolání webhooku stejně jako chatbottest_webhook_action

Čtení používá limit čtení (120 za minutu), změny limit zápisu (60) a test má vlastní limit 20 za minutu; viz Limity požadavků. Nástroj MCP get_webhook_guide vrací krátkého průvodce pro AI asistenty.

Pole webhooku

PolePopis
namePovinné, až 100 znaků
webhook_urlPovinné, veřejná adresa HTTPS
http_methodPOST (výchozí) nebo GET
send_metadataVýchozí true: volání nese také tool_name, args a metadata (chatbot_id, conversation_id, timestamp); false odesílá jen argumenty
timeout_ms1000 až 30000, výchozí 10000
headersAž 20 vlastních hlaviček
secret_queryAž 10 tajných parametrů dotazu, například API klíč
toolsNástroje, které chatbot smí volat (viz níže)

Pole nástroje

PolePopis
nameMalá písmena, číslice a podtržítka, začíná písmenem, až 64 znaků, jedinečné na chatbota; create_support_ticket je vyhrazeno
descriptionAž 500 znaků; říká chatbotovi, kdy nástroj použít
parametersAž 10 položek s name, type (string, number, boolean), description (až 200 znaků), required

Pravidla

  • Hodnoty headers a secret_query se nikdy nevracejí, jen jejich názvy. Klíč nalezený ve webhook_url se automaticky přesune do secret_query a oznámí se ve warnings.
  • Změna koncového bodu webhooku vyžaduje znovu odeslat všechny uložené klíče headers a secret_query, aby se tajné údaje nemohly nepozorovaně přesunout na jiný server.
  • Chatbot provede na jednu odpověď jedno kolo volání nástrojů. Odpověď se ořízne na 10 KB, přesměrování se nesledují a interní adresy jsou odmítnuty.

Test

POST /webhooks/{id}/test s volitelným tělem { "tool_name": "get_weather", "arguments": { "q": "Prague" } } vrací ok, status, response_time_ms, body_preview (prvních 2 KB), truncated a warnings. Po testu položte chatbotovi odpovídající otázku přes chat a zkontrolujte tools_executed.

Chyby#

Neúspěšná volání REST vracejí stav HTTP jiný než 2xx a tuto obálku:

{
  "success": false,
  "error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
  "timestamp": "2026-01-01T10:00:00.000Z"
}

details je přítomno jen u některých chyb. Chyby zpracovávejte podle code; zprávy se mohou měnit.

Chybové kódy

KódHTTPVýznam
UNAUTHORIZED401Chybějící, neplatný nebo deaktivovaný API klíč
QUOTA_EXCEEDED403Měsíční kvóta zpráv vyčerpána (details.quota_info)
FORBIDDEN403Funkce není ve vašem tarifu
LIMIT_EXCEEDED403Dosažen limit tarifu pro webhooky nebo nástroje (details.resource, used, max)
INVALID_REQUEST400Neplatné tělo nebo parametry
INVALID_URL400URL webhooku je neplatná, není HTTPS nebo není veřejná
INVALID_FILE400V nahrání chybí soubor
FILE_TOO_LARGE400Soubor nad 10 MB
UNSUPPORTED_FILE_TYPE400Přijímají se jen .pdf, .docx, .txt, .md
CONVERSATION_NOT_FOUND400conversation_id neexistuje nebo patří jinému chatbotovi
EDIT_FAILED400Nahrazovaný text nenalezen, nebo nalezen vícekrát
NOT_EDITABLE400Upravovat lze pouze dokumenty UTF-8 .md a .txt
NOT_FOUND404Dokument, tiket, webhook, nástroj nebo nahrání nenalezeno, nebo neaktivní chatbot
DUPLICATE_FILENAME409Dokument s tímto názvem existuje (details.existing_document_id)
DUPLICATE_CONTENT409Stejný obsah je již indexován
REPLACE_IN_PROGRESS409Dokument se nahrazuje nebo zpracovává; počkejte, až bude completed
CONFLICT409Název nástroje již existuje, nebo se dokument od vašeho čtení změnil
STORAGE_LIMIT_EXCEEDED413Překročen limit úložiště chatbota
RATE_LIMITED429Příliš mnoho požadavků; viz Limity požadavků
GONE_USE_V1410Starý koncový bod /api/chat byl odstraněn; použijte /api/v1/chat
INTERNAL_ERROR500Neočekávaná chyba serveru

Chyby MCP

Koncový bod MCP odpovídá chybami JSON-RPC: 401 pro chybějící nebo neplatný token, 429 pro příliš mnoho požadavků a 403, když tarif nemá MCP. Když nástroj selže, výsledek je označen jako chyba a obsahuje kód API, například Chatbotty API error [NOT_FOUND] (HTTP 404). Viz Konektor MCP.

Podpora

Pokud chyba přetrvává, napište na support@chatbotty.ai a uveďte kód, čas a koncový bod.

Konektor MCP#

Konektor MCP umožňuje AI asistentovi, například Claude, n8n nebo Cursoru, pracovat s vaším chatbotem: chatovat s ním, spravovat jeho znalostní bázi, nastavovat webhook akce a číst konverzace, analytiku a tikety. Jeden konektor patří jednomu chatbotovi; chcete-li použít dalšího chatbota, přidejte další konektor.

Připojení

PoložkaHodnota
URL serveruhttps://www.chatbotty.ai/api/mcp
PřenosStreamable HTTP přes POST
TarifyVšechny tarify; kontroluje se při každém požadavku
Limit300 požadavků za minutu na klíč (viz Limity požadavků)

Přihlášení nebo klíč

MetodaPoužívajíJak
Přihlášení (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeKlient otevře stránku Chatbotty; přihlásíte se, vyberete chatbota a kliknete na Povolit. Klíč se vytvoří automaticky
API klíčn8n, Cursor, VS Code, další klientiOdešlete hlavičku Authorization: Bearer YOUR_API_KEY (Autentizace)

Klíč vytvořený přihlášením je v API a MCP označen MCP konektor. Chcete-li asistenta odpojit, smažte jej tam. Tikety a nástroje webhooků se zobrazí jen tehdy, pokud je váš tarif obsahuje. Postup nastavení je v části Klienti MCP.

Nástroje

OblastNástroje
Chatbot a chatget_chatbot_info, send_message
Dokumentylist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Mezery ve znalostechlist_knowledge_gaps
Konverzacelist_conversations, get_conversation, get_conversation_messages
Analytikaget_analytics_summary, get_analytics_timeseries, get_top_queries
Tikety (tarify s tikety)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Webhook akce (tarify s webhook akcemi)get_webhook_guide, list_webhook_actions, get_webhook_action, create_webhook_action, update_webhook_action, test_webhook_action, delete_webhook_action, add_webhook_tool, update_webhook_tool, delete_webhook_tool

Každý nástroj funguje jako odpovídající koncový bod REST popsaný ve výše uvedených částech a má stejné limity a chyby.

Dobré vědět

  • send_message komunikuje s chatbotem jako návštěvník a spotřebovává měsíční kvótu zpráv. test_webhook_action ne.
  • list_knowledge_gaps vypisuje otázky, na které chatbot nedokázal odpovědět, a vyžaduje období; použijte jej k nalezení toho, co doplnit do znalostní báze.
  • Klient může popisy nástrojů ukládat do cache. Pokud nástroje vypadají zastarale, konektor odeberte a přidejte znovu.

Klienti MCP#

Jak připojit běžné klienty k https://www.chatbotty.ai/api/mcp. U klientů, kteří posílají klíč, jej nejprve vytvořte podle části Autentizace. Souvislosti: Konektor MCP.

Claude (claude.ai, Claude Desktop, mobil)

  1. Otevřete Settings, poté Connectors a přidejte vlastní konektor.
  2. Vložte URL serveru a klikněte na Connect.
  3. Přihlaste se do Chatbotty, vyberte chatbota a klikněte na Povolit.

API klíč není potřeba. Konektor pak funguje i v mobilní aplikaci Claude.

Claude Code

Přihlaste se přes prohlížeč:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp

Nebo použijte API klíč:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Když přihlašovací stránka varuje, že aplikace běží na vašem vlastním počítači, povolte přístup jen tehdy, pokud jste připojení zahájili sami.

n8n

  1. Přidejte uzel MCP Client Tool.
  2. Endpoint: URL serveru.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth s vaším API klíčem.

Cursor, VS Code a další klienti

Přidejte vzdálený server MCP s URL serveru a hlavičkou Authorization: Bearer YOUR_API_KEY. Například v Cursoru:

{
  "mcpServers": {
    "chatbotty": {
      "url": "https://www.chatbotty.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Řešení potíží

ProblémCo zkontrolovat
401Klíč je chybný, deaktivovaný nebo smazaný
Chybí tikety nebo nástroje webhookůVáš tarif je neobsahuje
Ruční klient dostává 406Klient musí posílat Accept: application/json, text/event-stream

Příklady#

Příklady ke zkopírování pro nejběžnější úlohy. Nahraďte YOUR_API_KEY klíčem z API a MCP a https://www.chatbotty.ai základní URL. Viz Autentizace.

Kontrola chatbota a kvóty

curl https://www.chatbotty.ai/api/v1/chatbot \
  -H "Authorization: Bearer YOUR_API_KEY"

Položení otázky a pokračování konverzace

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

Vezměte conversation_id z odpovědi a pošlete jej s další zprávou:

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "And on Sunday?", "conversation_id": "CONVERSATION_ID"}'

Nahrání dokumentu

curl -X POST https://www.chatbotty.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./faq.md"

Poté kontrolujte stav, dokud není completed:

curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Nalezení nezodpovězených otázek

curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Výpis konverzací obsahujících slovo

curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Zpracování chyb

{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 60 requests per minute per API key." }, "timestamp": "2026-01-01T10:00:00.000Z" }

Větvete podle error.code a viz Chyby. Limity najdete v části Limity požadavků. Dotazy: support@chatbotty.ai.