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žka | Hodnota |
|---|---|
| Základní URL REST | https://www.chatbotty.ai/api/v1 |
| URL serveru MCP | https://www.chatbotty.ai/api/mcp |
| Formát | JSON přes HTTPS |
| Autentizace | Authorization: Bearer YOUR_API_KEY |
| Rozsah klíče | Jeden 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.
| Funkce | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, dokumenty, konverzace, analytika | Ano | Ano | Ano | Ano |
| Tikety | Ne | Ano | Ano | Ano |
| Webhook akce | Ne | Ano | Ne | Ano |
| Import dokumentu z webové URL | Ne | Ano | Ano | Ano |
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 /chatnebo nástroj MCPsend_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žka | Hodnota |
|---|---|
| Formát | Náhodný 64znakový hexadecimální řetězec |
| Rozsah | Jeden chatbot na klíč |
| Limit | Až 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
- Otevřete API a MCP v postranním panelu.
- 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.
- 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 |
|---|---|
| Deaktivovat | Klíč okamžitě přestane fungovat; Aktivovat jej znovu zapne |
| Smazat | Klíč 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
| Situace | Odpověď |
|---|---|
| Chybějící nebo chybně utvořená hlavička | 401 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řída | Koncové body | Limit za minutu |
|---|---|---|
| Chat | POST /chat | 60 |
| Čtení | Všechny ostatní koncové body GET kromě analytiky (včetně GET /chatbot) | 120 |
| Zápis | Koncové body POST, PATCH, DELETE | 60 |
| Analytika | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Test webhooku | POST /webhooks/{id}/test | 20 |
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žka | Hodnota |
|---|---|
| Metoda a cesta | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parametry | Žádné |
| Limit požadavků | Třída čtení (viz Limity požadavků) |
| Kvóta | Nespotřebovává se |
| Nástroj MCP | get_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
planamessage_quotapatří vlastníkovi účtu; kvótu sdílejí všichni chatboti účtu.featuresukazuje, které funkce závislé na tarifu může tento klíč používat.handoff_contactje kontakt, který chatbot uvede, když odpověď nezná (zde jen pro čtení;null, pokud není nastaven).last_updated_atje č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žka | Hodnota |
|---|---|
| Metoda a cesta | POST https://www.chatbotty.ai/api/v1/chat |
| Limit požadavků | Třída chat: 60 za minutu |
| Kvóta | Jedna zpráva na volání; po překročení kvóty volání vrátí 403 QUOTA_EXCEEDED |
| Nástroj MCP | send_message |
Tělo požadavku
| Pole | Povinné | Popis |
|---|---|---|
message | Ano | Otázka návštěvníka (neprázdný text) |
conversation_id | Ne | Pokračuje ve stávající konverzaci; pro zahájení nové jej vynechte |
options | Ne | Volitelný 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 cesta | Popis | Klíčové parametry | Nástroj MCP |
|---|---|---|---|
GET /documents | Výpis dokumentů | limit (výchozí 20, max 100), offset, status | list_documents |
POST /documents | Nahrání dokumentu; vrací 202 | Viz níže | upload_document |
POST /documents/upload-url | Získání podepsané URL pro velký nebo lokální soubor | filename | create_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ách | offset, limit (výchozí 20000, max 50000) | read_document |
PATCH /documents/{id}/content | Úprava dokumentu .md nebo .txt | edits, append, expected_hash | edit_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.
| Pole | Popis |
|---|---|
file | Soubor (pouze multipart) |
content | Text dokumentu .md nebo .txt (JSON; vyžaduje se filename) |
content_base64 | Binární soubor v base64 (JSON; použijte do asi 3 MB) |
url | Veřejná URL souboru, který server stáhne (JSON; pouze tarify s importem z webové URL) |
upload_id | Id z POST /documents/upload-url po nahrání souboru |
filename | Název souboru s příponou |
description | Volitelný popis |
replace_existing | Vý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
POST /documents/upload-urls{ "filename": "price-list.pdf" }. Odpověď obsahujeupload_id,upload_urla hlavičky; URL platí 2 hodiny a funguje jednou.- Odešlete surový soubor pomocí
PUTnaupload_url. POST /documentss{ "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}/contentposílá jen změnu:edits(seznamold_textanew_text, každýold_textse musí vyskytovat právě jednou, až 100) a/neboappend(text, volitelněafter_heading).expected_hash(zGET .../content) chrání před přepsáním novější verze (409 CONFLICT).- Upravovat lze pouze dokumenty UTF-8
.mda.txt(jinak400 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 cesta | Popis | Klíčové parametry | Nástroj MCP |
|---|---|---|---|
GET /conversations | Výpis konverzací | Viz níže | list_conversations |
GET /conversations/{id} | Jedna konverzace | - | get_conversation |
GET /conversations/{id}/messages | Zprávy v chronologickém pořadí | limit (výchozí 50, max 200), offset | get_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
| Parametr | Popis |
|---|---|
limit, offset | Stránkování (výchozí 20, max 100) |
status | active, completed nebo ticket_created |
source | widget nebo api |
from, to | Data ve formátu ISO 8601; filtrují podle začátku konverzace |
quality | Konverzace s alespoň jednou otázkou tohoto druhu: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Fulltextové 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 cesta | Popis | Nástroj MCP |
|---|---|---|
GET /analytics/summary | Součty za období | get_analytics_summary |
GET /analytics/timeseries | Počty za hodinu, den nebo týden | get_analytics_timeseries |
GET /analytics/top-queries | Nejčastější otázky | get_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
| Parametr | Popis |
|---|---|
period | today (výchozí), week, month nebo quarter, vyhodnocováno v časovém pásmu chatbota |
from, to | Data ve formátu ISO 8601; nahrazují period; rozsah je nejvýše 366 dní |
source | widget nebo api |
Další parametry
| Koncový bod | Parametr | Popis |
|---|---|---|
timeseries | granularity | auto (výchozí), hour, day nebo week; hour s quarter je odmítnuto |
top-queries | limit, offset | Stránkování (výchozí 20, max 100) |
top-queries | quality | answered, 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 cesta | Popis | Klíčové parametry | Nástroj MCP |
|---|---|---|---|
GET /tickets | Výpis tiketů, nejnovější první | limit (výchozí 20, max 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Jeden tiket | - | get_ticket |
PATCH /tickets/{id} | Změna stavu | status v těle | update_ticket_status |
GET /tickets/{id}/notes | Interní poznámky, nejstarší první | - | list_ticket_notes |
POST /tickets/{id}/notes | Přidání poznámky; vrací 201 | content v těle | add_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žka | Hodnota |
|---|---|
| Stav | open, in_progress, resolved, closed |
| Poznámka | Neprá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 cesta | Popis | Nástroj MCP |
|---|---|---|
GET /webhooks | Výpis webhooků a využití vašich limitů | list_webhook_actions |
POST /webhooks | Vytvoření webhooku, volitelně s nástroji; vrací 201 | create_webhook_action |
GET /webhooks/{id} | Jeden webhook s jeho nástroji | get_webhook_action |
PATCH /webhooks/{id} | Změna webhooku | update_webhook_action |
DELETE /webhooks/{id} | Smazání webhooku s jeho nástroji | delete_webhook_action |
POST /webhooks/{id}/tools | Přidání nástroje; vrací 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Změna nástroje | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Smazání nástroje | delete_webhook_tool |
POST /webhooks/{id}/test | Zavolání webhooku stejně jako chatbot | test_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
| Pole | Popis |
|---|---|
name | Povinné, až 100 znaků |
webhook_url | Povinné, veřejná adresa HTTPS |
http_method | POST (výchozí) nebo GET |
send_metadata | Výchozí true: volání nese také tool_name, args a metadata (chatbot_id, conversation_id, timestamp); false odesílá jen argumenty |
timeout_ms | 1000 až 30000, výchozí 10000 |
headers | Až 20 vlastních hlaviček |
secret_query | Až 10 tajných parametrů dotazu, například API klíč |
tools | Nástroje, které chatbot smí volat (viz níže) |
Pole nástroje
| Pole | Popis |
|---|---|
name | Malá písmena, číslice a podtržítka, začíná písmenem, až 64 znaků, jedinečné na chatbota; create_support_ticket je vyhrazeno |
description | Až 500 znaků; říká chatbotovi, kdy nástroj použít |
parameters | Až 10 položek s name, type (string, number, boolean), description (až 200 znaků), required |
Pravidla
- Hodnoty
headersasecret_queryse nikdy nevracejí, jen jejich názvy. Klíč nalezený vewebhook_urlse automaticky přesune dosecret_querya oznámí se vewarnings. - Změna koncového bodu webhooku vyžaduje znovu odeslat všechny uložené klíče
headersasecret_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ód | HTTP | Význam |
|---|---|---|
UNAUTHORIZED | 401 | Chybějící, neplatný nebo deaktivovaný API klíč |
QUOTA_EXCEEDED | 403 | Měsíční kvóta zpráv vyčerpána (details.quota_info) |
FORBIDDEN | 403 | Funkce není ve vašem tarifu |
LIMIT_EXCEEDED | 403 | Dosažen limit tarifu pro webhooky nebo nástroje (details.resource, used, max) |
INVALID_REQUEST | 400 | Neplatné tělo nebo parametry |
INVALID_URL | 400 | URL webhooku je neplatná, není HTTPS nebo není veřejná |
INVALID_FILE | 400 | V nahrání chybí soubor |
FILE_TOO_LARGE | 400 | Soubor nad 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Přijímají se jen .pdf, .docx, .txt, .md |
CONVERSATION_NOT_FOUND | 400 | conversation_id neexistuje nebo patří jinému chatbotovi |
EDIT_FAILED | 400 | Nahrazovaný text nenalezen, nebo nalezen vícekrát |
NOT_EDITABLE | 400 | Upravovat lze pouze dokumenty UTF-8 .md a .txt |
NOT_FOUND | 404 | Dokument, tiket, webhook, nástroj nebo nahrání nenalezeno, nebo neaktivní chatbot |
DUPLICATE_FILENAME | 409 | Dokument s tímto názvem existuje (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Stejný obsah je již indexován |
REPLACE_IN_PROGRESS | 409 | Dokument se nahrazuje nebo zpracovává; počkejte, až bude completed |
CONFLICT | 409 | Název nástroje již existuje, nebo se dokument od vašeho čtení změnil |
STORAGE_LIMIT_EXCEEDED | 413 | Překročen limit úložiště chatbota |
RATE_LIMITED | 429 | Příliš mnoho požadavků; viz Limity požadavků |
GONE_USE_V1 | 410 | Starý koncový bod /api/chat byl odstraněn; použijte /api/v1/chat |
INTERNAL_ERROR | 500 | Neoč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žka | Hodnota |
|---|---|
| URL serveru | https://www.chatbotty.ai/api/mcp |
| Přenos | Streamable HTTP přes POST |
| Tarify | Všechny tarify; kontroluje se při každém požadavku |
| Limit | 300 požadavků za minutu na klíč (viz Limity požadavků) |
Přihlášení nebo klíč
| Metoda | Používají | Jak |
|---|---|---|
| Přihlášení (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | Klient 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ší klienti | Odeš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
| Oblast | Nástroje |
|---|---|
| Chatbot a chat | get_chatbot_info, send_message |
| Dokumenty | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Mezery ve znalostech | list_knowledge_gaps |
| Konverzace | list_conversations, get_conversation, get_conversation_messages |
| Analytika | get_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_messagekomunikuje s chatbotem jako návštěvník a spotřebovává měsíční kvótu zpráv.test_webhook_actionne.list_knowledge_gapsvypisuje 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)
- Otevřete Settings, poté Connectors a přidejte vlastní konektor.
- Vložte URL serveru a klikněte na Connect.
- 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
- Přidejte uzel MCP Client Tool.
- Endpoint: URL serveru.
- Server Transport: HTTP Streamable.
- 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ém | Co zkontrolovat |
|---|---|
401 | Klíč je chybný, deaktivovaný nebo smazaný |
| Chybí tikety nebo nástroje webhooků | Váš tarif je neobsahuje |
Ruční klient dostává 406 | Klient 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.