API transmisji #

Transmisja to jedna wysyłka wychodząca: odbiorcy, wiadomość otwierająca, jeden kanał i harmonogram. Opcjonalnie określa również agenta AI, który obsługuje otrzymane odpowiedzi. API transmisji pozwala tworzyć, wyceniać, uruchamiać i monitorować te wysyłki z poziomu własnego kodu, zamiast korzystać z pulpitu nawigacyjnego. Informacje o samym produkcie znajdują się w przewodniku po transmisjach.

• Podstawowy adres URL — https://api.youraiconnector.com/v1
• Uwierzytelnianie — Twój klucz API (zobacz Uwierzytelnianie)
• Błędy i stronicowanie — zobacz Błędy i stronicowanie

Wszystkie poniższe przykłady pokazują formularz zapytania ?apiKey= w cURL oraz nagłówek X-API-Key w JavaScript i Pythonie — oba działają w każdym punkcie końcowym.

W eksploratorze API. Każdy punkt końcowy na tej stronie znajduje się w opublikowanej specyfikacji OpenAPI, dzięki czemu możesz przeglądać jego dokładne pola i uruchamiać zapytania na żywo w eksploratorze API.

Jak skonstruowana jest wysyłka #

Wysłanie transmisji składa się z czterech wywołań, a nie jednego:

1. Utwórz transmisję z jej odbiorcami, kanałem i harmonogramem — zaczyna się jako Draft.
2. Ustaw wiadomość otwierającą. W przypadku WhatsApp Business oznacza to przesłanie szablonu do zatwierdzenia (lub wybranie takiego, który został już zatwierdzony). Na każdym innym kanale jest to zwykły tekst.
3. Oszacuj koszt, jeśli chcesz sprawdzić cenę przed wydaniem jakichkolwiek środków (opcjonalnie).
4. Uruchom ją. Uruchomienie przeprowadza pełną kontrolę — odbiorców, wiadomości, zatwierdzenia szablonu, połączonego nadawcy — i albo rozpoczyna wysyłkę, albo informuje dokładnie, czego brakuje.

Nic nie zostanie wysłane, dopóki nie wywołasz uruchomienia.

Obiekt transmisji #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Znaczniki czasu są zwracane jako milisekundy epoki (execution_date, created_at, last_modified_at, …), a każde odniesienie do kontaktu jest zwracane jako ciąg ścieżki, np. contacts/uid_whatsapp_15551234567.

Pola, które ustawiasz #

Wszystko, co wyślesz jako user_id, id, status lub source_campaign_id, jest ignorowane przy tworzeniu i usuwane przy aktualizacji — status zmienia się tylko poprzez poniższe punkty końcowe uruchamiania, wstrzymywania i wznawiania.

Pola utrzymywane przez platformę #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, liczniki partii oraz contacts (poszczególne kontakty dołączone z pulpitu nawigacyjnego, odczytywane jako ciągi ścieżek). Odczytuj je, nie zapisuj.

Statusy #

Utwórz transmisję #

POST /broadcasts — tworzy Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Odpowiedź (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Wyświetl listę transmisji #

GET /broadcasts — każda transmisja na koncie, od najnowszej. |

Parametry zapytania

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Odpowiedź (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Pobierz transmisję #

GET /broadcasts/{broadcastId} — zwraca { "success": true, "broadcast": { ... } }. Użyj tego, aby odpytywać trwającą wysyłkę: total_contacts_sent, unique_contacts_replied, overall_reply_rate oraz credits_used aktualizują się w trakcie jej trwania. |

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

Transmisja, która nie istnieje na Twoim koncie, zwraca 404.

Zaktualizuj transmisję #

PUT /broadcasts/{broadcastId} — wyślij tylko te pola, które chcesz zmienić. Możesz również odwołać się do pojedynczego klucza wewnątrz zagnieżdżonego obiektu za pomocą ścieżki kropkowej, np. "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Puste ciało żądania zwraca 400. Warto znać dwie zasady:

• opener_media działa na zasadzie wszystko albo nic. Wyślij kompletny obiekt lub null, aby usunąć załącznik. Ścieżka kropkowa do niego (opener_media.name) zostanie odrzucona z błędem 400, ponieważ częściowo zaktualizowany załącznik opisywałby plik, którego nie ma.
• Statusu nie można edytować. Użyj uruchomienia, wstrzymania i wznowienia.

Wiadomość otwierająca #

Każda transmisja zawiera swój element otwierający w whats_app_template. To, co to oznacza, zależy od kanału:

• WhatsApp Business — musi to być szablon zatwierdzony przez WhatsApp. Użyj jednego z dwóch poniższych punktów końcowych.
• Każdy inny kanał (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — pole body tego samego elementu to po prostu tekst, który zostanie wysłany. Przesłanie go przez poniższy punkt końcowy zapisuje go i oznacza jako gotowy, bez udziału WhatsApp.

Prześlij szablon do zatwierdzenia #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Odpowiedź (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status to odpowiedź WhatsApp: pending podczas sprawdzania, approved gdy jest gotowy do użycia, rejected jeśli został odrzucony. W przypadku kanału innego niż WhatsApp, odpowiedź wraca natychmiast jako approved z template_sid: null — nie ma nic do sprawdzania.

Co może Cię powstrzymać:

• Przesłanie szablonu, gdy poprzedni jest w trakcie sprawdzania, zwróci 400. Najpierw poczekaj na decyzję.
• Edycja zatwierdzonego szablonu sprawia, że poprzednia wersja pozostaje aktywna do momentu zatwierdzenia nowej, dzięki czemu trwająca transmisja nigdy nie traci swojego elementu otwierającego.
• W przypadku numeru WhatsApp połączonego bezpośrednio przez Meta, transmisji z załączonym obrazem lub wideo nie można przesłać (400) — załączniki są obsługiwane w zarządzanym kanale WhatsApp Business oraz w WhatsApp Web.

Użyj szablonu, który został już zatwierdzony #

POST /broadcasts/{broadcastId}/template/select — kopiuje zatwierdzony już szablon z Twojej biblioteki szablonów do transmisji, więc nie trzeba na nic czekać.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Odpowiedź (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

Zatwierdzenie jest weryfikowane po naszej stronie na podstawie rekordu w bibliotece — przesyłasz tylko identyfikator. Otrzymasz 400, jeśli transmisja nie jest szkicem WhatsApp, jeśli szablon nie jest zatwierdzony, jeśli jest to szablon uzupełniający, a nie otwierający, lub jeśli transmisja zawiera załącznik (szablony z biblioteki są tylko tekstowe). Identyfikator szablonu, którego nie ma na Twoim koncie, zwróci 404.

Oszacuj koszt #

POST /broadcasts/{broadcastId}/estimate-cost — wycenia wysyłkę przed jej zatwierdzeniem. Dostępne dla transmisji whatsapp i sms; każdy inny kanał zwróci 400. Transmisja wymaga list_id, ponieważ szacunek uwzględnia grupę odbiorców.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

Odpowiedź WhatsApp (200) — kredyty, z podziałem na kraj docelowy:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

Odpowiedź SMS (200) — dolary amerykańskie, na podstawie aktualnych cen Twilio dla Twojego własnego konta Twilio:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Przeczytaj billing_mode, zanim wyświetlisz numer. Informuje on, kto jest obciążany kosztami:

SMS bez podłączonych danych uwierzytelniających Twilio nadal zwraca liczbę segmentów, z estimatedCostUsd: 0 — nie ma żadnych cen do sprawdzenia.

Uruchom transmisję #

POST /broadcasts/{broadcastId}/launch

Uruchomienie najpierw sprawdza wszystko, a dopiero potem kontynuuje transmisję. Nie ma możliwości częściowego uruchomienia: albo się rozpocznie, albo nic się nie zmieni i otrzymasz komunikat o błędzie z wyjaśnieniem przyczyny.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Odpowiedź (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status to miejsce, w którym wylądowała transmisja:

• Scheduled — execution_date jest w przyszłości.
• Sending — rozpoczęła się teraz.
• Pending Approval — szablon WhatsApp jest nadal w trakcie weryfikacji. Wyśle się automatycznie, gdy tylko szablon zostanie zatwierdzony; nie wywołuj ponownie uruchomienia.

Uruchomić można tylko transmisję Draft (lub Pending Approval, której szablon został w międzyczasie zatwierdzony) — każda inna zwróci 400.

Dlaczego uruchomienie zostało odrzucone #

Każdy z tych przypadków zwraca 400 wraz z komunikatem error napisanym prostym językiem:

Wstrzymywanie i wznawianie #

POST /broadcasts/{broadcastId}/pause zatrzymuje transmisję Sending lub Scheduled i usuwa wszystko, co znajduje się w kolejce.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Wstrzymanie transmisji Pending Approval powoduje jej powrót do stanu Draft — nic nie zostało jeszcze zaplanowane, więc nie ma czego wznawiać. Każdy inny status zwraca 400.

POST /broadcasts/{broadcastId}/resume restartuje transmisję Paused:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Odpowiedź (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Wznawia ją do stanu Sending lub z powrotem do Scheduled, jeśli jej execution_date wciąż przypada w przyszłości. Wznowić można tylko transmisję Paused.

Kontynuuj wysyłkę po wstrzymaniu z powodu niskiego zaangażowania #

POST /broadcasts/{broadcastId}/override-engagement-guard

Podczas gdy transmisja jest wysyłana w partiach, mierzymy, ile osób odpowiedziało na każdą z nich, zanim rozpoczniemy kolejną. Jeśli prawie nikt nie odpowiada, transmisja wstrzymuje się automatycznie — wysyłka, która jest kontynuowana w ciszy, to najszybszy sposób na przefiltrowanie lub zablokowanie numeru. Służy do tego przycisk Kontynuuj mimo wszystko w panelu nawigacyjnym.

Ponieważ wskaźnik odpowiedzi, który spowodował wstrzymanie, nie może się zmienić, gdy transmisja jest zatrzymana, zwykłe wznowienie spowodowałoby ponowne wstrzymanie przy następnym sprawdzeniu. Ten punkt końcowy to decyzja o kontynuowaniu mimo wszystko: rejestruje on obejście dla tej konkretnej transmisji i znosi wstrzymanie w tym samym wywołaniu, jeśli transmisja została wstrzymana z powodu niskiego zaangażowania.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Odpowiedź (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — transmisja została wstrzymana z powodu niskiego zaangażowania i jest teraz ponownie uruchomiona; status to stan, do którego została wznowiona.
• resumed: false — nic nie zostało zniesione, obejście jest po prostu rejestrowane do przyszłych kontroli. Otrzymasz to, jeśli transmisja nigdy nie została wstrzymana lub została wstrzymana z innego powodu (wstrzymałeś ją ręcznie, osiągnięto limit wysyłki lub zbyt wiele wysyłek zakończyło się błędem). Takie wstrzymania nie są tutaj znoszone — wznów ją samodzielnie po usunięciu przyczyny.

Obejście dotyczy tylko tej transmisji. Nie jest to ustawienie konta i można je bezpiecznie wywołać dwukrotnie.

Duplikuj transmisję #

POST /broadcasts/{broadcastId}/duplicate — kopiuje odbiorców, wiadomość i ustawienia do nowej Draft. Wszystko, co dotyczy poprzedniego uruchomienia (liczniki, partie, harmonogram, statystyki odpowiedzi), zaczyna się od nowa.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Odpowiedź (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Kopia nigdy nie dziedziczy aktywnego zatwierdzenia WhatsApp: w kopii WhatsApp szablon wymaga Twojego potwierdzenia, a w kopii na inny kanał jest usuwany, a tekst staje się zwykłym otwieraczem. Kopiowanie do SMS usuwa również wszelkie załączniki, ponieważ SMS nie może ich wysyłać.

Usuń transmisję #

DELETE /broadcasts/{broadcastId}

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

Transmisja Sending lub Scheduled została odrzucona z błędem 400 — najpierw ją wstrzymaj.

Transmisje odzwierciedlające kampanię klasyczną #

Kampanie klasyczne, które wysyłają wiadomości, pojawiają się również w Transmisjach, a API zwraca je wraz z natywnymi transmisjami (posiadają one source_campaign_id). Zachowują się one nieco inaczej, ponieważ to kampania pozostaje nadrzędna:

• Edycja grupy odbiorców, wiadomości lub harmonogramu działa i jest zapisywana w kampanii.
• Kanał, agent odpowiedzi, załącznik oraz wszystkie liczniki uruchomień są tutaj tylko do odczytu — otrzymasz 400, jeśli spróbujesz je zmienić. Zmień je w kampanii.
• Uruchomienie zwraca 400, kierując do edytora kampanii.
• Wstrzymanie i wznowienie działają i mają wpływ na kampanię.
• Usunięcie zwraca 400 — zamiast tego usuń kampanię, a jej wpis w Transmisjach zniknie wraz z nią.
• Duplikowanie tworzy niezależną transmisję natywną, co jest zalecanym sposobem przenoszenia sprawdzonych kampanii.

Błędy #

Nieudane żądania zwracają {"success": false, "error": "<message>"} z następującymi statusami:

Następne kroki #

• Przewodnik po transmisjach — produkt stojący za tymi punktami końcowymi, w tym informacje o tempie wysyłki i zachowaniach związanych z bezpieczeństwem
• API kontaktów — budowanie listy, do której wysyłana jest transmisja
• API szablonów — zarządzanie zatwierdzonymi szablonami WhatsApp, które możesz wybrać
• API webhooków — subskrybuj Broadcast Started i Broadcast Completed zamiast odpytywać API