Wprowadzenie do API

Publiczne REST API Brosbots pozwala programistycznie robić wszystko to, co panel: budować i zarządzać agentami, uruchamiać kampanie wychodzące, odczytywać rozmowy i zużycie oraz zarządzać numerami, narzędziami, bazami wiedzy i integracjami.

Adres bazowy

https://app.brosbots.com/api/v1

Uwierzytelnianie

Każde żądanie musi zawierać klucz API organizacji w nagłówku X-API-Key. Klucze tworzysz i unieważniasz w panelu: kliknij swoje konto w lewym dolnym rogu paska bocznego, a potem Brosbots API.

curl https://app.brosbots.com/api/v1/agents/summary \
  -H "X-API-Key: bb_live_..."

Traktuj klucze API jak hasła: nie commituj ich do repozytoriów i nie umieszczaj w kodzie frontendowym. Jeśli klucz wycieknie - natychmiast go unieważnij.

ID agenta

Wszędzie, gdzie ścieżka zawiera {agent_id}, możesz podać publiczne ID agenta, np. agent_7fK2mQ9xLp3RtV8wYb1N (znajdziesz je w edytorze agenta, obok jego nazwy - kliknięcie kopiuje), albo jego numer. Oba wskazują tego samego agenta. W odpowiedziach pole workflow_id jest numerem.

Adresy z tej dokumentacji (/agents, /campaigns, /integrations, /triggers, /usage, /reports) zastąpiły wcześniejsze, np. /workflow/{workflow_id}/calls czy /organizations/usage/.... Wcześniejsze adresy nadal działają bez zmian, więc istniejące integracje nie wymagają poprawek. Nowe buduj na adresach z tej dokumentacji. Nazwy pól w treści żądań i odpowiedzi (np. workflow_id, workflow_run_id) się nie zmieniły.

Szybki start: wywołaj połączenie

Rozpocznij połączenie wychodzące istniejącym agentem. phone_number i initial_context to pola obok siebie; zmienne z initial_context agent widzi w promptach jako {{initial_context.<klucz>}}.

curl -X POST "https://app.brosbots.com/api/v1/agents/{agent_id}/calls" \
  -H "X-API-Key: bb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+48123456789",
    "initial_context": { "first_name": "Jan" }
  }'

{ "status": "initiated", "workflow_run_id": 580, "workflow_run_name": "WR-API-4821" }

POST /agents/{agent_id}/conversations nie dzwoni. Tworzy tylko rekord przebiegu dla rozmowy w przeglądarce (mode: webrtc, smallwebrtc) albo czatu (chat).

Odczyt rozmowy

Po zakończeniu rozmowy pobierz przebieg (zebrane dane, czas trwania, koszt, SMS-y, linki do plików):

curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \
  -H "X-API-Key: bb_live_..."

Pole	Znaczenie
`duration_seconds`	Czas trwania w pełnych sekundach; `null`, dopóki rozmowa trwa
`gathered_context`	Dane zebrane przez agenta, w tym `call_disposition`
`recording_download_url` / `transcript_download_url`	Podpisane linki HTTPS do nagrania (WAV) i transkrypcji (tekst). Nie wymagają klucza API
`download_urls_expire_at`	Kiedy linki wygasają (1 h od zapytania). Po nowe linki pobierz przebieg ponownie
`recording_url` / `transcript_url`	Klucze plików w magazynie (np. `recordings/580.wav`), nie adresy URL. Zostają dla zgodności z istniejącymi integracjami

Lista GET /agents/{agent_id}/conversations zwraca dla każdej rozmowy initial_context, gathered_context i duration_seconds, więc nie musisz dociągać szczegółów każdej z nich. Linki do pobrania, logi i SMS-y zwraca tylko widok pojedynczej rozmowy.

Transkrypcja

curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}/transcript" \
  -H "X-API-Key: bb_live_..."

{
  "run_id": 580,
  "segments": [
    { "role": "assistant", "text": "Dzień dobry, tu przychodnia.", "start": "2026-10-05T10:00:01+00:00", "end": "2026-10-05T10:00:02+00:00" },
    { "role": "user", "text": "Chciałam się umówić.", "start": "2026-10-05T10:00:05+00:00", "end": "2026-10-05T10:00:05+00:00" }
  ],
  "download_url": "https://...",
  "expires_at": "2026-10-05T11:00:00+00:00"
}

role to user (rozmówca) albo assistant (agent). Kolejne fragmenty tego samego mówcy są połączone w jedną wypowiedź; start i end to znaczniki czasu jej pierwszego i ostatniego fragmentu (plik nie zapisuje końca wypowiedzi). download_url prowadzi do surowego pliku tekstowego, w którym każdy fragment to osobna linia:

[2026-10-05T10:00:01+00:00] assistant: Dzień dobry,
[2026-10-05T10:00:02+00:00] assistant: tu przychodnia.
[2026-10-05T10:00:05+00:00] user: Chciałam się umówić.

Nagranie

curl "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}/recording?expires_in=600" \
  -H "X-API-Key: bb_live_..."

Zwraca download_url (WAV), content_type i expires_at. expires_in to czas życia linku w sekundach, od 60 do 86400 (domyślnie 3600). Oba endpointy zwracają 404, dopóki rozmowa trwa i plik nie został zapisany, oraz gdy plik usunęła polityka retencji.

Usuwanie rozmowy

curl -X DELETE "https://app.brosbots.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \
  -H "X-API-Key: bb_live_..."

Odpowiedź 204. Usunięcie jest nieodwracalne: nagranie i transkrypcja znikają z magazynu plików, a z rozmowy - initial_context (w tym numer telefonu), gathered_context, logi, SMS-y wysłane w trakcie rozmowy i zapisy dostarczeń integracji. Rozmowa znika z historii, a endpointy przebiegu zwracają dla niej 404. Czas trwania i koszt zostają w rozliczeniach organizacji, bo wymagają tego przepisy księgowe.

Usunięcie nie cofa danych, które już wyszły z Brosbots: payloadów webhooka call.completed, wpisów w CRM czy wierszy w arkuszu. Usuń je u siebie. Rozmowy w toku nie da się usunąć (409).

Konwencje

Ciała żądań i odpowiedzi są w JSON (Content-Type: application/json).
Znaczniki czasu w ISO 8601 ze strefą.
Listy stronicowane parametrami page / limit; odpowiedź zawiera total_count / total_pages.
Błędy używają standardowych kodów HTTP z ciałem JSON:

{ "detail": "czytelny powód błędu" }

Status	Znaczenie
`400`	Błędne żądanie (np. kwota poniżej minimum, zły filtr)
`401`	Brak lub nieprawidłowy klucz API
`404`	Zasób nie istnieje lub należy do innej organizacji
`409`	Konflikt (np. zasób już rozstrzygnięty)
`422`	Błąd walidacji - ciało wskazuje pola
`429`	Wszystkie kanały wychodzące zajęte - odczekaj tyle sekund, ile podaje nagłówek `Retry-After`
`5xx`	Błąd serwera - żądania idempotentne można ponawiać

Limity

API nie ma dziś stałego limitu liczby zapytań na klucz. Kod 429 zwracają endpointy dzwoniące (POST /agents/{agent_id}/calls, POST /triggers/{trigger_id}/calls), gdy wszystkie kanały wychodzące organizacji są zajęte; nagłówek Retry-After podaje, ile sekund odczekać. Połączenie poza godzinami 8:00-21:00 czasu odbiorcy kończy się kodem 409 z nagłówkiem Retry-After i polem detail.retry_at. Numer z listy Nie dzwonić organizacji kończy się kodem 403 z polem detail zaczynającym się od do_not_call. Obsługuj 429 ogólnie: czekaj tyle, ile mówi Retry-After, a gdy nagłówka nie ma - ponawiaj z wykładniczym odstępem. Limit zapytań może zostać wprowadzony w przyszłości.

Interaktywna dokumentacja

Zawsze aktualna, interaktywna referencja (Swagger UI): /api/v1/public-docs, a surowa specyfikacja OpenAPI: /api/v1/public-openapi.json.

Start

Endpointy

Adres bazowy

Uwierzytelnianie

ID agenta

Szybki start: wywołaj połączenie

Odczyt rozmowy

Transkrypcja

Nagranie

Usuwanie rozmowy

Konwencje

Limity

Interaktywna dokumentacja

​Adres bazowy

​Uwierzytelnianie

​ID agenta

​Szybki start: wywołaj połączenie

​Odczyt rozmowy

​Transkrypcja

​Nagranie

​Usuwanie rozmowy

​Konwencje

​Limity

​Interaktywna dokumentacja

Adres bazowy

Uwierzytelnianie

ID agenta

Szybki start: wywołaj połączenie

Odczyt rozmowy

Transkrypcja

Nagranie

Usuwanie rozmowy

Konwencje

Limity

Interaktywna dokumentacja