API kampanii #

Kampania łączy w sobie wszystko, czego bot AI potrzebuje do rozmowy z Twoimi kontaktami: instrukcje, kanały, na których działa, godziny aktywności oraz zachowanie w ramach działań następczych. API kampanii umożliwia wyświetlanie, tworzenie, aktualizowanie, duplikowanie, włączanie, archiwizowanie i dostrajanie kampanii bezpośrednio z poziomu Twojego kodu, zamiast korzystać z pulpitu nawigacyjnego.

Wszystkie poniższe punkty końcowe są relatywne względem bazowego adresu URL https://api.youraiconnector.com/v1. Każde żądanie musi być uwierzytelnione — zobacz Dostęp do API oraz Uwierzytelnianie, aby dowiedzieć się, jak uzyskać i przekazać klucz API. Dostęp do API jest funkcją płatną; bez niego żądania są odrzucane z błędem 403.

Uwaga: Niektóre przykłady pokazują prosty formularz zapytań ?apiKey=YOUR_API_KEY, inne używają nagłówka X-API-Key. Oba działają wszędzie — użyj tego, który lepiej pasuje do Twojej konfiguracji.

Typy kampanii #

Podczas tworzenia kampanii musisz wybrać jeden z poniższych typów:

Wielkość liter nie ma znaczenia. type, status, booking_provider, first_response_mode, bot.anthropic_model oraz bot.ai_speed akceptują dowolną wielkość liter — "live", "Live" oraz "LIVE" oznaczają to samo — a wartość jest przechowywana w swojej kanonicznej formie, która jest zwracana podczas odczytu kampanii. Jedynym wyjątkiem jest para wstrzymania: "Paused" oraz "paused" to dwa faktycznie różne stany, więc niejednoznaczna pisownia, taka jak "PAUSED", jest odrzucana z błędem 400, informującym o konieczności wyboru jednej z nich.

Dwa stany wstrzymania #

Oba stany zatrzymują kampanię: routing przychodzący działa tylko wtedy, gdy status jest dokładnie równy Live. Z poziomu API użyj Paused, aby wstrzymać, oraz Live, aby wznowić — para pisana małymi literami istnieje dla przycisku na pulpicie nawigacyjnym i jest utrzymywana w celu jego poprawnego działania.

Żaden z tych stanów nie jest tym, co dzieje się, gdy AI przestaje odpowiadać w ramach jednej rozmowy. Jest to przełącznik dla konkretnego kontaktu, is_bot_active przy kontakcie — ustawiany, gdy kontrolę przejmuje człowiek, gdy kontakt rezygnuje z subskrypcji lub gdy AI kończy czat. Status samej kampanii pozostaje nienaruszony, a wszystkie inne rozmowy w jej ramach działają dalej. Zobacz wstrzymywanie lub wznawianie AI dla jednego kontaktu.

Utworzenie kampanii nie decyduje o tym, kto odpowiada na kanale. Routing jest obsługiwany przez punkty wejścia (Entry Points) w agencie AI, a nie przez kampanie. Każdy kanał ma jeden domyślny punkt wejścia wskazujący agenta, który odpowiada na nowe, nieznane kontakty: ustaw go za pomocą PUT /entry-points/channel-defaults, sprawdź, czy drabinka jest aktywna dla konta za pomocą GET /entry-points/routing-status, wyczyść go za pomocą DELETE /entry-points/channel-defaults. POST /channels/campaign nadal zapisuje starszą mapę routingu kampanii dla poszczególnych kanałów, ale mapa ta nie jest już używana do routingu przychodzącego na żadnym koncie; jest zachowana wyłącznie w celu wycofania zmian. Nie opieraj na niej żadnych rozwiązań. Zobacz Skieruj kanał do kampanii, aby porównać oba podejścia.

Wyświetlanie kampanii #

GET /campaigns

Zwraca Twoje kampanie, zaczynając od najnowszych. Zarchiwizowane kampanie są wykluczone, chyba że przekażesz archived=true.

Parametry zapytania

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Odpowiedź

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Gdy next_cursor ma wartość null, oznacza to, że dotarłeś do ostatniej strony.

Pobierz kampanię #

GET /campaigns/{campaignId}

Zwraca pełny dokument kampanii, w tym konfigurację aktywnego bota (bot), ustawienia działań następczych, włączone kanały oraz wszelkie słowa kluczowe. Sygnatury czasowe są zwracane w milisekundach czasu epoch.

cURL

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

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Odpowiedź

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Utwórz kampanię #

POST /campaigns

Tworzy nową kampanię. name oraz type są wymagane; wszystko inne jest opcjonalne. Możesz dołączyć dowolne inne pole kampanii w tym samym żądaniu — na przykład language, ai_mode lub pełny obiekt konfiguracji bot — a zostanie ono zapisane wraz z nową kampanią. Właściciel i czas utworzenia są ustawiane automatycznie.

Pola żądania

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Aktualizacja kampanii #

PUT /campaigns/{campaignId}

Częściowo aktualizuje kampanię — wyślij tylko te pola, które chcesz zmienić. Jest to jedyna ogólna metoda aktualizacji; nie istnieje PATCH /campaigns/{campaignId} (dwie trasy PATCH to wąskie przełączniki włącz i archiwizuj).

Pola, które możesz zmienić. Wszystko, co zapisuje edytor kampanii, w tym name, status, type, language, ai_mode, enabled_channels, ustawienia wyzwalacza i sekwencji (drip), flagi rezerwacji i działań następczych, pola monitorowania Instagrama/Facebooka oraz cała konfiguracja bot. Tożsamość i własność są zablokowane na czas trwania kampanii: user, id oraz created_at są odrzucane, podobnie jak każda nazwa pola, której punkt końcowy nie rozpoznaje. Odrzucenie dotyczy całego żądania, a nie poszczególnych pól — jeden nieznany klucz zwraca 400 i nic w tym żądaniu nie zostaje zapisane.

ai_mode w kampanii obsługiwanej przez agenta odzwierciedla stan agenta. Gdy na kampanię odpowiada agent AI, odczyt kampanii zwraca ai_mode pochodzące z przełącznika Aktywny tego agenta — jest to jedyny przełącznik, który faktycznie decyduje o tym, czy AI odpowiada. Zapisanie ai_mode w takiej kampanii jest akceptowane, ale nie zmieni wartości zwracanej przy odczycie; zamiast tego należy włączyć lub wyłączyć przełącznik Aktywny agenta (w panelu nawigacyjnym lub za pośrednictwem API agentów). W klasycznych kampaniach bez agenta, ai_mode odczytuje i zapisuje przechowywaną wartość tak jak dotychczas.

Pola bota są scalane, a nie nadpisywane. Wysyłaj ustawienia bota jako klucze kropkowe ("bot.instructions": "...") lub jako zagnieżdżony obiekt ("bot": { "instructions": "..." }) — oba sposoby zapisują dane element po elemencie, więc pola, których nie wyślesz, zachowują swoje bieżące wartości. bot.instructions, bot.goal, bot.rules oraz bot.personality można edytować w ten sposób, podobnie jak każde inne ustawienie bota wymienione w sekcji Pola konfiguracji bota. To samo dotyczy test_bot, frequency oraz follow_up_config.

Aby całkowicie zastąpić konfigurację bota — usuwając każde pole, którego nie wyślesz — użyj bot_replace (lub test_bot_replace) z pełnym obiektem. Nie można łączyć zastępowania i scalania dla tego samego obiektu w jednym żądaniu; zwraca to 400.

Kilka pól ustawia się za pomocą dedykowanego klucza, zamiast zapisywać je bezpośrednio: użyj list_id dla listy kontaktów, event_id dla typu wydarzenia (lub event_ids, uporządkowanej tablicy ID typów wydarzeń, aby pozwolić AI na rezerwację kilku — pierwszy jest domyślny; pusta tablica usuwa powiązania ze wszystkimi), oraz contact_ids (tablicy ID kontaktów) dla kontaktów kampanii. Wpisy w bazie wiedzy są zarządzane przez API FAQ, a nie przez ten punkt końcowy.

Tagi zastępują, nie scalają. Wyślij tags jako kompletną tablicę, a stanie się ona zestawem tagów kampanii — zobacz Tagi kampanii, aby poznać pola oraz punkty końcowe służące do dodawania lub edycji pojedynczego tagu.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Usuwanie kampanii #

DELETE /campaigns/{campaignId}

Trwale usuwa kampanię. Tej operacji nie można cofnąć — jeśli kampania może być jeszcze potrzebna, zarchiwizuj ją.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "success": true
}

Duplikowanie kampanii #

POST /campaigns/{campaignId}/duplicate

Tworzy kopię kampanii z zachowaniem wszystkich jej ustawień. Kopia jest domyślnie wyłączona, a jej nazwa otrzymuje przyrostek (copy), dzięki czemu nie wysyła żadnych wiadomości, dopóki jej wyraźnie nie włączysz.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Odpowiedź

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Zduplikowane kopie w ramach jednego konta.

Włączanie lub wyłączanie kampanii #

PATCH /campaigns/{campaignId}/enabled

Włącza lub wyłącza kampanię. Wyłączona kampania przestaje angażować kontakty, ale zachowuje całą swoją konfigurację.

Pola żądania

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Archiwizowanie lub przywracanie kampanii #

PATCH /campaigns/{campaignId}/archived

Archiwizuje lub przywraca kampanię. Zarchiwizowane kampanie są ukryte na domyślnej liście kampanii, ale zachowują wszystkie swoje dane i można je przywrócić w dowolnym momencie.

Pola żądania

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Aktualizacja konfiguracji bota #

PUT /campaigns/{campaignId}/bot-config

To bezpieczny sposób na zmianę poszczególnych ustawień bota. Każde wysłane pole jest scalane z istniejącą konfiguracją bota, więc wszystkie pominięte pola zostają zachowane. Używaj tego zamiast punktu końcowego aktualizacji kampanii, gdy chcesz jedynie zmodyfikować część bota.

Klucze pól mogą zawierać tylko litery, cyfry, podkreślniki i myślniki.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Pola konfiguracji bota #

Wszystkie pola bota są opcjonalne. Wyślij tylko te, które chcesz ustawić. Wszelkie dodatkowe pola bota wykraczające poza wymienione tutaj są akceptowane i przechowywane w niezmienionej formie.

Ustaw godziny aktywności bota #

PUT /campaigns/{campaignId}/active-hours

Ustawia harmonogram dostępności bota. Poza skonfigurowanymi oknami czasowymi bot nie odpowiada automatycznie. Zapisuje to pole availability w konfiguracji bota.

Pola żądania

Każdy dzień tygodnia zawiera pojedyncze okno czasowe lub tablicę okien. Okno posiada start_time i end_time w 24-godzinnym formacie HH:MM.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Wyświetl listę niestandardowych funkcji kampanii #

GET /campaigns/{campaignId}/custom-functions

Zwraca funkcje niestandardowe powiązane z tą kampanią, rozwiązane do pełnych definicji. Funkcje niestandardowe to zewnętrzne akcje HTTP, które bot może wywołać podczas rozmowy — na przykład sprawdzenie stanu magazynowego w Twoim sklepie lub utworzenie rekordu w systemie CRM.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Odpowiedź

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Powiąż funkcję niestandardową z kampanią #

POST /campaigns/{campaignId}/custom-functions

Powiązuje istniejącą funkcję niestandardową z tą kampanią, aby bot mógł ją wywoływać podczas rozmowy. Powiązanie funkcji, która jest już powiązana, nie powoduje żadnej akcji.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Odwiąż funkcję niestandardową od kampanii #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Odwiązanie funkcji, która nie jest powiązana, nie powoduje żadnej akcji.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Powiąż źródło bazy wiedzy z kampanią #

POST /campaigns/{campaignId}/kb-sources

Powiązuje źródło bazy wiedzy (utworzone za pomocą interfejsu API FAQ) z tą kampanią, aby bot mógł z niego korzystać podczas udzielania odpowiedzi. Powiązanie źródła, które jest już powiązane, nie powoduje żadnej akcji.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Odwiąż źródło bazy wiedzy od kampanii #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Odwiązanie źródła, które nie jest powiązane, nie powoduje żadnej akcji.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Powiąż serwer MCP z kampanią #

POST /campaigns/{campaignId}/mcp-servers

Łączy serwer MCP z tą kampanią, dając botowi dostęp do narzędzi tego serwera podczas rozmowy. Połączenie serwera, który jest już połączony, nie powoduje żadnej akcji.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Odłącz serwer MCP od kampanii #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Odłączenie serwera, który nie jest połączony, nie powoduje żadnej akcji.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Biblioteka mediów kampanii #

Biblioteka mediów przechowuje obrazy, filmy, dokumenty i notatki głosowe, które bot może wysyłać podczas rozmowy.

Wyświetl bibliotekę mediów kampanii #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url to podpisany adres URL przechwycony w momencie przesyłania — może być już nieważny w momencie odczytu; pulpit nawigacyjny podpisuje go ponownie na żądanie.

Prześlij element multimedialny #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Odpowiedź

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Aktualizacja elementu multimedialnego #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Edytuje tylko metadane elementu — aby zastąpić sam plik, usuń element i prześlij nowy.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Usuwanie elementu multimedialnego #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Usunięcie elementu, który już nie istnieje, jest operacją bez efektu (no-op).

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Odpowiedź

{ "success": true, "deleted": true }

Tagi kampanii #

Tag kampanii to etykieta, której uczysz bota, aby przypisywał ją do kontaktu podczas rozmowy — hot-lead, not-interested, booked-a-call. Każdy tag składa się z trzech części:

Nazwy tagów muszą być unikalne w ramach kampanii. Bot przypisuje tagi według nazwy, więc w przypadku dwóch wpisów o tej samej nazwie wynik nie jest określony.

Ustaw wszystkie tagi kampanii #

PUT /campaigns/{campaignId} z tablicą tags.

To zastępuje tagi kampanii dokładnie tym, co wyślesz, co jest tym samym, co robi karta Tagi w panelu nawigacyjnym po zapisaniu zmian. Za każdym razem wysyłaj kompletną tablicę — tag, który pominiesz, zostanie usunięty. Wysłanie [] usuwa je wszystkie.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Odczytaj tagi za pomocą GET /campaigns/{campaignId}.

Dodaj jeden tag #

POST /campaigns/{campaignId}/tags

Dodaje pojedynczy tag bez konieczności ponownego wysyłania reszty. Użyj tego, gdy dodajesz tagi do zestawu, którego nie utworzyłeś w tym żądaniu.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Wysłanie dokładnie tego samego tagu dwukrotnie nie powoduje żadnego efektu za drugim razem. Wysłanie tego samego tag_id z inną nazwą lub opisem spowoduje dodanie drugiego wpisu zamiast edycji pierwszego — użyj poniższego punktu końcowego, aby edytować istniejący tag.

Zaktualizuj lub usuń jeden tag #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Adresują one jeden wpis za pomocą jego tag_id, więc działają tylko na tagach, które zostały z nim utworzone. Jeśli tag nie ma tag_id, zmień go za pomocą powyższego PUT /campaigns/{campaignId} dla całej tablicy.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

tagId, którego nie ma w kampanii, zwraca 404 z "Tag not found in campaign tags".

Przełączanie kanałów kampanii #

POST /campaigns/{campaignId}/channels

Dodaje lub usuwa kanały z tablicy enabled_channels kampanii bez konieczności ponownego przesyłania całej tablicy — jest to bezpieczniejsze niż PUT /campaigns/{campaignId}, gdy w tym samym czasie kampanię może edytować ktoś inny.

Wyślij pojedyncze przełączenie lub partię — nie oba w tym samym żądaniu:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Prawidłowe kanały: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

To zmienia tylko kanały, w których kampania jest reklamowana — nie decyduje o tym, kto odpowiada na dany kanał. Zobacz Typy kampanii powyżej oraz Kierowanie kampanii do kanałów przychodzących poniżej, aby uzyskać więcej informacji.

Komentarz do wiadomości prywatnej (Instagram i Facebook) #

Funkcja „Komentarz do wiadomości prywatnej” zamienia komentarz pod Twoim postem w prywatną rozmowę: ktoś dodaje komentarz, bot wysyła mu wiadomość prywatną (DM), a kampania przejmuje dalszą część konwersacji. Jest ona konfigurowana w całości za pomocą obiektu kampanii, więc nie ma w niej żadnych elementów dostępnych wyłącznie w interfejsie użytkownika.

Najpierw połącz stronę na Facebooku — zobacz Połączenie kanału. Następnie ustaw poniższe pola za pomocą PUT /campaigns/{campaignId}.

Kampania musi być Live. Monitorowanie komentarzy wykrywa tylko te kampanie, których status to Live (wielkość liter nie ma znaczenia — zobacz Typy kampanii). Każdy inny status wyłącza tę funkcję bez powiadomienia, a wymyślony status, taki jak "Active", jest teraz odrzucany z błędem 400 zamiast zapisywany. Prawidłowe statusy to Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent oraz Failed.

Pola

Czyszczenie pola

Te pola są usuwane, a nie ustawiane na null, gdy wysyłasz null, dzięki czemu bot przywraca ustawienia domyślne: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Jeden nieznany klucz odrzuca całe żądanie. PUT /campaigns/{campaignId} weryfikuje całą treść względem listy dozwolonych elementów. Klucz, który nie zostanie rozpoznany, zwraca 400 dla całego żądania — nie jest on ignorowany bez powiadomienia, a żadne inne pola w tej treści nie zostają zapisane.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Widoczna odpowiedź pozostawiona pod komentarzem wymaga funkcji odpowiedzi na komentarze w Twoim planie. Bez niej wiadomość prywatna nadal jest wysyłana, a odpowiedź publiczna jest pomijana.

Optymalizacja kampanii za pomocą AI #

POST /campaigns/{campaignId}/optimize

Uruchamia to samo przepisywanie przez AI, co funkcje „Optymalizuj” i przesyłanie opinii po kliknięciu łapki w dół w panelu nawigacyjnym: pobiera Twoją opinię, przepisuje instrukcje bota i przygotowuje wynik jako nową wersję roboczą do sprawdzenia.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Odpowiedź (202 — przepisywanie odbywa się w tle)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Odpytuj GET /campaigns/{campaignId} i obserwuj test_bot.status: zmienia się na "Optimizing" natychmiast, a następnie z powrotem na "Draft", gdy wynik przepisywania trafi do test_bot. Od tego momentu zachowuje się jak każda wersja robocza w panelu — przejrzyj ją, a następnie opublikuj w panelu, aby zaczęła działać. 409 oznacza, że optymalizacja dla tej kampanii jest już w toku.

Optymalizacja kosztuje kredyty, tak samo jak każda inna operacja AI na Twoim koncie.

Przypisz kontakt do kampanii #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Dodaje istniejący kontakt do kampanii i, jeśli o to poprosisz, natychmiast wysyła wiadomość powitalną kampanii. Jest to sposób na wysłanie zatwierdzonego szablonu WhatsApp kampanii do jednego kontaktu: szablon, z którym kampania została zatwierdzona, należy do tej kampanii, więc nie pojawia się w bibliotece Templates API i nie może zostać wysłany przez /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Odpowiedź

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Kredyty: Wysłanie wiadomości powitalnej w kampanii WhatsApp jest rozliczane tak samo jak wysyłka szablonu, wyceniane według kraju odbiorcy i kategorii szablonu. W innych kanałach wiadomość powitalna jest zwykłą wiadomością wychodzącą.

Kierowanie kampanii do kanałów przychodzących #

Te punkty końcowe zarządzają tym, która kampania odpowiada nowym, nieznanym kontaktom w danym kanale. Preferuj punkty wejścia (Entry Points) dla nowych integracji (zobacz notatkę w sekcji Typy kampanii) — pozostają one przydatne do pracy z kampaniami, które korzystają ze starszego sposobu kierowania, oraz do rozwiązywania konfliktów własności kanału między dwiema kampaniami przychodzącymi.

Przypisywanie kampanii do kanałów przychodzących #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Odpowiedź

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels wyświetla tylko te kanały, które faktycznie zostały skierowane do tej kampanii; failed wyświetla te, które nie zostały skierowane. Jeśli wszystkie żądane kanały zawiodą, samo żądanie również zakończy się niepowodzeniem.

Usuwanie kierowania przychodzącego kampanii #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Odpowiedź

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Reaktywacja uśpionej kampanii #

POST /campaigns/{campaignId}/reactivate

Przywraca kampanię ze stanu Ended, Completed, Paused lub Draft i odzyskuje jej kanały. Działa tylko w przypadku kampanii Incoming from Unknown Contacts lub Combined — kampania, która jest już Live, jest traktowana jako zakończona sukcesem i nie wymaga żadnych działań.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Kanał zajęty już przez agenta innej kampanii pojawi się w channelsBlockedByConflict zamiast powodować niepowodzenie całego wywołania — użyj zatrzymania kolidującej kampanii przychodzącej poniżej, aby najpierw go zwolnić, jeśli chcesz, aby ta kampania go przejęła. Zwracany jest 400 dla typu kampanii, który nie obsługuje reaktywacji, lub statusu, który nie jest jednym z powyższych stanów uśpienia.

Zatrzymaj kolidującą kampanię przychodzącą #

POST /campaigns/{campaignId}/stop-incoming

Zwalnia kanały tej kampanii z INNEJ kampanii, która obecnie je zajmuje, dzięki czemu ta kampania może je przejąć jako następna. Jest to wersja REST tego, co pulpit nawigacyjny robi automatycznie, gdy uruchamiasz kampanię przychodzącą w kanale, który ktoś inny już obsługuje.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels zwraca pustą wartość, gdy ta kampania posiada już wszystkie kanały, które reklamuje — nie ma nic do przejęcia.

Szacunkowe koszty #

Oszacuj koszt uruchomienia kampanii przed jej wysłaniem.

Szacunkowy koszt szablonu WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode wynosi "credits" w zarządzanym kanale WhatsApp. W kanale, w którym Meta obciąża bezpośrednio Twoje własne konto WhatsApp Business, costPerContact, subtotal oraz totalTemplateCost zwracają null — nigdy 0, co byłoby odczytane jako bezpłatne — ponieważ nie ma kwoty kredytu do raportowania.

Szacunkowy koszt SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

Wiadomości SMS są zawsze wysyłane za pośrednictwem Twojego własnego konta Twilio (zobacz dostawca SMS), więc są one zawsze rozliczane bezpośrednio przez Twilio — estimatedCostUsd to szacunkowa wartość tego rachunku Twilio, a nie opłata kredytowa.

Sprawdzanie limitów #

Sprawdź limit przed uruchomieniem, zamiast dowiadywać się o nim po nieudanej wysyłce.

Sprawdzanie w zakresie kampanii #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — czy uruchomienie lub zaplanowanie tej kampanii przekroczyłoby limit wiadomości AI-credit Twojego konta.

GET /campaigns/{campaignId}/limits/messaging — czy przekroczyłoby to dzienny limit wiadomości Twojego konta.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Odpowiedź (limit nieprzekroczony)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

W przypadku przekroczenia limitu zwracany jest 400, a powód znajduje się w error.

Sprawdzanie w zakresie konta #

GET /campaigns/limits/campaigns — czy osiągnięto miesięczny limit tworzenia kampanii w ramach subskrypcji.

GET /campaigns/limits/contacts — czy osiągnięto limit kontaktów w ramach subskrypcji.

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

Odpowiedź

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Sumy statystyk kampanii #

GET /campaigns/stats/totals

Suma wysłanych i otrzymanych odpowiedzi dla każdej kampanii ORAZ każdego agenta AI na Twoim koncie w określonym oknie czasowym — te same liczby, które strona listy kampanii pokazuje obok każdego wiersza, dostępne w jednym wywołaniu zamiast jednego żądania na kampanię.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent stanowi własne podsumowanie, a nie sumę byCampaign — ruch na koncie natywnym dla agenta AI może w ogóle nie dotyczyć żadnej kampanii, więc w przeciwnym razie byłby tutaj niewidoczny.

Testowanie kampanii w środowisku testowym (playground) #

Plac zabaw pozwala na prowadzenie rozmowy z botem kampanii bez korzystania z rzeczywistego kanału lub kontaktu. Jest to ten sam piaskownica, co panel testowy w pulpicie nawigacyjnym, i jest w pełni dostępny przez API.

Przebieg jest następujący: utwórz ukryty kontakt testowy, wyślij wiadomość, a następnie odpytaj kampanię o odpowiedź bota. Odpowiedzi są generowane asynchronicznie, więc trafiają do test_messages w kampanii, a nie w treści odpowiedzi.

Działanie placu zabaw przez API wiąże się z kosztami kredytów. Rozmowa testowa rozpoczęta przy użyciu klucza API jest rozliczana według standardowej stawki za wiadomość AI, tak samo jak rzeczywista odpowiedź, i pojawia się w historii użycia jako zwykły wpis. Testowanie z poziomu pulpitu nawigacyjnego pozostaje bezpłatne. Różnica jest zamierzona: test wykonuje tę samą pracę AI, co działanie na żywo, więc nielimitowany plac zabaw API byłby sposobem na korzystanie z nieograniczonej liczby operacji AI na koszt kogoś innego.

Krok 1 - Utwórz kontakt testowy #

POST /campaigns/{campaignId}/try-out/contact

Tworzy ukryty kontakt testowy i łączy go z kampanią. Wszystkie pola treści są opcjonalne; wszystko, co pominiesz, zostanie zastąpione wbudowaną przykładową tożsamością (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Odpowiedź

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Krok 2 - Zarejestruj przychodzącą wiadomość #

POST /campaigns/{campaignId}/try-out/messages

Dodaje wiadomości do wątku testowego. Wyślij tutaj najpierw wiadomość odwiedzającego, aby pojawiła się w historii rozmowy, którą czyta bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Krok 3 - Poproś bota o odpowiedź #

POST /campaigns/{campaignId}/try-out/test-message

Wysyła wiadomość do potoku AI. Jest to wywołanie, które faktycznie generuje odpowiedź bota.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Odpowiedź

{
  "success": true,
  "data": "Published"
}

"Published" oznacza, że wiadomość trafiła do potoku AI. "Ignored" oznacza, że nowsza wiadomość testowa zastąpiła tę poprzednią — środowisko testowe łączy szybką serię wiadomości w jedną odpowiedź, mniej więcej cztery sekundy po ostatniej wiadomości, podobnie jak w prawdziwej rozmowie czeka się, aż ktoś skończy pisać. Ze względu na to okno łączenia, to wywołanie zwraca wynik po kilku sekundach.

Krok 4 - Odczytanie odpowiedzi #

GET /campaigns/{campaignId}

Odpowiedź bota jest dodawana do tablicy test_messages kampanii. Odpytuj kampanię, aż pojawi się nowy wpis outbound.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Resetowanie środowiska testowego #

POST /campaigns/{campaignId}/try-out/reset

Czyści całą piaskownicę: usuwa kontakt testowy, czyści test_messages i zwalnia blokady odpowiedzi bota. Używaj tego między uruchomieniami testów.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Odpowiedź

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Inne punkty końcowe środowiska testowego #

Błędy API kampanii #

Punkty końcowe kampanii zwracają standardową kopertę błędu:

{
  "success": false,
  "error": "Campaign not found"
}

Wspólne kody, które może zwrócić każdy punkt końcowy — 401, 403 (Twój plan nie obejmuje dostępu do API), 429 (limit szybkości) oraz 500 — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji Błędy i stronicowanie.

Powiązane #

• Skieruj kanał do kampanii — przypisz Instagram, WhatsApp lub dowolny inny kanał do Agenta AI, który ma go obsługiwać, korzystając z Punktów Wejścia (Entry Points).
• Generuj szablony wiadomości uzupełniających za pomocą AI — uruchom zadanie w tle, które przygotuje szablony wiadomości uzupełniających dla kampanii w WhatsApp.
• API FAQ — zarządzaj wpisami pytań i odpowiedzi używanymi w Twoich kampaniach.
• Dostęp do API — wygeneruj swój klucz API.
• Uwierzytelnianie — wszystkie sposoby przekazywania klucza.