Integracja API chatbota: REST, Zapier i webhooki wyjaśnione

API chatbota to interfejs HTTP, który pozwala wysyłać wiadomości do chatbota AI i programowo odbierać odpowiedzi — bez użycia wizualnego widżetu. Zamiast użytkownika wpisującego tekst w dymek czatu, Twój kod wysyła żądanie, otrzymuje odpowiedź i coś z nią robi: renderuje niestandardowy interfejs, zapisuje odpowiedź w logach, uruchamia akcję albo przekazuje wynik do innego systemu.

Ten przewodnik omawia, czym jest API chatbota, kiedy wybrać je zamiast osadzonego widżetu, trzy główne metody połączenia (REST, Zapier i webhooki) oraz praktyczne wzorce budowania rzeczywistych integracji.

Czym jest API chatbota?

API chatbota udostępnia Twojego wytrenowanego chatbota AI jako usługę, którą dowolny kod może wywołać przez HTTP. Wysyłasz wiadomość użytkownika w treści żądania, a API zwraca odpowiedź chatbota — opartą na dowolnych źródłach (treść witryny, dokumenty, pary pytań i odpowiedzi), na których go wytrenowałeś.

Kluczowa różnica względem gotowego widżetu: API zwraca surowe dane. To Twoja aplikacja decyduje, jak je zaprezentować. Oznacza to, że możesz osadzić tego samego chatbota w aplikacji mobilnej, bocie na Slacku, wewnętrznym panelu i backendowym potoku automatyzacji — wszystkie korzystające z tej samej wytrenowanej bazy wiedzy.

Większość API chatbotów działa według podobnego schematu:

1. Uwierzytelnij się — dołącz klucz API w nagłówku Authorization.
2. Wyślij wiadomość metodą POST — prześlij tekst użytkownika, identyfikator chatbota oraz opcjonalnie identyfikator konwersacji dla kontekstu wieloetapowego.
3. Obsłuż odpowiedź — sparsuj odpowiedź, opcjonalnie strumieniuj tokeny dla wrażenia czasu rzeczywistego, i zapisz conversationId na potrzeby kolejnej wiadomości.

Dla zespołów porównujących opcje chatbotów przed wyborem platformy, ten przegląd najlepszych chatbotów AI dla stron internetowych pokazuje, na co zwracać uwagę w poszczególnych narzędziach.

Kiedy używać API, a kiedy widżetu

Osadzony widżet obsługuje większość zastosowań na stronie internetowej. API jest właściwym wyborem, gdy potrzebujesz czegoś, czego widżet nie może zapewnić.

Jeśli Twoje zastosowanie mieści się w prawej kolumnie, API to właściwe narzędzie. Pełny zestaw opcji osadzania — widżet, komponent React, iframe i wtyczka WordPress — znajdziesz w przewodniku integracji chatbota.

Metody połączenia i dostępność w planach

Istnieją trzy sposoby połączenia chatbota z systemami zewnętrznymi. Służą różnym celom i są dostępne w różnych planach.

REST API daje Ci najwięcej kontroli. Zapier konfiguruje się szybciej, jeśli nie potrzebujesz niestandardowego kodu. Webhooki uzupełniają oba rozwiązania — same wysyłają Ci dane, zamiast czekać, aż je pobierzesz.

Pełne zestawienie tego, co obejmuje każdy plan, znajdziesz w przewodniku po kosztach i cenach chatbotów.

Wymagania dla poszczególnych planów

Rozliczenie roczne obniża każdą cenę planu o około 20%. Wiadomości z API liczą się do Twojego miesięcznego limitu tak samo, jak wiadomości z widżetu.

Uwierzytelnianie

Każde żądanie API wymaga tokenu Bearer. Klucze API generujesz w ustawieniach obszaru roboczego w panelu Agentkit.

Generowanie klucza API

1. Otwórz swój obszar roboczy Agentkit.
2. Przejdź do Ustawienia, a następnie Klucze API.
3. Kliknij Utwórz klucz API.
4. Nadaj mu opisową nazwę (np. „Slack Bot Production”).
5. Skopiuj klucz od razu. Nie zostanie ponownie wyświetlony.

Używanie klucza w żądaniach

Dołącz klucz API w nagłówku Authorization:

Authorization: Bearer ak_live_your_api_key_here

Wszystkie żądania muszą być wysyłane przez HTTPS. Żądania bez ważnego tokenu zwracają odpowiedź 401 Unauthorized.

Sprawdzone praktyki zarządzania kluczami

• Przechowuj klucze API w zmiennych środowiskowych, nigdy w kodzie po stronie klienta.
• Rotuj klucze okresowo, zwłaszcza po zmianach w zespole.
• Twórz osobne klucze dla osobnych integracji, dzięki czemu możesz unieważnić jeden bez wpływu na pozostałe.
• Usuwaj klucze, których już nie używasz.

Pełne informacje o uwierzytelnianiu znajdziesz w dokumentacji uwierzytelniania.

Punkt końcowy czatu

Sercem API jest pojedynczy punkt końcowy, który wysyła wiadomość użytkownika do Twojego chatbota i zwraca odpowiedź AI.

Żądanie

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Treść żądania:

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Odpowiedź

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

conversationId w odpowiedzi ma duże znaczenie. Zapisz go i przekaż z powrotem w kolejnych żądaniach, aby zachować kontekst rozmowy. Bez niego każda wiadomość rozpoczyna nową rozmowę, a chatbot traci wątek.

Odpowiedzi błędów

Pełną dokumentację punktów końcowych znajdziesz w dokumentacji API.

Odpowiedzi strumieniowe

Dla aplikacji czasu rzeczywistego, w których chcesz wyświetlać odpowiedź w miarę jej generowania (efekt maszyny do pisania, którego użytkownicy oczekują od czatu AI), użyj Server-Sent Events (SSE).

Dodaj parametr stream: true do swojego żądania:

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

Odpowiedź przychodzi jako strumień zdarzeń SSE:

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Obsługa strumienia w JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

Przesyłanie strumieniowe jest zalecane w każdej integracji skierowanej do użytkownika. Sprawia, że chatbot sprawia wrażenie szybszego nawet podczas generowania długich odpowiedzi.

Webhooki

O ile punkt końcowy czatu pozwala wysyłać wiadomości do chatbota, webhooki pozwalają chatbotowi wysyłać dane do Ciebie. Gdy zajdą określone zdarzenia, Agentkit wysyła żądanie HTTP POST na skonfigurowany przez Ciebie adres URL. Webhooki są dostępne od planu Hobby wzwyż.

Konfigurowanie webhooków

1. Przejdź do Ustawień swojego obszaru roboczego, a następnie Webhooki.
2. Wprowadź adres URL swojego punktu końcowego (musi być HTTPS).
3. Wybierz zdarzenia, na które chcesz się zasubskrybować.
4. Zapisz. Agentkit wyśle żądanie weryfikacyjne, aby potwierdzić, że Twój punkt końcowy jest dostępny.

Dostępne zdarzenia

Ładunek webhooka

Każde żądanie POST webhooka zawiera treść JSON o spójnej strukturze:

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Zawsze weryfikuj pole signature względem swojego sekretu webhooka, aby potwierdzić, że żądanie pochodzi od Agentkit, a nie od strony trzeciej.

Zachowanie przy ponawianiu

Jeśli Twój punkt końcowy zwróci kod statusu inny niż 2xx, Agentkit ponawia próbę z narastającym opóźnieniem: po 1 minucie, 5 minutach, 30 minutach, a następnie przestaje. Nieudane próby dostarczenia są widoczne w dziennikach webhooków w Twoim panelu.

Typowe wzorce integracji

Wzorzec 1: bot na Slacku

Przekazuj pytania klientów z chatbota na stronie do kanału na Slacku i pozwól zespołowi odpowiadać, gdy AI nie potrafi.

1. Utwórz aplikację Slack z włączonymi przychodzącymi webhookami.
2. Skonfiguruj webhook Agentkit dla zdarzeń conversation.completed.
3. W swojej funkcji obsługującej webhook sprawdź, czy rozmowa została rozwiązana, czy eskalowana.
4. Jeśli została eskalowana, wyślij metodą POST sformatowaną wiadomość na adres URL webhooka Slacka wraz z transkrypcją rozmowy.

Daje to Twojemu zespołowi wsparcia widoczność bez konieczności monitorowania panelu Agentkit.

Wzorzec 2: niestandardowy interfejs czatu

Zastąp domyślny widżet interfejsem czatu wbudowanym w Twoją aplikację.

1. Zbuduj swój interfejs czatu w preferowanym frameworku.
2. Po wysłaniu wiadomości wywołaj punkt końcowy czatu z stream: true.
3. Renderuj tokeny w miarę ich napływania, dla informacji zwrotnej w czasie rzeczywistym.
4. Przechowuj conversationId w lokalnym stanie, aby zachować kontekst między wiadomościami.

To właściwe podejście dla aplikacji mobilnych, aplikacji desktopowych lub dowolnego produktu, w którym pływający widżet nie pasuje do designu. Dla zespołów, które chcą pozostać przy widżecie, ale potrzebują więcej kontroli nad jego umiejscowieniem, przewodnik po osadzaniu chatbota na Twojej stronie omawia wszystkie cztery opcje osadzania.

Wzorzec 3: automatyzacja backendowa

Wykorzystaj chatbota jako warstwę AI w większym przepływie pracy, bez żadnego interfejsu czatu.

Przykład: obsługa zgłoszeń wsparcia.

1. Nowe zgłoszenie trafia do Twojego systemu ticketowego.
2. Twój backend wysyła treść zgłoszenia do punktu końcowego czatu.
3. Chatbot generuje sugerowaną odpowiedź na podstawie wytrenowanej bazy wiedzy.
4. Twój system albo odpowiada automatycznie (przy wysokiej pewności), albo kolejkuje sugestię do przeglądu przez człowieka.

Ten wzorzec działa, ponieważ chatbot jest wytrenowany na tej samej bazie wiedzy, z której korzysta Twój zespół wsparcia. API daje Ci programowy dostęp do tej wiedzy. Więcej o tym, na czym możesz wytrenować chatbota — indeksowanie witryny, pliki PDF, CSV, pary pytań i odpowiedzi — znajdziesz w artykule jak wytrenować chatbota.

Wzorzec 4: potok analityczny

Rejestruj każdą rozmowę do analizy.

1. Zasubskrybuj zdarzenia webhooka message.received i message.sent.
2. Twoja funkcja obsługująca webhook zapisuje zdarzenia do hurtowni danych (BigQuery, Snowflake itd.).
3. Zbuduj panele pokazujące najczęstsze pytania, wskaźniki rozwiązanych spraw, godziny szczytu i trendy w rozmowach.

Pole metadanych w punkcie końcowym czatu pozwala dołączyć kontekst (adres URL strony, segment użytkownika, wariant testu A/B), który wzbogaca Twoją analitykę.

Ograniczanie liczby żądań

API egzekwuje ograniczenia liczby żądań, aby zapewnić niezawodność wszystkim użytkownikom.

Po przekroczeniu limitu API zwraca kod statusu 429 z nagłówkiem Retry-After, wskazującym, ile sekund odczekać. Wbuduj logikę ponawiania w swoją integrację:

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Kwestie bezpieczeństwa

Budując integracje API, pamiętaj o tych praktykach:

• Nigdy nie ujawniaj kluczy API w kodzie po stronie klienta. Jeśli budujesz niestandardowy interfejs czatu dla aplikacji webowej, przekazuj żądania przez własny backend.
• Weryfikuj podpisy webhooków. Zawsze sprawdzaj podpis HMAC przed przetworzeniem ładunku webhooka.
• Korzystaj z ograniczeń domen. W ustawieniach chatbota ogranicz, które domeny mogą wchodzić w interakcję z Twoim chatbotem.
• Monitoruj użycie. Regularnie sprawdzaj użycie API w panelu, aby wychwycić nieoczekiwane skoki, które mogą wskazywać na wyciekły klucz.
• Stosuj zasadę najmniejszych uprawnień. Jeśli integracja ma tylko wysyłać wiadomości, nie nadawaj jej klucza z uprawnieniami administratora.

Dla zespołów badających, jak API chatbotów AI łączą się z większymi ekosystemami narzędzi, warto zrozumieć MCP (Model Context Protocol) — nowo powstający standard dający modelom AI ustrukturyzowany dostęp do zewnętrznych narzędzi i danych.

Pierwsze kroki

Najszybsza droga od zera do działającej integracji:

1. Zarejestruj się w Agentkit i utwórz swojego pierwszego chatbota.
2. Wytrenuj chatbota na swoich treściach (zobacz jak wytrenować chatbota).
3. Przejdź na plan Hobby ($29.99/miesiąc), aby włączyć dostęp do API.
4. Wygeneruj klucz API w ustawieniach obszaru roboczego.
5. Wyślij swoje pierwsze testowe żądanie za pomocą cURL lub Postmana.
6. Buduj dalej: niestandardowy interfejs, bota na Slacku, automatyzację — cokolwiek wymaga Twoje zastosowanie.

Najczęściej zadawane pytania

Czym jest klucz API chatbota?

Klucz API chatbota to tajny token, który uwierzytelnia Twoją aplikację przy wysyłaniu żądań do API chatbota. Generujesz go w ustawieniach obszaru roboczego, dołączasz do nagłówka Authorization: Bearer każdego żądania i traktujesz jak hasło — przechowujesz w zmiennych środowiskowych, nigdy w kodzie po stronie klienta, i rotujesz, jeśli podejrzewasz, że mógł wyciec. Każdy klucz można przypisać do konkretnej integracji, dzięki czemu możesz unieważnić jeden bez wpływu na pozostałe.

Czy istnieje darmowe API chatbota?

Plan Free Agentkit ($0/miesiąc) nie obejmuje dostępu do REST API — do tego wymagany jest plan Hobby za $29.99/miesiąc. Plan Free obejmuje osadzalny widżet JS, zbieranie leadów i ograniczenia domen, co pokrywa większość zastosowań na stronie internetowej bez żadnego kodu. Jeśli potrzebujesz programowego dostępu od pierwszego dnia, plan Hobby jest punktem wejścia, a całą platformę możesz przetestować za darmo przed przejściem na wyższy plan.

Czy trzeba umieć programować, żeby korzystać z API chatbota?

Nie zawsze. Jeśli potrzebujesz dostępu do REST API do niestandardowych integracji, musisz napisać kod — albo skorzystać z narzędzia takiego jak Postman, by testować wywołania ręcznie. Ale jeśli Twoim celem jest połączenie chatbota z innymi aplikacjami bez kodu, integracja z Zapier (dostępna od planu Hobby wzwyż) łączy z ponad 7000 aplikacji przez interfejs no-code. Do osadzenia na stronie internetowej nie potrzeba żadnego kodu poza wklejeniem tagu <script>.

Jakie modele AI obsługuje API chatbota?

Bazowy model AI jest konfigurowany dla każdego chatbota osobno w panelu. Agentkit obsługuje modele od trzech dostawców: OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5) i Google (Gemini 3.7 Flash, Gemini 3.1 Pro). Domyślnym modelem jest GPT-5.6 Luna. Twoje wywołania API korzystają z modelu wybranego dla danego chatbota — nie określasz modelu na poziomie samego wywołania API.

Czy mogę użyć API chatbota, żeby osadzić czat na swojej stronie?

Tak, ale do zastosowań na stronie internetowej zwykle prostszy jest widżet JS. Widżet ładuje się asynchronicznie przez pojedynczy tag <script> i automatycznie obsługuje interfejs, stan rozmowy oraz przesyłanie strumieniowe. Użyj API, gdy potrzebujesz w pełni niestandardowego interfejsu, integracji z aplikacją mobilną lub automatyzacji backendowej. Zestawienie wszystkich opcji osadzania obok siebie znajdziesz w przewodniku po osadzaniu chatbota na Twojej stronie.

API chatbota zamienia wytrenowaną bazę wiedzy w usługę, którą można wywołać — te same odpowiedzi AI, które pojawiają się w widżecie, są dostępne dla dowolnego systemu potrafiącego wykonać żądanie HTTP. Niezależnie od tego, czy budujesz niestandardowy interfejs, automatyzujesz proces wsparcia, czy łączysz swojego chatbota z szerszym ekosystemem narzędzi — API daje Ci kontrolę, jakiej gotowy widżet zapewnić nie może.

Zbuduj swojego chatbota za darmo → Karta kredytowa nie jest wymagana.