> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Podstawowe pojęcia
> Mapa wszystkiego na platformie — do czego służy każdy obiekt, gdzie znajduje się w panelu i którego API dotyczy.
ThunderPhone to kompletna platforma do tworzenia, uruchamiania i ulepszania
głosowych agentów AI. Ta strona jest mapą: każdego pojęcia, które napotkasz,
dotyczy jedna krótka sekcja, wraz z odpowiadającym mu widokiem w panelu
i interfejsem API, który go obsługuje. Przejrzyj ją raz, a następnie wracaj,
gdy potrzebujesz wyjaśnienia terminu.
Pasek boczny panelu odzwierciedla tę strukturę:
[Agenci](#agents), [numery telefonów](#phone-numbers),
[widgety internetowe](#web-widgets), [połączenia](#calls),
[bazy wiedzy](#knowledge-bases).
[Monitorowanie na żywo](#live-monitoring) i kampanie
[wychodzące](#campaigns).
[Aplikacje, API, serwery MCP i dostawcy VoIP](#connections), z których
mogą korzystać Twoi agenci.
[Symulacje](#simulations), [eksperymenty](#experiments),
[problemy](#issues), [raporty](#reports),
[obserwowalność](#observability).
[Zespół i role](#team-and-roles), [klucze API](#organizations),
[alerty](#alerts), [rozliczenia](#billing).
[Webhooki](#webhooks) i [narzędzia funkcji](#function-tools) dla
własnego kodu.
***
## Organizacje
**Organizacja** to jednostka dzierżawy. Każdy inny zasób —
agenci, numery telefonów, połączenia, klucze — należy dokładnie do jednej
organizacji. Twoje konto może należeć do wielu organizacji; każda ma własne
saldo, własne klucze i własną listę członków.
Klucz API `sk_live_`, który tworzysz w sekcji **Organizacja → Klucze**,
jest powiązany z jedną organizacją. To powiązanie sprawia, że REST API jest
tak płaskie: nigdy nie umieszczasz identyfikatora organizacji w ścieżkach URL,
ponieważ Twój klucz już ją identyfikuje.
**W panelu:** przełącznik organizacji (w stopce paska bocznego) oraz ustawienia
**Organizacja** — karty Ogólne, Klucze, Alerty, Ustawienia rozliczeń
i Historia rozliczeń.
**W API:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).
***
## Agenci
**Agent** to konfiguracja AI obsługująca połączenie. Obejmuje:
* **Prompt**, który określa, co agent mówi i jak się zachowuje —
w tym działania podczas połączenia, takie jak przekazywanie, naciskanie
klawiszy i rozłączanie, które są zwykłymi liniami promptu, a nie osobną
konfiguracją.
* **Poziom silnika** (`spark`, `bolt`, `storm-*`): Spark jest zoptymalizowany
pod kątem kosztów, Bolt pod kątem szybkości, a Storm pod kątem inteligencji
przy złożonych promptach.
* **Głos** oraz **język podstawowy** i opcjonalne **dodatkowe języki** —
agent przełącza się automatycznie, gdy rozmówca zmienia język. Zobacz
[Obsługiwane języki](/pl/guides/supported-languages).
* Dołączone możliwości: [połączone aplikacje](#connections),
[połączenia API](#connections), [bazy wiedzy](#knowledge-bases),
[serwery MCP](#connections) oraz wbudowane
[narzędzia funkcji](#function-tools).
* Ustawienia zachowania: kolejność mówienia, tryb potwierdzania, ścieżka
w tle, limit czasu oczekiwania.
Edycje w kreatorze **są automatycznie zapisywane jako wersja robocza**; nic nie
trafia do środowiska produkcyjnego, dopóki nie klikniesz **Wdróż**. Każde
wdrożenie jest zapisywane jako migawka na karcie **Historia** kreatora, dzięki
czemu możesz sprawdzić i przywrócić dowolną poprzednią wersję.
**W panelu:** **Agenci głosowi** → kreator agenta
(`/dashboard/agents`). Zobacz
[Utwórz pierwszego głosowego agenta AI](/pl/guides/build-an-agent).
**W API:** [`/v1/agents`](/api-reference/agents) — CRUD,
duplikowanie, przekazywanie, historia wersji i narzędzia pomocnicze promptów.
***
## Numery telefonów
**Numer telefonu** należy do organizacji i kieruje połączenia przychodzące do
agenta (może też obsługiwać połączenia wychodzące). Dwa źródła:
* **Numery demonstracyjne** — rzeczywiste amerykańskie numery udostępniane z
puli ThunderPhone, aktywne w kilka sekund. Tylko dla połączeń przychodzących,
odbierają z krótkim komunikatem głosowym, a panel ogranicza organizację do 10
takich numerów. Idealne do pierwszego testu; nie do środowiska produkcyjnego.
* **Numery VoIP** — dostarczane od własnego dostawcy za pośrednictwem
[połączenia VoIP](#connections). Twilio i Telnyx łączą się bezpośrednio
(Telnyx oferuje konfigurację z przewodnikiem); SignalWire i Vonage pojawią się
wkrótce — obecnie można połączyć je przez ręczną konfigurację SIP, która
akceptuje dowolny trunk SIP. Po zaimportowaniu i zweryfikowaniu numery VoIP
obsługują połączenia przychodzące i wychodzące.
Każdy wiersz numeru umożliwia ustawienie trybu routingu, wybór agenta dla
połączeń przychodzących i oznaczenie numeru.
**W panelu:** **Numery telefonów** (`/dashboard/phone-numbers`).
Zobacz [Uzyskaj numer telefonu](/pl/guides/get-a-phone-number).
**W interfejsie API:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).
***
## Połączenia
Każde połączenie przychodzące, połączenie wychodzące, symulacja i sesja widżetu
stają się **dziennikiem połączenia**. Połączenie zawiera pełną transkrypcję z
oznaczeniami ról, uporządkowaną historię tur rozmowy (w tym wywołania narzędzi),
nagranie, łączny koszt rozliczenia oraz opcjonalną ocenę AI i raporty problemów.
Gdy połączenie jest **na żywo**, możesz je otworzyć i **nasłuchiwać** — dołączasz
po cichu i nikt uczestniczący w połączeniu Cię nie słyszy. Po rozpoczęciu
nasłuchiwania możesz użyć **szeptu**: wpisz instrukcję, która trafia bezpośrednio
do Twojego agenta w trakcie połączenia; rozmówca nigdy jej nie słyszy, a agent
stosuje się do niej na żywo.
**W panelu:** **Historia połączeń** (`/dashboard/call-history`) dla
archiwum i szczegółów poszczególnych połączeń; **Na żywo** dla połączeń w toku.
Zobacz
[Przeglądaj, nasłuchuj i wspieraj swoje połączenia](/pl/guides/review-calls).
**W interfejsie API:** [`/v1/calls`](/api-reference/calls) — lista, transkrypcja,
historia, audio, ocena, eksport;
[`/v1/issue-reports`](/api-reference/issue-reports).
***
## Widżety internetowe
**Widżet internetowy** umożliwia odwiedzającym Twoją witrynę rozmowę z agentem
za pomocą mikrofonu — bez potrzeby posiadania numeru telefonu. Uwierzytelnia się
za pomocą **klucza publikowalnego** (`pk_live_...`), który jest ograniczony do
źródeł z dozwolonych domen, dzięki czemu można go bezpiecznie używać w kodzie
po stronie klienta.
Klucze działają w jednym z dwóch trybów: `agent` (statycznie powiązany z jednym
agentem) lub `webhook` (Twój serwer wybiera konfigurację dla każdego
odwiedzającego — zobacz
[Dynamiczna konfiguracja dla każdego połączenia](/pl/guides/dynamic-call-config)).
Sesje widżetu korzystają z tej samej infrastruktury połączeń co połączenia
telefoniczne.
**W panelu:** **Widżety internetowe** (`/dashboard/web-widgets`) —
twórz widżety, ustawiaj tryb i agenta, zarządzaj dozwolonymi domenami oraz
kopiuj fragment kodu do osadzenia. Zobacz
[Utwórz widżet internetowy](/pl/guides/embed-a-web-widget-dashboard).
**W interfejsie API:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions) oraz
[dokumentacja SDK widżetu](/pl/widget/overview).
***
## Bazy wiedzy
**Baza wiedzy** to zestaw dokumentów, które Twój agent może przeszukiwać w
trakcie połączenia, aby oprzeć na nich swoje odpowiedzi — przesyłaj pliki
bezpośrednio lub importuj je z Google Drive, a następnie przypisz bazę wiedzy
do agenta w kreatorze. Agent wyszukuje w niej za pomocą wbudowanego narzędzia
wyszukiwania, gdy wymaga tego rozmowa.
**W panelu:** **Wiedza** (`/dashboard/knowledge`) dla biblioteki
dokumentów; sekcja **Wiedza** w kreatorze, aby przypisać ją do agenta. Zobacz
[Dodaj bazę wiedzy do swojego agenta](/pl/guides/knowledge-base).
***
## Połączenia
Połączenia umożliwiają agentom kontakt ze światem zewnętrznym. Cztery rodzaje, jedna
grupa na pasku bocznym:
* **Aplikacje** (`/dashboard/app-connections`) — połączenia OAuth z
Slack, HubSpot, Salesforce, Kalendarzem Google, Arkuszami Google i
Cal.com. Połącz raz, a następnie włączaj narzędzia dla poszczególnych operacji
(wyślij wiadomość Slack, zaktualizuj lub utwórz kontakt HubSpot, zarezerwuj termin w Cal.com…)
dla dowolnego agenta. Zobacz [Połącz aplikacje](/pl/guides/connect-apps).
* **API** (`/dashboard/api-connections`) — przekształć dowolne API HTTP w
działanie agenta. Wklej polecenie cURL, a kreator AI przygotuje definicję
narzędzia, lub utwórz ją ręcznie; przycisk **Testuj żądanie** wykonuje
wywołanie w piaskownicy przed wdrożeniem. Zobacz
[Połączenia API](/pl/guides/api-connections) — widok panelu dla
[`/v1/integrations`](/api-reference/integrations).
* **MCP** (`/dashboard/mcp-connections`) — dodaj serwer Model Context
Protocol za pomocą adresu URL i pozwól agentowi używać udostępnianych przez niego narzędzi.
Zobacz [Dodaj serwer MCP](/pl/guides/mcp-servers).
* **VoIP** (`/dashboard/voip-connections`) — dane uwierzytelniające dostawcy do
[korzystania z własnych numerów telefonów](#phone-numbers). Zobacz
[Połącz dostawcę VoIP](/pl/guides/voip-providers).
**W API:** [`/v1/integrations`](/api-reference/integrations) i
[`/v1/voip-connections`](/api-reference/voip-connections); zobacz także
[Utwórz integrację narzędzia](/pl/guides/build-tool-integration).
***
## Kampanie
**Kampania** wykonuje połączenia wychodzące na dużą skalę: prześlij plik CSV z
kontaktami, wybierz agenta i numer, z którego będą wykonywane połączenia, a następnie ustaw okno
połączeń (dni i godziny z uwzględnieniem strefy czasowej), współbieżność oraz zasady ponawiania
(maksymalną liczbę prób i wyniki — brak odpowiedzi, poczta głosowa, niepowodzenie — dla których
połączenia mają być ponawiane). Kampania przechodzi przez listę i zapisuje każde połączenie
w Historii połączeń.
**W panelu:** **Kampanie** (`/dashboard/campaigns`). Zobacz
[Uruchom kampanię połączeń wychodzących](/pl/guides/outbound-campaigns).
**W przypadku jednorazowych połączeń programistycznych:** użyj
[API połączeń wychodzących](/pl/guides/place-outbound-calls).
***
## Monitorowanie na żywo
**Na żywo** pokazuje każde połączenie trwające w organizacji i umożliwia
otwarcie dowolnego z nich, aby [nasłuchiwać i szeptać](#calls) w czasie rzeczywistym. To
interfejs nadzoru: obserwuj pierwszy rzeczywisty ruch nowego promptu albo
monitoruj uruchomioną kampanię.
**W panelu:** **Na żywo** (`/dashboard/live`). Zobacz
[Obserwuj i nadzoruj połączenia na żywo](/pl/guides/monitor-live-calls).
***
## Symulacje
**Symulacja** to rozmówca AI prowadzący rzeczywistą rozmowę z Twoim
agentem — ta sama ścieżka telefoniczna, rzeczywista transkrypcja, rzeczywista ocena — dzięki czemu
możesz testować przed wdrożeniem i po nim. Skieruj ją do agenta lub numeru
telefonu, samodzielnie opisz scenariusz rozmówcy albo **generuj scenariusze
za pomocą AI** na podstawie promptu agenta (w tym przypadki brzegowe, jeśli o nie poprosisz),
i obserwuj połączenie na żywo.
Scenariusze są grupowane w **pakiety**, które ustalają minimalny współczynnik zaliczenia i mogą
blokować wydania w CI; regresje względem zaakceptowanej linii bazowej są raportowane
dla każdego scenariusza.
**W panelu:** **Symulacje** (`/dashboard/simulations`) oraz
przycisk **Symulacja** w kreatorze agenta. Zobacz
[Symuluj połączenie](/pl/guides/simulate-a-call).
**W API:** [`/v1/test-calls`](/api-reference/test-calls) oraz
uruchamianie pakietów — zobacz [Przetestuj agenta kompleksowo](/pl/guides/test-agents).
***
## Eksperymenty
**Eksperyment** przeprowadza testy A/B konfiguracji agentów na rzeczywistym ruchu:
zdefiniuj warianty (różne prompty, silniki lub ustawienia), rozdziel
między nie ruch i porównaj wyniki dla każdego wariantu. Użyj go zamiast
ręcznie tworzyć logikę segmentacji w webhooku.
**W panelu:** **Eksperymenty** (`/dashboard/experiments`) oraz
karta **A/B** w kreatorze agenta. Zobacz
[Eksperymenty (testy A/B)](/pl/guides/experiments-ab-testing).
## Problemy
**Problem** to oznaczony problem w konkretnym połączeniu — zgłoszony przez
osobę weryfikującą lub wykryty przez ocenę AI. Problemy obejmują poziom ważności,
źródło i status, a strona Problemy jest kolejką weryfikacji: filtruj,
sprawdzaj problematyczne połączenia i śledź poprawki.
**W panelu:** **Problemy** (`/dashboard/issues`) oraz oznaczanie problemów dla poszczególnych
połączeń w Historii połączeń. Zobacz [Weryfikacja problemów](/pl/guides/issues).
**W API:** [`/v1/issue-reports`](/api-reference/issue-reports).
***
## Raporty
**Raport** odpowiada na pytanie w języku naturalnym dotyczące danych o połączeniach
(„Jakie były trzy główne powody, dla których rozmówcy prosili o rozmowę z człowiekiem
w zeszłym tygodniu?”) za pomocą analizy napisanej przez AI, ograniczonej do wybranych
agentów i zakresu dat.
**W panelu:** **Raporty** (`/dashboard/reports`). Zobacz
[Raporty](/pl/guides/reports).
***
## Obserwowalność
**Obserwowalność** to obszar metryk: liczba połączeń, wyniki i
jakość w czasie, z możliwością filtrowania według agenta i przedziału czasu oraz
eksportu do dalszej analizy.
**W panelu:** **Obserwowalność** (`/dashboard/observability`).
Zobacz [Obserwowalność](/pl/guides/observability).
***
## Alerty
**Reguła alertu** monitoruje metrykę (wskaźnik sukcesu, wskaźnik niepowodzeń,
średni wynik, liczbę połączeń, regresje pakietu) w przedziale czasu i
uruchamia się, gdy przekroczy ona określony próg. Powiadomienia są wysyłane e-mailem i do
Slacka oraz emitują zdarzenie `alert.triggered` do
Twoich [punktów końcowych webhooków](/pl/webhooks/endpoints).
**W panelu:** **Organizacja → Alerty**. Zobacz
[Alerty](/pl/guides/alerts).
***
## Webhooki
ThunderPhone wysyła **webhooki HTTP POST** na Twój serwer, gdy coś
dzieje się w trakcie i po połączeniu. Dwa modele dostarczania:
* **Punkty końcowe webhooków** (zalecane): zarządzaj wieloma adresami URL w
[`/v1/developer/webhook-endpoints`](/pl/webhooks/endpoints), korzystając z
sekretów dla poszczególnych punktów końcowych i subskrypcji zdarzeń dla poszczególnych punktów końcowych.
* **Starszy webhook z jednym adresem URL**: jeden adres URL na organizację. Zarządzany w
[`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
lub w **Organizacja → Ogólne**. Zachowany dla zgodności wstecznej.
Zdarzenia dzielą się na dwie klasy:
* **Zdarzenia blokujące** oczekują, że Twój serwer odpowie konfiguracją,
która wpływa na trwające połączenie — są to
[zdarzenia połączeń przychodzących](/pl/webhooks/call-incoming)
(`telephony.incoming` / `web.incoming`). Masz do 10 sekund
na odpowiedź; po przekroczeniu limitu czasu połączenie obsługuje statycznie przypisany agent.
* **Zdarzenia nieblokujące** to powiadomienia typu fire-and-forget, ponawiane
z wykładniczym opóźnieniem — zobacz
[semantykę dostarczania](/pl/webhooks/overview).
Każde żądanie zawiera podpis HMAC-SHA256 w
`X-ThunderPhone-Signature`. Zobacz
[Weryfikacja podpisu](/pl/webhooks/overview).
***
## Narzędzia funkcji
**Narzędzie funkcji** to punkt końcowy HTTP, który agent może wywołać
w trakcie rozmowy. Przekazujesz ThunderPhone schemat funkcji w stylu OpenAI
wraz z adresem URL punktu końcowego; agent decyduje, kiedy go wywołać, a
ThunderPhone wysyła podpisane żądanie HTTP ze swoich serwerów i przekazuje
wynik z powrotem agentowi.
Agenci mają także **wbudowane funkcje połączeń** — przekazywanie połączenia,
wysyłanie danych klawiatury (DTMF), kończenie połączenia, oczekiwanie na linii — które
włączasz za pomocą zwykłych linii promptu zamiast definicji narzędzi.
**W panelu:** sekcja **Połączenia API** w kreatorze (zobacz
[Połączenia](#connections)).
**W API:** [`/v1/integrations`](/api-reference/integrations) oraz
[specyfikacja narzędzi funkcji](/pl/tools/overview).
***
## Zespół i role
Każda organizacja ma listę członków z dwiema rolami: **Członkowie** tworzą
i obsługują agentów; **Administratorzy** zarządzają także zespołem i rozliczeniami.
Zapraszaj e-mailem — zaproszenia wygasają po 7 dniach i można je cofnąć;
menu ⋯ w wierszu członka zmienia role lub usuwa daną osobę. Logowanie jednokrotne
można skonfigurować dla całej organizacji — zobacz [SSO](/pl/guides/sso).
**W panelu:** **Organizacja → Ogólne**. Zobacz
[Zaproś swój zespół](/pl/guides/invite-your-team).
**W API:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/invites).
***
## Rozliczenia
ThunderPhone działa w modelu **przedpłaconym**. Każda organizacja ma saldo w USD; połączenia obciążają je według stawki agenta za minutę (poziom silnika plus dopłaty —
kreator na bieżąco pokazuje łączną stawkę podczas zmiany ustawień, a
[języki premium](/pl/guides/supported-languages) dodają 2¢/min). Gdy saldo
spadnie do zera, połączenia przychodzące są odrzucane, a połączenia wychodzące zwracają
`402 Payment Required`.
Doładuj saldo ręcznie lub włącz **automatyczne doładowanie** z progiem salda, kwotą
doładowania i opcjonalnym miesięcznym limitem wydatków — aby połączenie
nigdy nie urwało się w połowie zdania.
**W panelu:** **Organizacja → Ustawienia rozliczeń** oraz
**Historia rozliczeń**. Zobacz
[Dodawanie środków i włączanie automatycznego doładowania](/pl/guides/billing-and-topups).
**W API:** [`/v1/billing`](/api-reference/billing).
***
## Kopilot w aplikacji
Panel zawiera wbudowanego **kopilota** — zapytaj go „jak zrobić X”,
a odpowie na podstawie tej dokumentacji, zaoferuje instrukcje krok po kroku,
które wyróżniają rzeczywiste kontrolki, oraz może ponownie odtworzyć dowolny
z przewodników. To najszybszy sposób na znalezienie kontrolki wspomnianej na tej stronie.
Zobacz [Zapytaj kopilota w aplikacji](/pl/guides/ask-the-copilot).
***
## Wszystko razem
Kreator w pięciu krokach: agent → rozliczenia → numer → symulacja → przegląd.
To samo pierwsze połączenie w czterech wywołaniach REST.
Utwórz agenta, zasil saldo, uzyskaj numer, symuluj i przeglądaj połączenia.
Aplikacje OAuth, niestandardowe API, serwery MCP i dostawcy VoIP.
Raporty, obserwowalność, eksperymenty, problemy i alerty.
Zaproszenia i role, klucze API, bezpieczeństwo oraz SSO.
Receptury API: połączenia przychodzące, wychodzące, dynamiczna konfiguracja, narzędzia, testowanie.
Poprawnie skonfiguruj weryfikację HMAC raz i używaj jej wszędzie.