Zbuduj integrację od początku do końca

Ten przewodnik przeprowadzi Cię przez wszystko, czego potrzebujesz, aby uruchomić Your AI Connector z poziomu własnego kodu, bez konieczności otwierania panelu nawigacyjnego. Pod koniec zbudujesz minimalną integrację, która:

Uwierzytelnianie za pomocą klucza API
Tworzenie agenta AI i konfigurowanie jego zachowania jako asystenta
Podłączanie kanału komunikacji (jako przykładu używamy WhatsApp Web) i przypisywanie go do agenta
Importowanie kontaktów
Wysyłanie i odczytywanie wiadomości
Odczytywanie analityki
Subskrybowanie webhooków dla zdarzeń w czasie rzeczywistym

Każdy krok zawiera link do pełnego przewodnika po zasobach, dzięki czemu możesz zagłębić się w szczegóły, gdy będziesz tego potrzebować. Ta strona jest mapą; przewodniki po zasobach to teren.

Zanim zaczniesz. Dostęp do API jest funkcją płatną. Jeśli Twój plan go nie obejmuje, każde żądanie zwróci 403. Zobacz Dostęp do API, aby potwierdzić, że jest włączony, oraz Uwierzytelnianie, aby poznać wszystkie sposoby przekazywania klucza.

Wszystkie poniższe ścieżki są względne względem podstawowego adresu URL:

https://api.youraiconnector.com/v1

Krok 1 — Uzyskaj klucz API i wykonaj pierwsze żądanie

Twój klucz API znajduje się w aplikacji w sekcji Ustawienia → Integracje → Klucz API — jest to osobna sekcja w ramach Integracji, oddzielona od Webhooków, która pojawia się tylko wtedy, gdy plan obejmuje dostęp do API. Wygeneruj klucz, skopiuj go i przechowuj w bezpiecznym miejscu (w serwerowym magazynie sekretów lub zmiennej środowiskowej — nigdy w kodzie przeglądarki). Pełne instrukcje znajdują się w Dostęp do API.

Gdy już masz klucz, potwierdź jego działanie, wywołując punkt końcowy sprawdzania stanu (health endpoint). Istnieje kilka sposobów wysłania klucza; najprostszym jest parametr zapytania ?apiKey=, ale w rzeczywistym kodzie preferuj nagłówek X-API-Key, aby klucz nigdy nie trafił do logów serwera ani historii przeglądarki.

cURL

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Każda udana odpowiedź jest zawinięta w tę samą kopertę — pole success: true oraz dane wynikowe. Błędy zwracają success: false z komunikatem error i kodem error_code. Zobacz Błędy i stronicowanie, aby uzyskać pełną listę oraz dowiedzieć się, jak punkty końcowe list stronicują dane za pomocą ?limit i ?cursor.

Limit szybkości. Uwierzytelnione żądania są ograniczone do 300 na minutę (z wyższym limitem 1200 na minutę na konto). Przekroczenie limitu zwraca 429; wstrzymaj się i spróbuj ponownie.

Krok 2 — Utwórz agenta AI

Agent AI to jednostka, która przechowuje zachowanie Twojego asystenta: jego instrukcje, cel, godziny pracy oraz sposób komunikacji z kontaktami. To on odpowiada na konwersacje, więc jest to naturalny pierwszy element do utworzenia.

Utwórz go za pomocą POST /agents. name to jedyne pole, które warto wysłać na początku; wszystko inne można ustawić za pomocą poniższego wywołania bot-config.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

Pomyślne utworzenie zwraca 201 z nowym identyfikatorem:

{
  "success": true,
  "agent_id": "abc123agent"
}

Zapisz agent_id — będziesz się do niego odwoływać podczas kierowania kanałów.

Skonfiguruj asystenta

PUT /agents/{agentId}/bot-config ustawia zachowanie asystenta. Scala ono wysyłane pola z istniejącą konfiguracją, więc wszystko, co pominiesz, zostanie zachowane:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Ustaw godziny pracy za pomocą PUT /agents/{agentId}/active-hours, aby asystent odpowiadał tylko w godzinach pracy; poza tymi oknami nie odpowiada automatycznie.

Baza wiedzy. Aby asystent odpowiadał na podstawie Twoich własnych treści, dołącz FAQ. Zobacz przewodnik po FAQ.

Starsza wersja: klasyczne kampanie. Konta, które nadal mają stronę Kampanie, tworzą to samo zachowanie asystenta w ramach kampanii (POST /campaigns z obiektem type i bot, a następnie PUT /campaigns/{campaignId}/bot-config). Pełna lista pól kampanii i kontrola cyklu życia znajdują się w przewodniku po kampaniach. Jeśli tworzysz coś nowego, utwórz agenta.

Krok 3 — Połącz kanał

Agent potrzebuje sposobu na wysyłanie i odbieranie wiadomości. Z poziomu API można obsłużyć siedem przepływów połączeń: WhatsApp Business, WhatsApp Web, Instagram i Messenger razem (jeden wspólny przepływ Meta), konta osobiste na Instagramie, Telegram, LINE oraz Viber. Pozostałe kanały — w tym SMS, e-mail, widżet czatu i kanały niestandardowe — konfiguruje się w panelu, a nie przez REST. Po ich podłączeniu punkty końcowe dotyczące wiadomości, kontaktów i routingu działają na nich w dokładnie taki sam sposób. GET /channels to aktualne źródło informacji o tym, co faktycznie jest podłączone do danego konta:

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

Pełny zestaw procesów łączenia/rozłączania dla każdego kanału został udokumentowany w przewodniku po kanałach. Poniżej przedstawiamy pełny proces dla WhatsApp Web, ponieważ pokazuje on najciekawszy schemat: proces parowania za pomocą kodu QR, który Twój wrapper musi wyrenderować i odpytywać.

Przykład praktyczny: parowanie WhatsApp Web za pomocą kodu QR

Parowanie WhatsApp Web to taniec składający się z trzech wywołań — start, pobranie kodu QR, odpytywanie do momentu połączenia.

1. Rozpocznij sesję parowania. Podaj numer, który chcesz połączyć, w formacie E.164.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Pobierz kod QR i pokaż go użytkownikowi. Odpytuj o to co 10–15 sekund. Odpowiedź zawiera surowy ładunek qr_code (wyrenderuj go samodzielnie jako obraz QR) oraz gotowy do wyświetlenia qr_data_url.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

W interfejsie swojego wrappera wstaw qr_data_url bezpośrednio do <img src="..."> i poproś użytkownika o zeskanowanie go z poziomu WhatsApp → Połączone urządzenia w telefonie. Jeśli kod QR wygaśnie (odpowiedź 410), rozpocznij od kroku 1, aby uzyskać nowy.

3. Odpytuj o status, aż do momentu połączenia. Po zeskanowaniu przez użytkownika, kontynuuj odpytywanie punktu końcowego statusu, aż zgłosi on connected (usługa może również zgłosić open). Traktuj disconnected oraz not_initialized jako błędy krytyczne.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Uwaga. Każdy połączony numer WhatsApp Web wiąże się z cykliczną miesięczną opłatą za utrzymanie, dopóki go nie rozłączysz (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Skieruj kanał do swojego agenta

Podłączenie kanału sprawia, że zaczyna on działać; skierowanie go informuje platformę, który agent AI powinien odpowiadać na zupełnie nowe przychodzące konwersacje. Ustaw domyślny punkt wejścia (Entry Point) dla kanału, podając nazwę agenta utworzonego w kroku 2:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Powtórz wywołanie dla każdego kanału — jeden domyślny punkt wejścia na kanał. Aby pozostawić kanał bez agenta, wywołaj DELETE /entry-points/channel-defaults?channel=whatsapp_web; aby sprawdzić, czy drabinka punktów wejścia jest aktywna dla konta, wywołaj GET /entry-points/routing-status. Starsza mapa POST /channels/campaign jest zachowana tylko w celu wycofania zmian i nie jest już używana do routingu przychodzącego. Zobacz przewodnik po kanałach, aby uzyskać informacje o innych typach kanałów oraz przepływie OAuth dla WhatsApp Business.

Krok 4 — Import kontaktów

Gdy kanał jest aktywny, załaduj osoby, do których chcesz dotrzeć. Punkt końcowy importu przyjmuje do 500 rekordów na wywołanie. Każdy rekord wymaga phone_number w formacie międzynarodowym; wszystko inne jest opcjonalne. Rekordy z błędnymi numerami, nieobsługiwanymi kanałami lub numerami, które już istnieją, są pomijane — każde pominięcie jest raportowane wraz z indeksem i powodem, dzięki czemu możesz ponowić próbę tylko dla nieudanych rekordów.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

Odpowiedź informuje dokładnie, co się stało:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Aby uzyskać informacje na temat tworzenia pojedynczych rekordów, list/wyszukiwania, list, tagów i pól niestandardowych, zobacz przewodnik po kontaktach.

Krok 5 — Wysyłanie i odczytywanie wiadomości

Wyślij wiadomość

Najprostszy sposób wysyłania jest niezależny od kanału: podaj tożsamość kontaktu oraz treść wiadomości, a platforma dostarczy ją za pośrednictwem kanału, z którego korzysta dany kontakt. Możesz kierować wiadomość według contact_id lub według channel oraz pasującego pola tożsamości (phone_number dla WhatsApp/WhatsApp Web/SMS, instagram_id dla Instagrama itd.).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

Dostarczanie jest asynchroniczne — 201 oznacza, że wiadomość została zaakceptowana i dodana do kolejki, a nie jeszcze dostarczona. (Kontakty z włączonym trybem „nie przeszkadzać” lub trybem prywatnym są odrzucane z kodem 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Odczytaj konwersację

Aby odczytać wiadomości, wyświetl je według kontaktu, od najnowszych, korzystając z paginacji kursorem. Przekaż next_cursor z jednej odpowiedzi jako cursor w następnej, aby przeglądać historię wstecz.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

Możesz również filtrować według typu zawartości (?filter=text|media|tool_use) lub kierunku (?direction=inbound|outbound). Przewodnik po wiadomościach omawia załączniki multimedialne, oznaczanie wiadomości jako przeczytanych oraz widoki wiadomości w ramach sesji.

Nie odpytuj o odpowiedzi. Wyświetlanie wiadomości w pętli czasowej działa, ale marnuje żądania i zwiększa opóźnienia. W przypadku wiadomości przychodzących użyj webhooków — to jest krok 7.

Krok 6 — Odczyt analityki

Gdy wiadomości zaczną płynąć, podsumowanie analityczne dostarczy zagregowane liczby w wybranym zakresie dat: wysłane, dostarczone, odczytane, z odpowiedziami, zarezerwowane, utworzone kontakty oraz wydane/doładowane kredyty. Otrzymasz zarówno sumy dla zakresu, jak i szereg danych dziennych z wypełnionymi zerami — idealne do wykresu na pulpicie nawigacyjnym. Opcjonalnie możesz ograniczyć zakres do pojedynczej kampanii za pomocą campaign_id (poniższe przykłady używają przykładowego identyfikatora kampanii, abc123campaign); pomiń ten parametr, aby uzyskać sumy dla całego konta.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

Domyślny zakres to ostatnie 30 dni, z limitem do 366 dni. Aby uzyskać szczegółowe rejestry zużycia kredytów oraz zestawienia kosztów AI, zapoznaj się z przewodnikiem po analityce.

Krok 7 — Subskrypcja webhooków dla zdarzeń w czasie rzeczywistym

Odpytywanie (polling) sprawdza się w prostych skryptach, ale profesjonalna integracja powinna być oparta na modelu push. Webhooki pozwalają platformie wywołać Twój serwer w momencie, gdy coś się wydarzy — pojawi się nowy kontakt, odpowiedź, umówione spotkanie lub zakończony czat.

Najpierw sprawdź dokładne nazwy zdarzeń, które możesz subskrybować:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Następnie utwórz subskrypcję wskazującą na adres HTTPS na Twoim serwerze. Użyj dokładnych ciągów znaków zdarzeń z powyższego wywołania.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

Adres URL musi używać protokołu HTTPS i być publicznie dostępny. Od tego momentu Twój serwer będzie otrzymywał żądanie POST dla każdego subskrybowanego zdarzenia. Możesz wysłać testowe powiadomienie, sprawdzić stan subskrypcji oraz ponownie włączyć subskrypcję, która została automatycznie wyłączona po wielokrotnych błędach — zobacz przewodnik po webhookach oraz stronę Webhooki na poziomie integracji, aby poznać formaty ładunków (payload) i weryfikację.

Podsumowanie całości

Oto cały proces w skrócie:

Krok	Cel	Kluczowe wywołanie
1	Uwierzytelnianie	`GET /health`
2	Utwórz i dostosuj asystenta	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Połącz kanał i skonfiguruj trasowanie	`POST /channels/whatsapp-web/connections` → pobierz kod QR + status → `PUT /entry-points/channel-defaults`
4	Załaduj kontakty	`POST /contacts/import`
5	Wyślij i odczytaj	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Mierz wyniki	`GET /analytics/summary`
7	Reaguj w czasie rzeczywistym	`POST /webhooks`

Minimalny wrapper to tylko te siedem wywołań zintegrowanych z Twoim własnym interfejsem. Następnie, w miarę potrzeb, możesz dodawać kolejne warstwy, korzystając z przewodników dla poszczególnych zasobów:

Kampanie · Kontakty · FAQ · Wiadomości · Spotkania
Kanały · Szablony · Analityka · Webhooki · Klucze API
Jesteś tu nowy? Wprowadzenie · Uwierzytelnianie · Błędy i stronicowanie

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Zbuduj integrację od początku do końca #

Krok 1 — Uzyskaj klucz API i wykonaj pierwsze żądanie #

Krok 2 — Utwórz agenta AI #

Skonfiguruj asystenta #

Krok 3 — Połącz kanał #

Przykład praktyczny: parowanie WhatsApp Web za pomocą kodu QR #

Skieruj kanał do swojego agenta #

Krok 4 — Import kontaktów #

Krok 5 — Wysyłanie i odczytywanie wiadomości #

Wyślij wiadomość #

Odczytaj konwersację #

Krok 6 — Odczyt analityki #

Krok 7 — Subskrypcja webhooków dla zdarzeń w czasie rzeczywistym #

Podsumowanie całości #

Zbuduj integrację od początku do końca

Krok 1 — Uzyskaj klucz API i wykonaj pierwsze żądanie

Krok 2 — Utwórz agenta AI

Skonfiguruj asystenta

Krok 3 — Połącz kanał

Przykład praktyczny: parowanie WhatsApp Web za pomocą kodu QR

Skieruj kanał do swojego agenta

Krok 4 — Import kontaktów

Krok 5 — Wysyłanie i odczytywanie wiadomości

Wyślij wiadomość

Odczytaj konwersację

Krok 6 — Odczyt analityki

Krok 7 — Subskrypcja webhooków dla zdarzeń w czasie rzeczywistym

Podsumowanie całości