Przegląd

Quickchat AI udostępnia REST API zapewniające programistyczny dostęp do konfiguracji Twojego AI Agenta, Bazy Wiedzy, Rozmów, AI Actions i innych funkcji.

Authentication

Wszystkie endpointy API korzystają z uwierzytelniania za pomocą Bearer tokena. Dołącz swój token API w nagłówku Authorization każdego żądania:

Authorization: Bearer <API_TOKEN>

Tokeny tworzy się w Dashboardzie Quickchat w sekcji External Apps > API. Każdy token to JWT zawierający Twoje scenario_id, więc dodatkowy nagłówek identyfikujący nie jest potrzebny.

• Ważność tokena: 52 tygodnie od utworzenia
• Tokeny można odwołać w dowolnym momencie z Dashboardu
• Każdy token jest przypisany do jednego AI Agenta (scenariusza)
• Tworzenie tokenów wymaga planu Business lub wyższego; w niższych planach opcja jest wyłączona, a endpoint zwraca 402 Payment Required

Notatka

Endpoint Chat w czasie rzeczywistym (POST https://app.quickchat.ai/chat) akceptuje ten sam Bearer token co reszta tego API, ale znajduje się poza ścieżką bazową /v1/api/ i wymaga scenario_id w body żądania. Pełną dokumentację znajdziesz na stronie Chat.

Token Scopes

Tokeny API są tworzone z jednym z dwóch scope’ów:

Scope	Access Level	Description
read_all	Read-only	Może odczytywać wszystkie zasoby, ale nie może tworzyć, aktualizować ani usuwać
write_all	Read + Write	Pełny dostęp do wszystkich endpointów, w tym operacji zapisu

• Scope jest przypisywany do tokena podczas tworzenia w Dashboardzie w sekcji External Apps > API
• Scope write_all automatycznie obejmuje wszystkie uprawnienia read_all
• Użycie tokena read_all na endpoincie zapisu zwraca 403 z "Insufficient token scope. Required: write_all"

Wskazówka

Używaj tokenów read_all do monitorowania, analityki i integracji tylko do odczytu. Tokenów write_all używaj wyłącznie wtedy, gdy Twoja integracja musi tworzyć lub modyfikować zasoby.

Wymagania scope’ów według grup endpointów:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

Base URL

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Rate Limits

Limity zapytań są stosowane per token, per endpoint.

Tier	Limit	Applies To
READ	120 requests/min	Operacje GET i listowania
WRITE	60 requests/min	POST, PATCH, PUT, DELETE
HEAVY	20 requests/min	Przesyłanie plików, importy, scrapowanie

Po przekroczeniu limitu zapytań API zwraca HTTP 429 Too Many Requests.

Webhooks

Quickchat AI nie wysyła webhooków wychodzących. Nie ma możliwości zasubskrybowania zdarzenia, abyśmy wysyłali POST na Twój endpoint, gdy przychodzi wiadomość, rozmowa zostaje przekazana człowiekowi albo zostaje zamknięta.

Aby otrzymywać dane na bieżąco, skorzystaj z jednej z tych opcji:

• AI Actions: AI wywołuje Twoje API w trakcie rozmowy. To najbliższy odpowiednik webhooka i działa w modelu push, a nie odpytywania: Twój endpoint jest wywoływany, gdy rozmowa trwa. Uruchamia się wtedy, gdy AI uzna, że dana akcja ma zastosowanie, więc lepiej sprawdza się przy „powiadom mój system o tym leadzie” niż przy „powiadom mój system o każdej wiadomości”.
• Google Sheets: dopisuj wiersz na każde zdarzenie bez budowania endpointu.
• Odpytywanie API Conversations: po pełny zapis. Pamiętaj o limicie READ powyżej.

Dostęp do API wymaga planu Business; zobacz Plany i limity.

Pagination

Endpointy listujące obsługują paginację za pomocą parametrów zapytania:

Parameter	Description
limit integer	Liczba elementów na stronę
offset integer	Liczba elementów do pominięcia

Odpowiedzi z paginacją mają następującą strukturę:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Error Handling

Wszystkie błędy są zwracane jako JSON w następującym formacie:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Nieprawidłowe dane wejściowe lub brakujące wymagane pola
401	PERMISSION_DENIED	Nieprawidłowy, wygasły lub odwołany token
402	PAYMENT_REQUIRED	Wymagana aktywna subskrypcja
403	PERMISSION_DENIED	Token nie ma wymaganego scope’a dla tej operacji
404	NOT_FOUND	Zasób nie znaleziony
409	CONFLICT	Konflikt operacji (np. równoległa modyfikacja)
422	VALIDATION_ERROR	Body żądania nie przeszło walidacji schematu
429	TOO_MANY_REQUESTS	Przekroczono limit zapytań
500	UNKNOWN	Wewnętrzny błąd serwera
503	SERVICE_UNAVAILABLE	Tymczasowa niedostępność

---