Základné koncepty

Prehľad všetkého na platforme — čo každý objekt robí, kde sa nachádza v ovládacom paneli a ktoré API sa ho týka.

ThunderPhone je komplexná platforma na vytváranie, prevádzku a zlepšovanie hlasových agentov s AI. Táto stránka je mapou: každý koncept, s ktorým sa stretnete, má vlastnú krátku sekciu spolu s rozhraním dashboardu a rozhraním API, ktoré ho podporuje. Najprv si ju prejdite a potom sa sem vráťte vždy, keď budete potrebovať objasniť niektorý pojem.

Bočný panel dashboardu zodpovedá tejto štruktúre:

Organizácie#

Organizácia je jednotka tenancy. Každý ďalší zdroj — agenti, telefónne čísla, hovory, kľúče — patrí presne jednej organizácii. Váš účet môže patriť do viacerých organizácií; každá má vlastný zostatok, vlastné kľúče a vlastný zoznam členov.

Kľúč API sk_live_, ktorý vytvoríte v časti Organizácia → Kľúče, je viazaný na jednu organizáciu. Vďaka tomuto prepojeniu je rozhranie REST API také priamočiare: do ciest URL nikdy nevkladáte ID organizácie, pretože ju váš kľúč už identifikuje.

V dashboarde: prepínač organizácií (v päte bočného panela) a nastavenia Organizácia — karty Môj účet, Všeobecné, Kľúče, Upozornenia, Nastavenia fakturácie a História fakturácie. Pozrite si referenciu nastavení organizácie.

V API: /v1/orgs, /v1/developer/api-keys.

Agenti#

Agent je konfigurácia AI, ktorá vykonáva hovor. Zahŕňa:

• Prompt, ktorý určuje, čo agent hovorí a ako sa správa — vrátane akcií hovoru, ako sú prepojenia, stlačenia klávesnice a ukončenia hovoru, ktoré sú obyčajnými riadkami promptu, nie samostatnou konfiguráciou.
• Úroveň enginu (spark, bolt, storm-*): Spark je optimalizovaný na náklady, Bolt na rýchlosť a Storm na inteligenciu pri zložitých promptoch.
• Hlas spolu s primárnym jazykom a voliteľnými ďalšími jazykmi — agent sa automaticky prepne, keď volajúci zmení jazyk. Pozrite si podporované jazyky.
• Pripojené funkcie: prepojené aplikácie, pripojenia API, znalostné databázy, servery MCP a vložené funkčné nástroje.
• Nastavenia správania: poradie hovorenia, režim potvrdenia, stopa na pozadí, časový limit podržania.

Úpravy v nástroji na tvorbu sa automaticky ukladajú do konceptu; nič sa nezverejní, kým nekliknete na Nasadiť. Každé nasadenie sa uloží ako snímka na karte História nástroja na tvorbu, takže môžete skontrolovať a obnoviť ľubovoľnú predchádzajúcu verziu.

V dashboarde: Hlasoví agenti → nástroj na tvorbu agentov (/dashboard/agents). Pozrite si vytvorenie prvého hlasového agenta.

V API: /v1/agents — CRUD, duplikovanie, prenos, história verzií a pomocné nástroje pre prompty.

Hlasy#

Knižnica hlasov obsahuje hlasy, ktoré môže agent používať, ich prehrateľné ukážky, kompatibilné jazyky, skupiny podľa pohlavia a prízvuku a prípadný príplatok za prémiový hlas alebo jazyk. Pred výberom môže platený nástroj na ukážky syntetizovať vlastnú frázu s dĺžkou 1 až 500 znakov.

Oprávnené organizácie môžu tiež vytvárať vlastné hlasy z krátkej ukážky vo formáte WAV alebo MP3. Vlastné hlasy majú kvótu a asynchrónny stav vytvárania; po pripravení sa zobrazia v rovnakom výbere agentov ako hlasy z knižnice.

Na paneli: Hlasy (/dashboard/voices). Pozrite si Knižnica hlasov a vlastné hlasy.

V API: /v1/voices, ukážky hlasov a vlastné hlasy.

Telefónne čísla#

Telefónne číslo patrí organizácii a smeruje prichádzajúce hovory k agentovi (a môže podporovať odchádzajúce hovory). Dva zdroje:

• Čísla ThunderPhone — skutočné americké čísla poskytované z fondu ThunderPhone, aktívne v priebehu sekúnd, $1/mesiac plus príplatok 1 ¢/minútu. Iba pre prichádzajúce hovory; na odchádzajúce hovory potrebujete vlastného operátora. Organizácia ich môže štandardne mať 25.
• VoIP čísla — prinesené od vlastného poskytovateľa prostredníctvom pripojenia VoIP. Twilio a Telnyx sa pripájajú priamo (Telnyx ponúka sprievodcu nastavením); SignalWire a Vonage budú čoskoro dostupné — momentálne ich môžete pripojiť prostredníctvom manuálnej konfigurácie SIP, ktorá prijíma ľubovoľný SIP trunk. Po importovaní a overení podporujú VoIP čísla prichádzajúce aj odchádzajúce hovory.

V každom riadku čísla môžete nastaviť režim smerovania, vybrať agenta pre prichádzajúce hovory a pridať označenie čísla.

Na paneli: Telefónne čísla (/dashboard/phone-numbers). Pozrite si Získať telefónne číslo.

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

Hovory#

Každý prichádzajúci hovor, odchádzajúci hovor, simulácia a relácia widgetu sa stane záznamom hovoru. Hovor obsahuje úplný prepis s označením rolí, štruktúrovanú históriu ťahov (vrátane volaní nástrojov), nahrávku, celkovú cenu a voliteľné hodnotenie AI a hlásenia problémov.

Kým hovor prebieha naživo, môžete ho otvoriť a odpočúvať — pripojíte sa potichu a nikto v hovore vás nepočuje. Po pripojení môžete šepkať: napíšte pokyn, ktorý sa počas hovoru odošle priamo vášmu agentovi; volajúci ho nikdy nepočuje a agent sa ním okamžite riadi.

Na paneli: História hovorov (/dashboard/call-history) pre archív a podrobnosti jednotlivých hovorov; Naživo pre prebiehajúce hovory. Pozrite si Kontrola, odpočúvanie a koučovanie hovorov.

V API: /v1/calls — zoznam, prepis, história, zvuk, hodnotenie, export; /v1/issue-reports.

Klientské portály#

Klientský portál je značkový pohľad na históriu hovorov iba na čítanie pre externého klienta. Správcovia organizácie vyberajú agentov, ktorých hovory sa zobrazia, pridávajú e-mailové adresy schválených používateľov, nahrávajú logo a akcentovú farbu a voliteľne overujú vlastnú doménu. Používatelia portálu môžu kontrolovať podrobnosti hovorov, prepisy a dostupné nahrávky bez získania prístupu k panelu.

Na paneli: Klientské portály (/dashboard/client-portals). Pozrite si Klientské portály.

V API: /v1/client-portals pre rozhranie správy administrátorov.

Webové widgety#

Webový widget poskytuje návštevníkom vašej stránky konverzáciu s agentom prostredníctvom mikrofónu — nie je potrebné telefónne číslo. Autentifikuje sa pomocou publikovateľného kľúča (pk_live_...), ktorý je viazaný na pôvod vašich povolených domén, takže je bezpečný na použitie v kóde na strane klienta.

Kľúče fungujú v jednom z dvoch režimov: agent (staticky viazaný na jedného agenta) alebo webhook (váš server vyberie konfiguráciu pre každého návštevníka — pozrite si Dynamická konfigurácia pre jednotlivé hovory). Relácie widgetu prechádzajú rovnakou infraštruktúrou hovorov ako telefónne hovory.

Na paneli: Webové widgety (/dashboard/web-widgets) — vytvárajte widgety, nastavujte režim a agenta, spravujte povolené domény a skopírujte úryvok na vloženie. Pozrite si Vytvorenie webového widgetu.

V API: /v1/publishable-key, /v1/mic-session a dokumentáciu Widget SDK.

Znalostné bázy#

Znalostná báza je súbor dokumentov, ktoré môže váš agent počas hovoru vyhľadávať, aby poskytoval odpovede na základe overených informácií — nahrávajte súbory, vkladajte text alebo importujte webové stránky podľa URL a potom pripojte znalostnú bázu k agentovi v nástroji na vytváranie. Agent ju vyhľadáva pomocou vstavaného vyhľadávacieho nástroja vždy, keď si to konverzácia vyžaduje.

Na paneli: Znalosti (/dashboard/knowledge) pre knižnicu dokumentov; sekcia Znalosti v nástroji na vytváranie na pripojenie znalostnej bázy k agentovi. Pozrite si Poskytnutie znalostnej bázy agentovi.

Pripojenia#

Pripojenia umožňujú agentom komunikovať s externým svetom. Štyri druhy, jedna skupina na bočnom paneli:

• Aplikácie (/dashboard/app-connections) — pripojenia OAuth k Slack, HubSpot, Salesforce, Google Calendar, Google Sheets a Cal.com. Pripojte ich raz a potom pri jednotlivých operáciách zapnite nástroje (odoslanie správy do Slacku, vytvorenie alebo aktualizácia kontaktu v HubSpote, rezervácia termínu v Cal.com…) pre ľubovoľného agenta. Pozrite si Pripojenie aplikácií.
• API (/dashboard/api-connections) — premeňte ľubovoľné HTTP API na akciu agenta. Vložte príkaz cURL a sprievodca AI pripraví návrh definície nástroja, alebo ho vytvorte manuálne; tlačidlo Testovať požiadavku odošle testovacie volanie pred nasadením. Pozrite si Pripojenia API — rozhranie panela pre /v1/integrations.
• MCP (/dashboard/mcp-connections) — pridajte server Model Context Protocol pomocou URL a umožnite agentovi používať nástroje, ktoré poskytuje. Pozrite si Pridanie servera MCP.
• VoIP (/dashboard/voip-connections) — prihlasovacie údaje poskytovateľa pre použitie vlastných telefónnych čísel. Pozrite si Pripojenie poskytovateľa VoIP.

ThunderPhone poskytuje aj vlastný koncový bod MCP, aby externý klient MCP mohol zobraziť zoznam agentov, kontrolovať hovory a prepisy a uskutočňovať hovory. Pozrite si Použitie ThunderPhone ako servera MCP.

V API: /v1/integrations, /v1/mcp-servers a /v1/voip-connections; pozrite si aj Vytvorenie integrácie nástroja.

Kampane#

Kampaň uskutočňuje odchádzajúce hovory vo veľkom rozsahu: nahrajte CSV so kontaktmi, vyberte agenta a číslo volajúceho a nastavte okno volaní (dni a hodiny so zohľadnením časového pásma), súbežnosť a pravidlá opakovania (maximálny počet pokusov a výsledky — bez odpovede, hlasová schránka, neúspech — pri ktorých sa hovor zopakuje). Kampaň postupne spracuje zoznam a zaznamená každý hovor do Histórie hovorov.

Na paneli: Kampane (/dashboard/campaigns). Pozrite si Spustenie kampane odchádzajúcich hovorov.

Pre jednorazové programové hovory: API odchádzajúcich hovorov.

Živé monitorovanie#

Naživo zobrazuje každý prebiehajúci hovor v organizácii a umožňuje vám otvoriť ktorýkoľvek z nich, aby ste mohli počúvať a šepkať v reálnom čase. Je to prostredie na dohľad: sledujte, ako nový prompt prijíma prvú reálnu prevádzku, alebo majte pod dohľadom prebiehajúcu kampaň.

Na paneli: Naživo (/dashboard/live). Pozrite si Sledovanie a dohľad nad živými hovormi.

Simulácie#

Simulácia je volajúci s AI, ktorý vedie skutočný rozhovor s vaším agentom — rovnaká telefónna cesta, skutočný prepis, skutočné hodnotenie — takže môžete testovať pred nasadením aj po ňom. Nasmerujte ju na agenta alebo telefónne číslo, scenár volajúceho napíšte sami alebo vygenerujte scenáre pomocou AI z promptu agenta (vrátane okrajových prípadov, ak o ne požiadate) a sledujte hovor naživo.

Scenáre sa zoskupujú do súprav, ktoré určujú minimálnu úspešnosť a môžu blokovať vydania v CI; regresie oproti schválenému základu sa vykazujú pre každý scenár.

Na paneli: Simulácie (/dashboard/simulations) a tlačidlo Simulácia v nástroji na vytváranie agenta. Pozrite si Simulácia hovoru.

V API: /v1/test-calls a spúšťač súprav — pozrite si Komplexné testovanie agenta.

Validačné sady#

Validačná sada premieňa reálne momenty z hovorov na opakovateľné jednokolové kontroly regresií. Každý príklad uchováva kontext konverzácie, relevantné audio volajúceho, pôvodnú odpoveď a očakávané správanie. Opätovné prehrania sa spúšťajú proti aktuálnemu návrhu agenta bez uskutočnenia ďalšieho hovoru a dialógové okno nasadenia môže zobraziť, či sa najnovšie spustenie stále zhoduje s týmto návrhom.

Na paneli: Validačné sady (/dashboard/validation) pre množinu údajov organizácie a karta Validácia v nástroji na vytváranie agenta pre spustenia. Pozrite si Validačné sady.

V API: /v1/validation-sets a koncové body opätovného prehrania agenta/príkladu na tej istej referenčnej stránke.

Experimenty#

Experiment vykonáva A/B testovanie konfigurácií agenta na reálnej prevádzke: definujte varianty (odlišné prompty, enginy alebo nastavenia), rozdeľte medzi ne prevádzku a porovnajte výsledky pre jednotlivé varianty. Použite ho namiesto vlastnej implementácie logiky segmentov vo webovom hooku.

Na paneli: Experimenty (/dashboard/experiments) a karta A/B v nástroji na vytváranie agenta. Pozrite si Experimenty (A/B testovanie).

Problémy#

Problém je označený nedostatok v konkrétnom hovore — nahlásený ľudským kontrolórom alebo zistený hodnotením AI. Problémy obsahujú závažnosť, zdroj a stav a stránka Problémy slúži ako front na triedenie: filtrujte, preskúmajte problematický hovor a sledujte opravy.

Na paneli: Problémy (/dashboard/issues) a označovanie pre každý hovor v Histórii hovorov. Pozrite si Triedenie problémov.

V API: /v1/issue-reports.

Reporty#

Report odpovedá na otázku v prirodzenom jazyku o vašich údajoch hovorov ("Aké boli minulý týždeň tri najčastejšie dôvody, pre ktoré volajúci žiadali človeka?") pomocou analýzy napísanej AI, obmedzenej na agentov a rozsah dátumov, ktoré vyberiete.

Na paneli: Reporty (/dashboard/reports). Pozrite si Reporty.

Observabilita#

Observabilita je prostredie metrík: objem hovorov, výsledky a kvalita v čase, s možnosťou filtrovania podľa agenta a časového okna a exportom na následnú analýzu.

Na paneli: Observabilita (/dashboard/observability). Pozrite si Observabilita.

Upozornenia#

Pravidlo upozornenia sleduje metriku (úspešnosť, miera zlyhaní, priemerné skóre, objem hovorov, regresie súprav) v časovom okne a spustí sa, keď prekročí váš prah. Upozornenia sa odosielajú e-mailom a do Slacku a spúšťajú udalosť alert.triggered pre vaše koncové body webových hookov.

Na paneli: Organizácia → Upozornenia. Pozrite si Upozornenia.

Webhooky#

ThunderPhone odosiela na váš server webhooky HTTP POST, keď počas hovoru a po ňom nastanú udalosti. Dva modely doručovania:

• Koncové body webhookov (odporúčané): spravujte viacero URL na /v1/developer/webhook-endpoints s tajnými kľúčmi pre každý koncový bod a odbermi udalostí pre každý koncový bod.
• Starší webhook s jednou URL: jedna URL na organizáciu. Spravuje sa na /v1/webhook alebo v časti Organizácia → Všeobecné. Zachovaný z dôvodu spätnej kompatibility.

Udalosti sa delia na dve triedy:

• Blokujúce udalosti očakávajú, že váš server odpovie konfiguráciou, ktorá ovplyvní prebiehajúci hovor — ide o udalosti prichádzajúceho hovoru (telephony.incoming / web.incoming). Na odpoveď máte až 10 sekúnd; pri časovom limite hovor spracuje staticky priradený agent.
• Neblokujúce udalosti sú oznámenia typu fire-and-forget, ktoré sa opakujú s exponenciálnym odkladom — pozrite si sémantiku doručovania.

Každá požiadavka obsahuje podpis HMAC-SHA256 v hlavičke X-ThunderPhone-Signature. Pozrite si overenie podpisu.

Funkčné nástroje#

Funkčný nástroj je koncový bod HTTP, ktorý môže váš agent zavolať uprostred konverzácie. ThunderPhone poskytnete schému funkcie v štýle OpenAI spolu s URL koncového bodu; agent rozhodne, kedy ho zavolať, a ThunderPhone odošle podpísanú požiadavku HTTP zo svojich serverov a výsledok vráti agentovi.

Agenti majú aj vstavané funkcie hovorov — presmerovanie hovoru, odosielanie vstupu z klávesnice (DTMF), ukončenie hovoru, čakanie na linke — ktoré povolíte jednoduchými riadkami v prompte namiesto definícií nástrojov.

Na ovládacom paneli: sekcia Pripojenia API v nástroji na vytváranie (pozrite si Pripojenia).

V API: /v1/integrations a špecifikácia funkčných nástrojov.

Tím a roly#

Každá organizácia má zoznam členov s dvoma rolami: Členovia vytvárajú a prevádzkujú agentov; Administrátori zároveň spravujú tím a fakturáciu. Pozvite ich e-mailom — pozvánky vypršia po 7 dňoch a možno ich odvolať; ponuka ⋯ v riadku člena mení roly alebo niekoho odstráni. Jednotné prihlásenie možno nakonfigurovať pre celú organizáciu — pozrite si SSO.

Na ovládacom paneli: Organizácia → Všeobecné. Pozrite si Pozvite svoj tím.

V API: /v1/members, /v1/invites.

Fakturácia#

ThunderPhone je predplatený. Každá organizácia má zostatok v USD; hovory ho odpočítavajú podľa sadzby agenta za minútu (úroveň enginu plus príplatky — nástroj na vytváranie zobrazuje celkovú sadzbu v reálnom čase pri zmene nastavení a vybrané ďalšie jazyky pridávajú 3¢/min). Keď zostatok dosiahne nulu, prichádzajúce hovory sa odmietnu a odchádzajúce hovory vrátia 402 Payment Required.

Doplňte kredit manuálne alebo povoľte automatické dopĺňanie s prahovou hodnotou zostatku, sumou doplnenia a voliteľným mesačným limitom výdavkov — aby sa hovor nikdy neprerušil uprostred vety.

Na ovládacom paneli: Organizácia → Nastavenia fakturácie a História fakturácie. Pozrite si Pridajte kredit a zapnite automatické dopĺňanie aj úplný prehľad cien.

V API: /v1/billing.

Kopilot v aplikácii#

Ovládací panel obsahuje vstavaného kopilota — opýtajte sa ho „ako vykonám X“ a odpovie vám na základe tejto dokumentácie, ponúkne podrobné návody krok za krokom, ktoré zvýraznia skutočné ovládacie prvky, a dokáže znova spustiť ktorúkoľvek z prehliadok so sprievodcom. Je to najrýchlejší spôsob, ako nájsť ovládací prvok spomenutý na tejto stránke. Pozrite si Opýtajte sa kopilota v aplikácii.

Dajte to všetko dohromady#