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
| Element | Wartość |
|---|---|
| Bazowy URL REST | https://www.chatbotty.ai/api/v1 |
| URL serwera MCP | https://www.chatbotty.ai/api/mcp |
| Format | JSON przez HTTPS |
| Uwierzytelnianie | Authorization: Bearer YOUR_API_KEY |
| Zakres klucza | Jeden 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.
| Funkcja | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Czat, dokumenty, konwersacje, analityka | Tak | Tak | Tak | Tak |
| Zgłoszenia | Nie | Tak | Tak | Tak |
| Akcje Webhook | Nie | Tak | Nie | Tak |
| Import dokumentu z adresu URL | Nie | Tak | Tak | Tak |
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 /chatlub narzędzie MCPsend_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ć przezGET /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
| Element | Wartość |
|---|---|
| Format | Losowy 64-znakowy ciąg szesnastkowy |
| Zakres | Jeden chatbot na klucz |
| Limit | Do 50 kluczy na chatbota (nieaktywne klucze również się liczą) |
| Przechowywanie | Przechowywany 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
- Otworzyć API i MCP na pasku bocznym.
- Na karcie swojego chatbota kliknąć Utwórz Nowy, wpisać nazwę (na przykład "Production app") i kliknąć Utwórz.
- 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.
| Akcja | Skutek |
|---|---|
| Dezaktywuj | Klucz 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
| Sytuacja | Odpowiedź |
|---|---|
| Brak nagłówka lub jest nieprawidłowy | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Nieznany lub dezaktywowany klucz | 401 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
| Klasa | Endpointy | Limit na minutę |
|---|---|---|
| Czat | POST /chat | 60 |
| Odczyt | Wszystkie pozostałe endpointy GET oprócz analityki (w tym GET /chatbot) | 120 |
| Zapis | Endpointy POST, PATCH, DELETE | 60 |
| Analityka | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Test webhooka | POST /webhooks/{id}/test | 20 |
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
| Element | Wartość |
|---|---|
| Metoda i ścieżka | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parametry | Brak |
| Limit żądań | Klasa odczytu (zob. Limity żądań) |
| Limit wiadomości | Nie jest zużywany |
| Narzędzie MCP | get_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
planimessage_quotanależą do właściciela konta; limit jest wspólny dla wszystkich chatbotów konta.featurespokazuje, które funkcje zależne od planu może używać ten klucz.handoff_contactto kontakt, który chatbot podaje, gdy nie zna odpowiedzi (tutaj tylko do odczytu;null, gdy nie ustawiono).last_updated_atto 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
| Element | Wartość |
|---|---|
| Metoda i ścieżka | POST https://www.chatbotty.ai/api/v1/chat |
| Limit żądań | Klasa czatu: 60 na minutę |
| Limit wiadomości | Jedna wiadomość na wywołanie; po przekroczeniu limitu wywołanie zwraca 403 QUOTA_EXCEEDED |
| Narzędzie MCP | send_message |
Treść żądania
| Pole | Wymagane | Opis |
|---|---|---|
message | Tak | Pytanie odwiedzającego (niepusty tekst) |
conversation_id | Nie | Kontynuuje istniejącą konwersację; po pominięciu rozpoczyna nową |
options | Nie | Opcjonalny 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żka | Opis | Kluczowe parametry | Narzędzie MCP |
|---|---|---|---|
GET /documents | Lista dokumentów | limit (domyślnie 20, maks. 100), offset, status | list_documents |
POST /documents | Przesłanie dokumentu; zwraca 202 | Zob. niżej | upload_document |
POST /documents/upload-url | Pobranie podpisanego adresu URL dla dużego lub lokalnego pliku | filename | create_upload_url |
GET /documents/{id} | Status i szczegóły jednego dokumentu | - | get_document |
DELETE /documents/{id} | Usunięcie dokumentu | - | delete_document |
GET /documents/{id}/content | Odczyt tekstu, stronicowany | offset, limit (domyślnie 20000, maks. 50000) | read_document |
PATCH /documents/{id}/content | Edycja dokumentu .md lub .txt | edits, append, expected_hash | edit_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.
| Pole | Opis |
|---|---|
file | Plik (tylko multipart) |
content | Tekst dokumentu .md lub .txt (JSON; wymagane filename) |
content_base64 | Plik binarny w base64 (JSON; używać do około 3 MB) |
url | Publiczny adres URL pliku, który serwer pobiera (JSON; tylko plany z importem z adresu URL) |
upload_id | ID z POST /documents/upload-url po przesłaniu pliku |
filename | Nazwa pliku z rozszerzeniem |
description | Opcjonalny opis |
replace_existing | Domyś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
POST /documents/upload-urlz{ "filename": "price-list.pdf" }. Odpowiedź zawieraupload_id,upload_urli nagłówki; adres jest ważny przez 2 godziny i działa jednorazowo.- Wysłać surowy plik metodą
PUTnaupload_url. POST /documentsz{ "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}/contentwysyła tylko zmianę:edits(listaold_textinew_text, każdyold_textmusi wystąpić dokładnie raz, do 100) i/lubappend(text, opcjonalnieafter_heading).expected_hash(zGET .../content) chroni przed nadpisaniem nowszej wersji (409 CONFLICT).- Edytować można tylko dokumenty UTF-8
.mdi.txt(w przeciwnym razie400 NOT_EDITABLE). - Każda edycja lub zastąpienie tworzy nowe
document_id; stara wersja odpowiada, dopóki nowa nie ma statusucompleted. - 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żka | Opis | Kluczowe parametry | Narzędzie MCP |
|---|---|---|---|
GET /conversations | Lista konwersacji | Zob. niżej | list_conversations |
GET /conversations/{id} | Jedna konwersacja | - | get_conversation |
GET /conversations/{id}/messages | Wiadomości w kolejności chronologicznej | limit (domyślnie 50, maks. 200), offset | get_conversation_messages |
Wszystkie trzy używają limitu odczytu 120 żądań na minutę (zob. Limity żądań). Konwersacja innego chatbota zwraca 404 NOT_FOUND.
Filtry listy
| Parametr | Opis |
|---|---|
limit, offset | Stronicowanie (domyślnie 20, maks. 100) |
status | active, completed lub ticket_created |
source | widget lub api |
from, to | Daty ISO 8601; filtr według początku konwersacji |
quality | Konwersacje z co najmniej jednym pytaniem tego rodzaju: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Wyszukiwanie 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żka | Opis | Narzędzie MCP |
|---|---|---|
GET /analytics/summary | Sumy za okres | get_analytics_summary |
GET /analytics/timeseries | Liczby na godzinę, dzień lub tydzień | get_analytics_timeseries |
GET /analytics/top-queries | Najczęstsze pytania | get_top_queries, list_knowledge_gaps |
Wszystkie trzy używają limitu analityki 60 żądań na minutę (zob. Limity żądań).
Wspólne parametry
| Parametr | Opis |
|---|---|
period | today (domyślnie), week, month lub quarter, wyznaczane w strefie czasowej chatbota |
from, to | Daty ISO 8601; zastępują period; zakres wynosi najwyżej 366 dni |
source | widget lub api |
Dodatkowe parametry
| Endpoint | Parametr | Opis |
|---|---|---|
timeseries | granularity | auto (domyślnie), hour, day lub week; hour z quarter jest odrzucane |
top-queries | limit, offset | Stronicowanie (domyślnie 20, maks. 100) |
top-queries | quality | answered, 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żka | Opis | Kluczowe parametry | Narzędzie MCP |
|---|---|---|---|
GET /tickets | Lista zgłoszeń, od najnowszych | limit (domyślnie 20, maks. 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Jedno zgłoszenie | - | get_ticket |
PATCH /tickets/{id} | Zmiana statusu | status w treści żądania | update_ticket_status |
GET /tickets/{id}/notes | Notatki wewnętrzne, od najstarszych | - | list_ticket_notes |
POST /tickets/{id}/notes | Dodanie notatki; zwraca 201 | content w treści żądania | add_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
| Element | Wartość |
|---|---|
| Status | open, in_progress, resolved, closed |
| Notatka | Niepusty 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żka | Opis | Narzędzie MCP |
|---|---|---|
GET /webhooks | Lista webhooków i wykorzystanie limitów | list_webhook_actions |
POST /webhooks | Utworzenie webhooka, opcjonalnie z narzędziami; zwraca 201 | create_webhook_action |
GET /webhooks/{id} | Jeden webhook z jego narzędziami | get_webhook_action |
PATCH /webhooks/{id} | Zmiana webhooka | update_webhook_action |
DELETE /webhooks/{id} | Usunięcie webhooka wraz z narzędziami | delete_webhook_action |
POST /webhooks/{id}/tools | Dodanie narzędzia; zwraca 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Zmiana narzędzia | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Usunięcie narzędzia | delete_webhook_tool |
POST /webhooks/{id}/test | Wywołanie webhooka tak jak robi to chatbot | test_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
| Pole | Opis |
|---|---|
name | Wymagane, do 100 znaków |
webhook_url | Wymagany, publiczny adres HTTPS |
http_method | POST (domyślnie) lub GET |
send_metadata | Domyślnie true: wywołanie przenosi także tool_name, args i metadata (chatbot_id, conversation_id, timestamp); false wysyła tylko argumenty |
timeout_ms | od 1000 do 30000, domyślnie 10000 |
headers | Do 20 własnych nagłówków |
secret_query | Do 10 tajnych parametrów zapytania, na przykład klucz API |
tools | Narzędzia, które chatbot może wywołać (zob. niżej) |
Pola narzędzia
| Pole | Opis |
|---|---|
name | Małe litery, cyfry i podkreślenia, zaczyna się od litery, do 64 znaków, unikalne w obrębie chatbota; create_support_ticket jest zarezerwowane |
description | Do 500 znaków; mówi chatbotowi, kiedy użyć narzędzia |
parameters | Do 10 pozycji z name, type (string, number, boolean), description (do 200 znaków), required |
Zasady
- Wartości
headersisecret_querynigdy nie są zwracane, tylko ich nazwy. Klucz znaleziony wwebhook_urljest automatycznie przenoszony dosecret_queryi zgłaszany wwarnings. - Zmiana endpointu webhooka wymaga ponownego wysłania wszystkich zapisanych kluczy
headersisecret_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
| Kod | HTTP | Znaczenie |
|---|---|---|
UNAUTHORIZED | 401 | Brakujący, nieprawidłowy lub dezaktywowany klucz API |
QUOTA_EXCEEDED | 403 | Miesięczny limit wiadomości wyczerpany (details.quota_info) |
FORBIDDEN | 403 | Funkcji nie ma w Państwa planie |
LIMIT_EXCEEDED | 403 | Osiągnięto limit planu dla webhooków lub narzędzi (details.resource, used, max) |
INVALID_REQUEST | 400 | Nieprawidłowa treść lub parametry |
INVALID_URL | 400 | Adres URL webhooka jest nieprawidłowy, nie jest HTTPS lub nie jest publiczny |
INVALID_FILE | 400 | W przesyłaniu brakuje pliku |
FILE_TOO_LARGE | 400 | Plik większy niż 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Akceptowane są tylko .pdf, .docx, .txt, .md |
CONVERSATION_NOT_FOUND | 400 | conversation_id nie istnieje lub należy do innego chatbota |
EDIT_FAILED | 400 | Tekstu do zastąpienia nie znaleziono lub znaleziono więcej niż raz |
NOT_EDITABLE | 400 | Edytować można tylko dokumenty UTF-8 .md i .txt |
NOT_FOUND | 404 | Nie znaleziono dokumentu, zgłoszenia, webhooka, narzędzia lub przesłania albo chatbot jest nieaktywny |
DUPLICATE_FILENAME | 409 | Dokument o tej nazwie istnieje (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Ta sama treść jest już zaindeksowana |
REPLACE_IN_PROGRESS | 409 | Dokument jest zastępowany lub przetwarzany; należy poczekać, aż będzie completed |
CONFLICT | 409 | Nazwa narzędzia już istnieje lub dokument zmienił się od momentu odczytu |
STORAGE_LIMIT_EXCEEDED | 413 | Przekroczono limit miejsca chatbota |
RATE_LIMITED | 429 | Zbyt wiele żądań; zob. Limity żądań |
GONE_USE_V1 | 410 | Stary endpoint /api/chat został usunięty; należy użyć /api/v1/chat |
INTERNAL_ERROR | 500 | Nieoczekiwany 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
| Element | Wartość |
|---|---|
| URL serwera | https://www.chatbotty.ai/api/mcp |
| Transport | Streamable HTTP przez POST |
| Plany | Wszystkie plany; sprawdzane przy każdym żądaniu |
| Limit | 300 żądań na minutę na klucz (zob. Limity żądań) |
Logowanie lub klucz
| Metoda | Używana przez | Jak |
|---|---|---|
| Logowanie (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | Klient otwiera stronę Chatbotty; logują się Państwo, wybierają chatbota i klikają Zezwól. Klucz jest tworzony automatycznie |
| Klucz API | n8n, Cursor, VS Code, inni klienci | Należ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
| Obszar | Narzędzia |
|---|---|
| Chatbot i czat | get_chatbot_info, send_message |
| Dokumenty | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Luki w wiedzy | list_knowledge_gaps |
| Konwersacje | list_conversations, get_conversation, get_conversation_messages |
| Analityka | get_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_messagerozmawia z chatbotem jak odwiedzający i zużywa miesięczny limit wiadomości.test_webhook_actiongo nie zużywa.list_knowledge_gapswyś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)
- Otworzyć Settings, następnie Connectors, a potem dodać własny konektor.
- Wkleić URL serwera i kliknąć Connect.
- 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
- Dodać węzeł MCP Client Tool.
- Endpoint: URL serwera.
- Server Transport: HTTP Streamable.
- 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
| Problem | Co sprawdzić |
|---|---|
401 | Klucz jest błędny, dezaktywowany lub usunięty |
| Brak narzędzi zgłoszeń lub webhooków | Państwa plan ich nie obejmuje |
Klient ręczny otrzymuje 406 | Klient 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.