← Powrót do aplikacji

API & MCP

Steruj chatbotem z własnego kodu lub z asystentów AI.

Przegląd#

Chatbotty można używać i nim zarządzać spoza panelu na dwa sposoby: przez REST API z własnego kodu oraz przez konektor MCP z asystentów AI, takich jak Claude. Oba działają z jednym chatbotem naraz i używają tych samych kluczy API. Zaczynamy od Uwierzytelniania.

Podstawy

ElementWartość
Bazowy URL RESThttps://www.chatbotty.ai/api/v1
URL serwera MCPhttps://www.chatbotty.ai/api/mcp
FormatJSON przez HTTPS
UwierzytelnianieAuthorization: Bearer YOUR_API_KEY
Zakres kluczaJeden klucz należy dokładnie do jednego chatbota; chatbot nigdy nie jest przesyłany w żądaniu, wynika z klucza

Czego użyć

  • REST API - piszą Państwo kod, który wysyła wiadomości czatu lub zarządza dokumentami, konwersacjami, zgłoszeniami i akcjami Webhook. Zob. Chatbot i kolejne sekcje z endpointami.
  • Konektor MCP - podłączają Państwo asystenta AI i pozwalają mu pracować z chatbotem bez programowania. Zob. Konektor MCP i Klienci MCP.

Plany

Klucze API, REST API i konektor MCP są dostępne w każdym planie: Free, Evaluation, Support i Automate. Poszczególne funkcje zależą od planu.

FunkcjaFreeEvaluationSupportAutomate
Czat, dokumenty, konwersacje, analitykaTakTakTakTak
ZgłoszeniaNieTakTakTak
Akcje WebhookNieTakNieTak
Import dokumentu z adresu URLNieTakTakTak

Wywołanie funkcji, której nie ma w Państwa planie, zwraca 403 FORBIDDEN. Konektor MCP w ogóle nie oferuje takich narzędzi. Zmiana planu obowiązuje od następnego żądania.

Limit

  • Do miesięcznego limitu wiadomości liczą się tylko wiadomości wysłane przez czat (REST POST /chat lub narzędzie MCP send_message), dokładnie tak samo jak wiadomości z widżetu.
  • Inne wywołania (dokumenty, konwersacje, analityka, zgłoszenia, akcje Webhook) nie zużywają limitu.
  • Gdy limit zostanie wyczerpany, wywołanie czatu zwraca 403 QUOTA_EXCEEDED. Pozostały limit można sprawdzić przez GET /chatbot.
  • Klucze działają niezależnie od dozwolonych domen chatbota, a także gdy chatbot jest nieaktywny dla widżetu (z wyjątkiem wysyłania wiadomości czatu, które nieaktywny chatbot odrzuca z 404 NOT_FOUND).

Format odpowiedzi

Każda odpowiedź REST używa tej samej koperty. Błędy opisuje sekcja Błędy.

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

Uwierzytelnianie#

Każde żądanie musi zawierać klucz API chatbota jako token Bearer. Ten sam klucz działa dla REST API i dla konektora MCP.

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

Klucze API

ElementWartość
FormatLosowy 64-znakowy ciąg szesnastkowy
ZakresJeden chatbot na klucz
LimitDo 50 kluczy na chatbota (nieaktywne klucze również się liczą)
PrzechowywaniePrzechowywany jest tylko hash; pełny klucz jest pokazywany raz, zaraz po utworzeniu

Z kluczami należy postępować jak z hasłami: nigdy ich nie udostępniać i nie umieszczać w kodzie po stronie klienta.

Zarządzanie kluczami w panelu

  1. Otworzyć API i MCP na pasku bocznym.
  2. Na karcie swojego chatbota kliknąć Utwórz Nowy, wpisać nazwę (na przykład "Production app") i kliknąć Utwórz.
  3. Natychmiast skopiować klucz. Nie można go ponownie wyświetlić ("Copy this key now. You won't be able to see it again.").

Następnie lista pokazuje nazwę klucza, jego pierwsze 12 znaków i Ostatnio użyty.

AkcjaSkutek
DezaktywujKlucz przestaje działać natychmiast; Aktywuj włącza go ponownie
UsuńKlucz jest usuwany trwale; aplikacje, które go używają, natychmiast przestają działać

Klucze utworzone przez podłączenie asystenta AI są oznaczone Konektor MCP. Usunięcie takiego klucza odłącza asystenta. Ponowne podłączenie tego samego asystenta do tego samego chatbota zastępuje jego stary klucz.

Błędy uwierzytelniania

SytuacjaOdpowiedź
Brak nagłówka lub jest nieprawidłowy401 UNAUTHORIZED "Missing or invalid Authorization header"
Nieznany lub dezaktywowany klucz401 UNAUTHORIZED "Invalid or inactive API key"

Wszystkie kody opisuje sekcja Błędy, a limity żądań Limity żądań.

Limity żądań#

Limity obowiązują na klucz API i na minutę. Każda klasa endpointów ma własny licznik, dlatego wiele zapisów nie wyczerpuje budżetu odczytów.

REST API

KlasaEndpointyLimit na minutę
CzatPOST /chat60
OdczytWszystkie pozostałe endpointy GET oprócz analityki (w tym GET /chatbot)120
ZapisEndpointy POST, PATCH, DELETE60
AnalitykaGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Test webhookaPOST /webhooks/{id}/test20

Dodatkowy limit: POST /documents/upload-url wydaje najwyżej 50 adresów przesyłania na chatbota w ciągu 2 godzin.

Konektor MCP

Endpoint MCP dopuszcza 300 żądań na minutę na klucz. Każde wywołanie narzędzia podlega następnie także limitowi REST endpointu, z którego korzysta, a send_message zużywa limit wiadomości.

Gdy limit zostanie przekroczony

API zwraca 429 RATE_LIMITED z komunikatem takim jak "Rate limit exceeded. Maximum 60 requests per minute per API key." Należy poczekać do następnej minuty i spróbować ponownie, najlepiej z rosnącym opóźnieniem.

Limity żądań są oddzielne od miesięcznego limitu wiadomości; zob. Przegląd i Błędy.

Chatbot#

Należy zidentyfikować chatbota, do którego należy Państwa klucz API, i sprawdzić jego plan oraz limit, zanim zacznie się z nim pracować.

GET /chatbot

ElementWartość
Metoda i ścieżkaGET https://www.chatbotty.ai/api/v1/chatbot
ParametryBrak
Limit żądańKlasa odczytu (zob. Limity żądań)
Limit wiadomościNie jest zużywany
Narzędzie MCPget_chatbot_info

Odpowiedź

{
  "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"
    }
  }
}

Uwagi

  • plan i message_quota należą do właściciela konta; limit jest wspólny dla wszystkich chatbotów konta.
  • features pokazuje, które funkcje zależne od planu może używać ten klucz.
  • handoff_contact to kontakt, który chatbot podaje, gdy nie zna odpowiedzi (tutaj tylko do odczytu; null, gdy nie ustawiono).
  • last_updated_at to czas ostatnio przesłanego dokumentu.

Czat#

Należy wysłać wiadomość do chatbota i otrzymać jego odpowiedź, dokładnie tak jak odwiedzający w widżecie.

POST /chat

ElementWartość
Metoda i ścieżkaPOST https://www.chatbotty.ai/api/v1/chat
Limit żądańKlasa czatu: 60 na minutę
Limit wiadomościJedna wiadomość na wywołanie; po przekroczeniu limitu wywołanie zwraca 403 QUOTA_EXCEEDED
Narzędzie MCPsend_message

Treść żądania

PoleWymaganeOpis
messageTakPytanie odwiedzającego (niepusty tekst)
conversation_idNieKontynuuje istniejącą konwersację; po pominięciu rozpoczyna nową
optionsNieOpcjonalny obiekt; niepotrzebny w zwykłym użyciu

Jeśli conversation_id nie istnieje lub należy do innego chatbota, wywołanie zwraca 400 CONVERSATION_NOT_FOUND. Chatbot, który nie jest aktywny, zwraca 404 NOT_FOUND.

Odpowiedź

{
  "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 }]
    }
  }
}

Kontekst konwersacji

Pierwsze wywołanie tworzy konwersację i zwraca jej conversation_id. Aby zachować kontekst, należy wysyłać to ID z każdą kolejną wiadomością. Konwersacje utworzone przez API pojawiają się w panelu ze źródłem api.

tools_executed

metadata.tools_executed wymienia narzędzia, które chatbot wywołał podczas odpowiadania (akcje Webhook, tworzenie zgłoszenia pomocy). Każda pozycja ma name, ok i, w razie niepowodzenia, krótki code, taki jak webhook_timeout, webhook_redirect, webhook_blocked lub invalid_args. Pusta lista oznacza, że żadne narzędzie nie zostało wywołane. Pozwala to sprawdzić, czy akcja Webhook rzeczywiście się wykonała.

Dokumenty#

Zarządzanie bazą wiedzy chatbota: przesyłanie, odczyt, edycja, wyświetlanie listy i usuwanie dokumentów. Te wywołania nie zużywają limitu wiadomości.

Endpointy

Metoda i ścieżkaOpisKluczowe parametryNarzędzie MCP
GET /documentsLista dokumentówlimit (domyślnie 20, maks. 100), offset, statuslist_documents
POST /documentsPrzesłanie dokumentu; zwraca 202Zob. niżejupload_document
POST /documents/upload-urlPobranie podpisanego adresu URL dla dużego lub lokalnego plikufilenamecreate_upload_url
GET /documents/{id}Status i szczegóły jednego dokumentu-get_document
DELETE /documents/{id}Usunięcie dokumentu-delete_document
GET /documents/{id}/contentOdczyt tekstu, stronicowanyoffset, limit (domyślnie 20000, maks. 50000)read_document
PATCH /documents/{id}/contentEdycja dokumentu .md lub .txtedits, append, expected_hashedit_document, append_to_document

Limity: wywołania GET używają limitu odczytu, pozostałe limitu zapisu (zob. Limity żądań).

Przesyłanie

Dozwolone typy: .pdf, .docx, .txt, .md, do 10 MB. Można wysłać multipart/form-data albo JSON.

PoleOpis
filePlik (tylko multipart)
contentTekst dokumentu .md lub .txt (JSON; wymagane filename)
content_base64Plik binarny w base64 (JSON; używać do około 3 MB)
urlPubliczny adres URL pliku, który serwer pobiera (JSON; tylko plany z importem z adresu URL)
upload_idID z POST /documents/upload-url po przesłaniu pliku
filenameNazwa pliku z rozszerzeniem
descriptionOpcjonalny opis
replace_existingDomyślnie true: plik o tej samej nazwie jest zastępowany nową wersją

W JSON należy wysłać dokładnie jedno z pól content, content_base64, url, upload_id.

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

Duże lub lokalne pliki

  1. POST /documents/upload-url z { "filename": "price-list.pdf" }. Odpowiedź zawiera upload_id, upload_url i nagłówki; adres jest ważny przez 2 godziny i działa jednorazowo.
  2. Wysłać surowy plik metodą PUT na upload_url.
  3. POST /documents z { "upload_id": "...", "filename": "price-list.pdf" }.

Przetwarzanie i status

Przetwarzanie jest asynchroniczne. Status przechodzi od pending przez processing do completed albo kończy się jako failed z error_message. Dokument ze statusem failed pozostaje na liście; należy go usunąć lub przesłać ponownie. Należy odpytywać GET /documents/{id}, aż status będzie completed.

Edycja i zastępowanie

  • PATCH /documents/{id}/content wysyła tylko zmianę: edits (lista old_text i new_text, każdy old_text musi wystąpić dokładnie raz, do 100) i/lub append (text, opcjonalnie after_heading).
  • expected_hash (z GET .../content) chroni przed nadpisaniem nowszej wersji (409 CONFLICT).
  • Edytować można tylko dokumenty UTF-8 .md i .txt (w przeciwnym razie 400 NOT_EDITABLE).
  • Każda edycja lub zastąpienie tworzy nowe document_id; stara wersja odpowiada, dopóki nowa nie ma statusu completed.
  • Druga zmiana, gdy dokument jest jeszcze przetwarzany, zwraca 409 REPLACE_IN_PROGRESS.

Konwersacje#

Odczyt historii konwersacji chatbota, w tym konwersacji utworzonych w widżecie. Te wywołania są tylko do odczytu i nie zużywają limitu wiadomości.

Endpointy

Metoda i ścieżkaOpisKluczowe parametryNarzędzie MCP
GET /conversationsLista konwersacjiZob. niżejlist_conversations
GET /conversations/{id}Jedna konwersacja-get_conversation
GET /conversations/{id}/messagesWiadomości w kolejności chronologicznejlimit (domyślnie 50, maks. 200), offsetget_conversation_messages

Wszystkie trzy używają limitu odczytu 120 żądań na minutę (zob. Limity żądań). Konwersacja innego chatbota zwraca 404 NOT_FOUND.

Filtry listy

ParametrOpis
limit, offsetStronicowanie (domyślnie 20, maks. 100)
statusactive, completed lub ticket_created
sourcewidget lub api
from, toDaty ISO 8601; filtr według początku konwersacji
qualityKonwersacje z co najmniej jednym pytaniem tego rodzaju: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qWyszukiwanie pełnotekstowe w treści wiadomości (od 2 do 200 znaków)

Odpowiedź

{
  "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 }
  }
}

W planach ze zgłoszeniami szczegóły konwersacji zawierają także tickets utworzone w niej. Wiadomości mają id, role (user lub assistant), content i created_at.

Wskazówka

Aby znaleźć pytania, na które chatbot nie potrafił odpowiedzieć, należy użyć GET /analytics/top-queries?quality=not_answered (zob. Analityka) i otworzyć powiązane konwersacje przez conversation_ids.

Analityka#

Zagregowane statystyki chatbota. Analityka jest dostępna w każdym planie, także Free. Te wywołania nie zużywają limitu wiadomości.

Endpointy

Metoda i ścieżkaOpisNarzędzie MCP
GET /analytics/summarySumy za okresget_analytics_summary
GET /analytics/timeseriesLiczby na godzinę, dzień lub tydzieńget_analytics_timeseries
GET /analytics/top-queriesNajczęstsze pytaniaget_top_queries, list_knowledge_gaps

Wszystkie trzy używają limitu analityki 60 żądań na minutę (zob. Limity żądań).

Wspólne parametry

ParametrOpis
periodtoday (domyślnie), week, month lub quarter, wyznaczane w strefie czasowej chatbota
from, toDaty ISO 8601; zastępują period; zakres wynosi najwyżej 366 dni
sourcewidget lub api

Dodatkowe parametry

EndpointParametrOpis
timeseriesgranularityauto (domyślnie), hour, day lub week; hour z quarter jest odrzucane
top-querieslimit, offsetStronicowanie (domyślnie 20, maks. 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Odpowiedź summary

{
  "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 to liczba pytań z odpowiedzią podzielona przez sumę pytań z odpowiedzią i bez odpowiedzi, w procentach.

Pytania bez odpowiedzi

GET /analytics/top-queries?quality=not_answered&period=month zwraca pytania, na które chatbot nie potrafił odpowiedzieć, od najczęstszych. Każda pozycja ma content, count, last_asked oraz do 5 conversation_ids, które można otworzyć przez konwersacje. Należy dodać brakujące fakty do bazy wiedzy i zweryfikować wynik przez czat.

Zgłoszenia#

Odczyt zgłoszeń pomocy, zmiana ich statusu i dodawanie notatek wewnętrznych. Zgłoszenia są dostępne w planach Evaluation, Support i Automate; Free zwraca 403 FORBIDDEN. Zgłoszeń nie można tworzyć przez API: tworzy je chatbot podczas konwersacji.

Endpointy

Metoda i ścieżkaOpisKluczowe parametryNarzędzie MCP
GET /ticketsLista zgłoszeń, od najnowszychlimit (domyślnie 20, maks. 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Jedno zgłoszenie-get_ticket
PATCH /tickets/{id}Zmiana statusustatus w treści żądaniaupdate_ticket_status
GET /tickets/{id}/notesNotatki wewnętrzne, od najstarszych-list_ticket_notes
POST /tickets/{id}/notesDodanie notatki; zwraca 201content w treści żądaniaadd_ticket_note

Wywołania GET używają limitu odczytu (120 na minutę), PATCH i POST limitu zapisu (60 na minutę); zob. Limity żądań.

Wartości

ElementWartość
Statusopen, in_progress, resolved, closed
NotatkaNiepusty tekst, do 5000 znaków

Nieprawidłowy status zwraca 400 INVALID_REQUEST. Zgłoszenie innego chatbota zwraca 404 NOT_FOUND.

Obiekt zgłoszenia

{
  "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"
}

Przykład

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"}'

Akcje Webhook#

Zarządzanie akcjami Webhook chatbota: zewnętrznymi API lub webhookami automatyzacji (na przykład n8n), które chatbot wywołuje jako narzędzia podczas odpowiadania. Dostępne w planie Automate (10 webhooków i 10 narzędzi na chatbota) oraz w okresie próbnym Evaluation (5 webhooków i 5 narzędzi na chatbota). Pozostałe plany otrzymują 403 FORBIDDEN; przekroczenie limitów zwraca 403 LIMIT_EXCEEDED. Wywołania nie zużywają limitu wiadomości.

Endpointy

Metoda i ścieżkaOpisNarzędzie MCP
GET /webhooksLista webhooków i wykorzystanie limitówlist_webhook_actions
POST /webhooksUtworzenie webhooka, opcjonalnie z narzędziami; zwraca 201create_webhook_action
GET /webhooks/{id}Jeden webhook z jego narzędziamiget_webhook_action
PATCH /webhooks/{id}Zmiana webhookaupdate_webhook_action
DELETE /webhooks/{id}Usunięcie webhooka wraz z narzędziamidelete_webhook_action
POST /webhooks/{id}/toolsDodanie narzędzia; zwraca 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Zmiana narzędziaupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Usunięcie narzędziadelete_webhook_tool
POST /webhooks/{id}/testWywołanie webhooka tak jak robi to chatbottest_webhook_action

Odczyty używają limitu odczytu (120 na minutę), zmiany limitu zapisu (60), a test ma własny limit 20 na minutę; zob. Limity żądań. Narzędzie MCP get_webhook_guide zwraca krótki przewodnik dla asystentów AI.

Pola webhooka

PoleOpis
nameWymagane, do 100 znaków
webhook_urlWymagany, publiczny adres HTTPS
http_methodPOST (domyślnie) lub GET
send_metadataDomyślnie true: wywołanie przenosi także tool_name, args i metadata (chatbot_id, conversation_id, timestamp); false wysyła tylko argumenty
timeout_msod 1000 do 30000, domyślnie 10000
headersDo 20 własnych nagłówków
secret_queryDo 10 tajnych parametrów zapytania, na przykład klucz API
toolsNarzędzia, które chatbot może wywołać (zob. niżej)

Pola narzędzia

PoleOpis
nameMałe litery, cyfry i podkreślenia, zaczyna się od litery, do 64 znaków, unikalne w obrębie chatbota; create_support_ticket jest zarezerwowane
descriptionDo 500 znaków; mówi chatbotowi, kiedy użyć narzędzia
parametersDo 10 pozycji z name, type (string, number, boolean), description (do 200 znaków), required

Zasady

  • Wartości headers i secret_query nigdy nie są zwracane, tylko ich nazwy. Klucz znaleziony w webhook_url jest automatycznie przenoszony do secret_query i zgłaszany w warnings.
  • Zmiana endpointu webhooka wymaga ponownego wysłania wszystkich zapisanych kluczy headers i secret_query, aby sekrety nie mogły niezauważenie trafić na inny serwer.
  • Chatbot wykonuje jedną rundę wywołań narzędzi na odpowiedź. Odpowiedź jest obcinana do 10 KB, przekierowania nie są śledzone, a adresy wewnętrzne są odrzucane.

Test

POST /webhooks/{id}/test z opcjonalną treścią { "tool_name": "get_weather", "arguments": { "q": "Prague" } } zwraca ok, status, response_time_ms, body_preview (pierwsze 2 KB), truncated i warnings. Po teście należy zadać chatbotowi pasujące pytanie przez czat i sprawdzić tools_executed.

Błędy#

Nieudane wywołania REST zwracają status HTTP inny niż 2xx oraz taką kopertę:

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

details występuje tylko przy niektórych błędach. Błędy należy obsługiwać według code; komunikaty mogą się zmieniać.

Kody błędów

KodHTTPZnaczenie
UNAUTHORIZED401Brakujący, nieprawidłowy lub dezaktywowany klucz API
QUOTA_EXCEEDED403Miesięczny limit wiadomości wyczerpany (details.quota_info)
FORBIDDEN403Funkcji nie ma w Państwa planie
LIMIT_EXCEEDED403Osiągnięto limit planu dla webhooków lub narzędzi (details.resource, used, max)
INVALID_REQUEST400Nieprawidłowa treść lub parametry
INVALID_URL400Adres URL webhooka jest nieprawidłowy, nie jest HTTPS lub nie jest publiczny
INVALID_FILE400W przesyłaniu brakuje pliku
FILE_TOO_LARGE400Plik większy niż 10 MB
UNSUPPORTED_FILE_TYPE400Akceptowane są tylko .pdf, .docx, .txt, .md
CONVERSATION_NOT_FOUND400conversation_id nie istnieje lub należy do innego chatbota
EDIT_FAILED400Tekstu do zastąpienia nie znaleziono lub znaleziono więcej niż raz
NOT_EDITABLE400Edytować można tylko dokumenty UTF-8 .md i .txt
NOT_FOUND404Nie znaleziono dokumentu, zgłoszenia, webhooka, narzędzia lub przesłania albo chatbot jest nieaktywny
DUPLICATE_FILENAME409Dokument o tej nazwie istnieje (details.existing_document_id)
DUPLICATE_CONTENT409Ta sama treść jest już zaindeksowana
REPLACE_IN_PROGRESS409Dokument jest zastępowany lub przetwarzany; należy poczekać, aż będzie completed
CONFLICT409Nazwa narzędzia już istnieje lub dokument zmienił się od momentu odczytu
STORAGE_LIMIT_EXCEEDED413Przekroczono limit miejsca chatbota
RATE_LIMITED429Zbyt wiele żądań; zob. Limity żądań
GONE_USE_V1410Stary endpoint /api/chat został usunięty; należy użyć /api/v1/chat
INTERNAL_ERROR500Nieoczekiwany błąd serwera

Błędy MCP

Endpoint MCP odpowiada błędami JSON-RPC: 401 przy braku lub nieprawidłowym tokenie, 429 przy zbyt wielu żądaniach i 403, gdy plan nie obejmuje MCP. Gdy narzędzie zawiedzie, wynik jest oznaczony jako błąd i zawiera kod API, na przykład Chatbotty API error [NOT_FOUND] (HTTP 404). Zob. Konektor MCP.

Pomoc techniczna

Jeśli błąd się utrzymuje, należy napisać na support@chatbotty.ai, podając kod, czas i endpoint.

Konektor MCP#

Konektor MCP pozwala asystentowi AI, takiemu jak Claude, n8n lub Cursor, pracować z Państwa chatbotem: rozmawiać z nim, zarządzać jego bazą wiedzy, konfigurować akcje Webhook oraz odczytywać konwersacje, analitykę i zgłoszenia. Jeden konektor należy do jednego chatbota; aby użyć innego chatbota, należy dodać kolejny konektor.

Połączenie

ElementWartość
URL serwerahttps://www.chatbotty.ai/api/mcp
TransportStreamable HTTP przez POST
PlanyWszystkie plany; sprawdzane przy każdym żądaniu
Limit300 żądań na minutę na klucz (zob. Limity żądań)

Logowanie lub klucz

MetodaUżywana przezJak
Logowanie (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeKlient otwiera stronę Chatbotty; logują się Państwo, wybierają chatbota i klikają Zezwól. Klucz jest tworzony automatycznie
Klucz APIn8n, Cursor, VS Code, inni klienciNależy wysłać nagłówek Authorization: Bearer YOUR_API_KEY (Uwierzytelnianie)

Klucz utworzony przez zalogowanie jest oznaczony Konektor MCP w API i MCP. Aby odłączyć asystenta, należy go tam usunąć. Narzędzia zgłoszeń i webhooków pojawiają się tylko wtedy, gdy obejmuje je Państwa plan. Kroki konfiguracji znajdują się w Klienci MCP.

Narzędzia

ObszarNarzędzia
Chatbot i czatget_chatbot_info, send_message
Dokumentylist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Luki w wiedzylist_knowledge_gaps
Konwersacjelist_conversations, get_conversation, get_conversation_messages
Analitykaget_analytics_summary, get_analytics_timeseries, get_top_queries
Zgłoszenia (plany ze zgłoszeniami)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Akcje Webhook (plany z akcjami Webhook)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żde narzędzie działa jak odpowiadający mu endpoint REST opisany w poprzednich sekcjach i ma te same limity oraz błędy.

Warto wiedzieć

  • send_message rozmawia z chatbotem jak odwiedzający i zużywa miesięczny limit wiadomości. test_webhook_action go nie zużywa.
  • list_knowledge_gaps wyświetla pytania, na które chatbot nie potrafił odpowiedzieć, i wymaga podania okresu; służy do znalezienia, co dodać do bazy wiedzy.
  • Klient może przechowywać opisy narzędzi w pamięci podręcznej. Jeśli narzędzia wyglądają na nieaktualne, należy usunąć konektor i dodać go ponownie.

Klienci MCP#

Jak podłączyć popularnych klientów do https://www.chatbotty.ai/api/mcp. W przypadku klientów, którzy wysyłają klucz, należy go najpierw utworzyć w sposób opisany w Uwierzytelnianie. Tło: Konektor MCP.

Claude (claude.ai, Claude Desktop, mobile)

  1. Otworzyć Settings, następnie Connectors, a potem dodać własny konektor.
  2. Wkleić URL serwera i kliknąć Connect.
  3. Zalogować się do Chatbotty, wybrać chatbota i kliknąć Zezwól.

Klucz API nie jest potrzebny. Konektor działa wtedy także w aplikacji mobilnej Claude.

Claude Code

Logowanie przez przeglądarkę:

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

Lub z kluczem API:

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

Gdy strona logowania ostrzega, że aplikacja działa na Państwa własnym komputerze, dostęp należy zezwolić tylko wtedy, gdy samodzielnie rozpoczęto połączenie.

n8n

  1. Dodać węzeł MCP Client Tool.
  2. Endpoint: URL serwera.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth z Państwa kluczem API.

Cursor, VS Code i inni klienci

Należy dodać zdalny serwer MCP z URL serwera i nagłówkiem Authorization: Bearer YOUR_API_KEY. Na przykład w Cursor:

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

Rozwiązywanie problemów

ProblemCo sprawdzić
401Klucz jest błędny, dezaktywowany lub usunięty
Brak narzędzi zgłoszeń lub webhookówPaństwa plan ich nie obejmuje
Klient ręczny otrzymuje 406Klient musi wysyłać Accept: application/json, text/event-stream

Przykłady#

Przykłady do skopiowania dla najczęstszych zadań. Należy zastąpić YOUR_API_KEY kluczem z API i MCP, a https://www.chatbotty.ai bazowym adresem URL. Zob. Uwierzytelnianie.

Sprawdzenie chatbota i limitu

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

Zadanie pytania i kontynuacja konwersacji

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?"}'

Należy wziąć conversation_id z odpowiedzi i wysłać je z następną wiadomością:

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"}'

Przesłanie dokumentu

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

Następnie należy sprawdzać status, aż będzie completed:

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

Wyszukanie pytań bez odpowiedzi

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

Lista konwersacji zawierających słowo

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

Obsługa błędów

{ "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" }

Należy rozgałęziać logikę według error.code i zob. Błędy. Informacje o limitach: Limity żądań. Pytania: support@chatbotty.ai.