Getting Started

Podstawowe pojęcia

Mapa wszystkich elementów platformy — do czego służy każdy obiekt, gdzie znajduje się w panelu i które API go obsługuje.

ThunderPhone to kompletna platforma do tworzenia, uruchamiania i ulepszania agentów głosowych AI. Ta strona to mapa: każde pojęcie, które napotkasz, ma własną krótką sekcję, wraz z obszarem panelu i interfejsem API, który je obsługuje. Przejrzyj ją raz, a następnie wracaj do niej, gdy jakieś pojęcie będzie wymagało wyjaśnienia.

Pasek boczny panelu odzwierciedla tę strukturę:

Organizacje#

Organizacja jest jednostką 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 interfejs REST API jest tak prosty: 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 Moje konto, Ogólne, Klucze, Alerty, Ustawienia rozliczeń i Historia rozliczeń. Zobacz dokumentację ustawień organizacji.

W API: /v1/orgs, /v1/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 przekierowania, naciskanie klawiszy i rozłączanie, które są zwykłymi liniami promptu, a nie oddzielną 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 wraz z językiem głównym i opcjonalnymi dodatkowymi językami — agent przełącza się automatycznie, gdy rozmówca zmienia język. Zobacz Obsługiwane języki.
• Dołączone możliwości: połączone aplikacje, połączenia API, bazy wiedzy, serwery MCP oraz wbudowane narzędzia funkcji.
• Ustawienia zachowania: kolejność mówienia, tryb potwierdzeń, ścieżka w tle, limit czasu oczekiwania.

Edycje w kreatorze są automatycznie zapisywane jako wersja robocza; nic nie zostaje wdrożone, 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 swojego pierwszego agenta głosowego.

W API: /v1/agents — CRUD, duplikowanie, przekierowywanie, historia wersji i pomocniki promptów.

Głosy#

Biblioteka głosów zawiera głosy, których może używać agent, ich odtwarzalne próbki, obsługiwane języki, grupy płci i akcentów oraz wszelkie dopłaty za głosy lub języki premium. Płatny próbnik może przed wyborem syntezować własną frazę o długości 1–500 znaków.

Uprawnione organizacje mogą również tworzyć głosy niestandardowe na podstawie krótkiej próbki WAV lub MP3. Głosy niestandardowe mają limit oraz asynchroniczny status tworzenia; gdy są gotowe, pojawiają się w tym samym selektorze agentów co głosy z biblioteki.

W panelu: Głosy (/dashboard/voices). Zobacz Biblioteka głosów i głosy niestandardowe.

W API: /v1/voices, próbki głosów oraz głosy niestandardowe.

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 — prawdziwe numery w USA 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, ale nie do środowiska produkcyjnego.
• Numery VoIP — dostarczane od własnego dostawcy przez połączenie VoIP. Twilio i Telnyx łączą się bezpośrednio (Telnyx oferuje konfigurację z przewodnikiem); SignalWire i Vonage będą dostępne wkrótce — obecnie można połączyć je przez ręczną konfigurację SIP, która obsługuje dowolny trunk SIP. Po zaimportowaniu i zweryfikowaniu numery VoIP obsługują połączenia przychodzące i wychodzące.

Każdy wiersz numeru pozwala ustawić tryb routingu, wybrać agenta dla połączeń przychodzących i oznaczyć numer etykietą.

W panelu: Numery telefonów (/dashboard/phone-numbers). Zobacz Uzyskaj numer telefonu.

W API: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Połączenia#

Każde połączenie przychodzące, połączenie wychodzące, symulacja i sesja widżetu stają się logiem połączenia. Połączenie zawiera pełną transkrypcję z oznaczeniem ról, ustrukturyzowaną historię tur (w tym wywołania narzędzi), nagranie, łączny koszt rozliczeniowy oraz opcjonalne oceny AI i raporty problemów.

Gdy połączenie jest na żywo, możesz je otworzyć i nasłuchiwać — dołączasz po cichu i nikt w połączeniu Cię nie słyszy. Po rozpoczęciu nasłuchiwania możesz użyć szeptu: wpisz instrukcję, która trafi bezpośrednio do agenta w trakcie połączenia; rozmówca nigdy jej nie usłyszy, a agent zastosuje ją 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, odsłuchuj i prowadź swoje połączenia.

W API: /v1/calls — lista, transkrypcja, historia, audio, ocena, eksport; /v1/issue-reports.

Portale klientów#

Portal klienta to oznakowany marką widok historii połączeń tylko do odczytu dla klienta zewnętrznego. Administratorzy organizacji wybierają agentów, których połączenia są wyświetlane, dodają zatwierdzone adresy e-mail widzów, przesyłają logo i kolor akcentujący oraz opcjonalnie weryfikują domenę niestandardową. Widzowie portalu mogą sprawdzać szczegóły połączeń, transkrypcje i dostępne nagrania bez otrzymywania dostępu do panelu.

W panelu: Portale klientów (/dashboard/client-portals). Zobacz Portale klientów.

W API: /v1/client-portals do zarządzania przez administratorów.

Widżety internetowe#

Widżet internetowy zapewnia odwiedzającym Twoją witrynę rozmowę z agentem przez mikrofon — bez potrzeby podawania numeru telefonu. Uwierzytelnia się za pomocą klucza publicznego (pk_live_...), który jest ograniczony do dozwolonych domen pochodzenia, 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 przypisany do jednego agenta) lub webhook (Twój serwer wybiera konfigurację dla każdego odwiedzającego — zobacz Dynamiczna konfiguracja dla każdego połączenia). Sesje widżetów korzystają z tej samej infrastruktury połączeń co rozmowy 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.

W API: /v1/publishable-key, /v1/mic-session oraz dokumentację Widget SDK.

Bazy wiedzy#

Baza wiedzy to zbiór dokumentów, które agent może przeszukiwać w trakcie rozmowy, aby oprzeć swoje odpowiedzi na źródłach — prześlij pliki, wklej tekst lub zaimportuj strony internetowe według adresu URL, a następnie przypisz bazę wiedzy do agenta w kreatorze. Agent wyszukuje w niej informacje 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ć bazę do agenta. Zobacz Dodaj bazę wiedzy do swojego agenta.

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, Google Calendar, Google Sheets i Cal.com. Połącz raz, a następnie włączaj narzędzia dla poszczególnych operacji (wyślij wiadomość Slack, utwórz lub zaktualizuj kontakt HubSpot, zarezerwuj termin w Cal.com…) dla dowolnego agenta. Zobacz Połącz aplikacje.
• API (/dashboard/api-connections) — przekształć dowolne HTTP API w działanie agenta. Wklej polecenie cURL, a kreator AI przygotuje definicję narzędzia, lub utwórz ją ręcznie; przycisk Testuj żądanie wykonuje połączenie w środowisku testowym przed wdrożeniem. Zobacz Połączenia API — interfejs panelu dla /v1/integrations.
• MCP (/dashboard/mcp-connections) — dodaj serwer Model Context Protocol według adresu URL i pozwól agentowi korzystać z udostępnianych przez niego narzędzi. Zobacz Dodaj serwer MCP.
• VoIP (/dashboard/voip-connections) — dane uwierzytelniające dostawcy do korzystania z własnych numerów telefonów. Zobacz Połącz dostawcę VoIP.

ThunderPhone udostępnia także własny punkt końcowy MCP, dzięki któremu zewnętrzny klient MCP może wyświetlać listę agentów, sprawdzać połączenia i transkrypcje oraz wykonywać połączenia. Zobacz Używaj ThunderPhone jako serwera MCP.

W API: /v1/integrations, /v1/mcp-servers oraz /v1/voip-connections; zobacz także Utwórz integrację narzędzia.

Kampanie#

Kampania wykonuje wychodzące połączenia 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 wykonywania połączeń (dni i godziny z uwzględnieniem strefy czasowej), współbieżność oraz zasady ponawiania prób (maksymalną liczbę prób i wyniki — brak odpowiedzi, poczta głosowa, niepowodzenie — dla których próby będą ponawiane). Kampania przechodzi przez listę i rejestruje każde połączenie w Historii połączeń.

W panelu: Kampanie (/dashboard/campaigns). Zobacz Uruchom kampanię wychodzących połączeń.

W przypadku jednorazowych połączeń programistycznych: API połączeń wychodzących.

Monitorowanie na żywo#

Na żywo pokazuje każde połączenie w toku w całej organizacji i umożliwia otwarcie dowolnego z nich, aby nasłuchiwać i szeptać w czasie rzeczywistym. To obszar nadzoru: obserwuj, jak nowy prompt obsługuje pierwszy rzeczywisty ruch, lub monitoruj trwającą kampanię.

W panelu: Na żywo (/dashboard/live). Zobacz Obserwowanie i nadzorowanie połączeń na żywo.

Symulacje#

Symulacja to rozmówca AI prowadzący prawdziwą 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, napisz scenariusz rozmówcy samodzielnie albo wygeneruj scenariusze z 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 wskaźnik zaliczenia i mogą blokować wydania w CI; regresje względem zaakceptowanego poziomu bazowego są raportowane dla każdego scenariusza.

W panelu: Symulacje (/dashboard/simulations) oraz przycisk Symulacja w kreatorze agenta. Zobacz Symulowanie połączenia.

W API: /v1/test-calls oraz uruchamianie pakietów — zobacz Testowanie agenta od początku do końca.

Zbiory walidacyjne#

Zbiór walidacyjny przekształca rzeczywiste momenty rozmów w powtarzalne, jednoturowe kontrole regresji. Każdy przykład zapisuje kontekst rozmowy, odpowiednie nagranie rozmówcy, pierwotną odpowiedź i oczekiwane zachowanie. Odtworzenia są uruchamiane dla bieżącej wersji roboczej agenta bez wykonywania kolejnego połączenia, a okno wdrażania może pokazać, czy najnowsze uruchomienie nadal odpowiada tej wersji roboczej.

W panelu: Zbiory walidacyjne (/dashboard/validation) dla zbioru danych organizacji oraz karta Walidacja w kreatorze agenta dla uruchomień. Zobacz Zbiory walidacyjne.

W API: /v1/validation-sets oraz punkty końcowe odtwarzania agenta i przykładów na tej samej stronie referencyjnej.

Eksperymenty#

Eksperyment testuje A/B konfiguracje agenta na rzeczywistym ruchu: zdefiniuj warianty (różne prompty, silniki lub ustawienia), podziel 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 (testowanie A/B).

Problemy#

Problem to oznaczony problem w konkretnym połączeniu — zgłoszony przez osobę dokonującą przeglądu lub wykryty przez ocenę AI. Problemy zawierają poziom ważności, źródło i status, a strona Problemy jest kolejką segregacji: filtruj, sprawdzaj problematyczne połączenie i śledź poprawki.

W panelu: Problemy (/dashboard/issues) oraz oznaczanie dla poszczególnych połączeń w Historii połączeń. Zobacz Segregacja problemów.

W API: /v1/issue-reports.

Raporty#

Raport odpowiada na pytanie sformułowane w języku naturalnym dotyczące danych o połączeniach ("Jakie były trzy najczęstsze powody, dla których rozmówcy prosili o człowieka w zeszłym tygodniu?") analizą napisaną przez AI, ograniczoną do wybranych przez Ciebie agentów i zakresu dat.

W panelu: Raporty (/dashboard/reports). Zobacz Raporty.

Obserwowalność#

Obserwowalność to obszar metryk: wolumenu połączeń, wyników i jakości 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ść.

Alerty#

Reguła alertu monitoruje metrykę (wskaźnik sukcesu, wskaźnik niepowodzeń, średni wynik, wolumen połączeń, regresje pakietów) w przedziale czasu i uruchamia się, gdy przekroczy ona określony przez Ciebie próg. Powiadomienia są wysyłane e-mailem i do Slacka oraz wysyłają zdarzenie alert.triggered do Twoich punktów końcowych webhooków.

W panelu: Organizacja → Alerty. Zobacz Alerty.

Webhooki#

ThunderPhone wysyła webhooki HTTP POST na Twój serwer, gdy coś dzieje się w trakcie połączenia lub po jego zakończeniu. Dostępne są dwa modele dostarczania:

• Punkty końcowe webhooków (zalecane): zarządzaj wieloma adresami URL w /v1/developer/webhook-endpoints, korzystając z sekretów i subskrypcji zdarzeń dla poszczególnych punktów końcowych.
• Starszy webhook z pojedynczym adresem URL: jeden adres URL na organizację. Zarządzany w /v1/webhook lub w sekcji 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 kształtuje trwające połączenie — są to zdarzenia połączeń przychodzących (telephony.incoming / web.incoming). Masz do 10 sekund na odpowiedź; w przypadku przekroczenia czasu połączenie obsłuży statycznie przypisany agent.
• Zdarzenia nieblokujące to powiadomienia typu „wyślij i zapomnij”, ponawiane z wykładniczym wydłużaniem odstępów — zobacz semantykę dostarczania.

Każde żądanie zawiera podpis HMAC-SHA256 w nagłówku X-ThunderPhone-Signature. Zobacz weryfikację podpisu.

Narzędzia funkcji#

Narzędzie funkcji to punkt końcowy HTTP, który Twój 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 wykonuje podpisane żądanie HTTP ze swoich serwerów i przekazuje wynik agentowi.

Agenci mają również wbudowane możliwości połączeń — przekazywanie połączenia, wysyłanie danych wejściowych z klawiatury (DTMF), kończenie połączenia, oczekiwanie na linii — które włączasz zwykłymi liniami promptu zamiast definicjami narzędzi.

W panelu: sekcja Połączenia API w kreatorze (zobacz Połączenia).

W API: /v1/integrations oraz specyfikacja narzędzi funkcji.

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ą również zespołem i rozliczeniami. Zaproś przez e-mail — 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.

W panelu: Organizacja → Ogólne. Zobacz Zaproś swój zespół.

W API: /v1/members, /v1/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 oraz dopłaty — kreator na bieżąco pokazuje pełną stawkę podczas zmiany ustawień, a wybrane dodatkowe języki dodają 3¢/min). Gdy saldo spadnie do zera, połączenia przychodzące są odrzucane, a połączenia wychodzące zwracają 402 Payment Required.

Doładuj środki ręcznie albo włącz automatyczne doładowanie, ustawiając próg salda, kwotę doładowania i opcjonalny miesięczny limit wydatków — aby połączenie nigdy nie zakończyło się w połowie zdania.

W panelu: Organizacja → Ustawienia rozliczeń oraz Historia rozliczeń. Zobacz Dodaj środki i włącz automatyczne doładowanie, a także pełny cennik.

W API: /v1/billing.

Asystent w aplikacji#

Panel zawiera wbudowanego asystenta — zapytaj go „jak zrobić X”, a odpowie na podstawie tej dokumentacji, zaproponuje szczegółowe instrukcje krok po kroku wskazujące rzeczywiste elementy sterujące i może ponownie uruchomić dowolny z przewodników. To najszybszy sposób na znalezienie elementu sterującego wspomnianego na tej stronie. Zobacz Zapytaj asystenta w aplikacji.

Złóż to w całość#