Základné koncepty

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

Bočný panel ovládacieho panela zodpovedá tejto štruktúre:

Organizácie

Organizácia je jednotka tenanta. 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é jednoduché: do ciest URL nikdy nevkladáte ID organizácie, pretože ju už identifikuje váš kľúč.

V ovládacom paneli: 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:

• Pokyn, ktorý určuje, čo agent hovorí a ako sa správa — vrátane akcií počas hovoru, ako sú presmerovania, stlačenia klávesnice a ukončenia hovoru, ktoré sú obyčajnými riadkami pokynu, nie samostatnou konfiguráciou.
• Úroveň enginu (spark, bolt, storm-*): Spark je optimalizovaný na náklady, Bolt na rýchlosť a Storm na inteligentné spracovanie zložitých pokynov.
• 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é bázy, servery MCP a vložené funkčné nástroje.
• Nastavenia správania: poradie reči, režim potvrdenia, hudba na pozadí, časový limit podržania.

Úpravy v nástroji na vytváranie 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 vytváranie, takže môžete skontrolovať a obnoviť ľubovoľnú predchádzajúcu verziu.

V ovládacom paneli: Hlasoví agenti → nástroj na vytváranie agentov (/dashboard/agents). Pozrite si vytvorenie prvého hlasového agenta.

V API: /v1/agents — CRUD, duplikovanie, presmerovanie, história verzií a pomocné funkcie pre pokyny.

Hlasy

Knižnica hlasov obsahuje hlasy, ktoré môže agent používať, ich prehrateľné ukážky, kompatibilné jazyky, zoskupenia podľa pohlavia a prízvuku a prípadné príplatky za prémiové hlasy alebo jazyky. Platený nástroj na ukážky dokáže pred výberom syntetizovať vašu 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 stav asynchrónneho vytvárania; po dokončení sa zobrazia v rovnakom výbere agenta ako hlasy z knižnice.

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

V rozhraní 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 slúžiť aj na odchádzajúce hovory). Existujú dva zdroje:

• Demo čísla — skutočné americké čísla z fondu ThunderPhone, aktivované v priebehu sekúnd. Sú len pre prichádzajúce hovory, pri prijatí hovoru prehrajú krátke hovorené upozornenie a panel obmedzuje organizáciu na 10 takýchto čísel. Sú ideálne na prvý test, nie na produkčné použitie.
• 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 k dispozícii — dnes ich môžete používať cez manuálnu konfiguráciu SIP, ktorá prijíma ľubovoľný SIP trunk. Po importe 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ť štítok k číslu.

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

V rozhraní 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 stáva záznamom hovoru. Hovor obsahuje úplný prepis s označenými rolami, štruktúrovanú históriu ťahov (vrátane volaní nástrojov), nahrávku, celkovú sumu účtovania 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 ho okamžite vykoná.

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 rozhraní API: /v1/calls — zoznam, prepis, história, zvuk, hodnotenie, export; /v1/issue-reports.

Klientské portály

Klientský portál je zobrazenie histórie hovorov pre externého klienta s vašou značkou a prístupom iba na čítanie. Správcovia organizácie vyberajú agentov, ktorých hovory sa zobrazia, pridávajú e-mailové adresy schválených zobrazovateľov, nahrávajú logo a doplnkovú farbu a voliteľne overujú vlastnú doménu. Zobrazovatelia 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 rozhraní API: /v1/client-portals pre rozhranie správy pre administrátorov.

Webové widgety

Webový widget poskytuje návštevníkom vašej stránky konverzáciu s agentom prostredníctvom mikrofónu — bez potreby telefónneho čísla. Overuje sa pomocou publikovateľného kľúča (pk_live_...), ktorý je uzamknutý na pôvod vašich povolených domén, takže je bezpečný na použitie v klientskom kóde.

Kľúče fungujú v jednom z dvoch režimov: agent (staticky naviazaný na jedného agenta) alebo webhook (váš server vyberá konfiguráciu pre každého návštevníka — pozrite si Dynamická konfigurácia pre jednotlivé hovory). Relácie widgetu prechádzajú cez tú istú infraštruktúru hovorov ako telefonické 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, v ktorých môže váš agent počas hovoru vyhľadávať, aby svoje odpovede oprel o relevantné informácie — nahrajte súbory, vložte text alebo importujte webové stránky podľa URL a potom znalostnú bázu pripojte 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 bázy k agentovi. Pozrite si Pridanie znalostnej bázy agentovi.

Pripojenia

Pripojenia umožňujú agentom komunikovať s externými službami. Š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 pre každého agenta zapínajte nástroje pre jednotlivé operácie (odoslanie správy v Slacku, aktualizácia alebo vytvorenie kontaktu v HubSpot, rezervácia termínu v Cal.com…). 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 s AI pripraví návrh definície nástroja, alebo ju vytvorte ručne; tlačidlo Testovať požiadavku odošle volanie do sandboxu pred nasadením. Pozrite si Pripojenia API — rozhranie na paneli pre /v1/integrations.
• MCP (/dashboard/mcp-connections) — pridajte server Model Context Protocol podľa URL a umožnite agentovi používať nástroje, ktoré sprístupňuje. 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, takže externý klient MCP môže 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 s kontaktmi, vyberte agenta a číslo volajúceho a nastavte časové okno volania (dni a hodiny so zohľadnením časového pásma), súbežnosť a pravidlá opakovaných pokusov (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 pre odchádzajúce hovory.

Živé monitorovanie

Live zobrazuje každý hovor, ktorý práve prebieha v rámci organizácie, a umožňuje vám otvoriť ktorýkoľvek z nich, aby ste ho mohli počúvať a šepkať v reálnom čase. Je to rozhranie na dohľad: sledujte, ako nový prompt prijíma prvú reálnu prevádzku, alebo monitorujte prebiehajúcu kampaň.

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

Simulácie

Simulácia je hovor AI volajúceho, ktorý vedie skutočnú konverzáciu s vaším agentom — rovnaká telefonická 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é stanovujú minimálnu úspešnosť a môžu blokovať vydania v CI; regresie oproti prijatej základnej úrovni sa vykazujú pre každý scenár.

Na ovládacom paneli: Simulations (/dashboard/simulations) a tiež tlačidlo Simulation v nástroji na vytváranie agentov. Pozrite si Simulácia hovoru.

V API: /v1/test-calls a spúšťač súprav — pozrite si Testovanie agenta end-to-end.

Validačné súpravy

Validačná súprava mení momenty zo skutočných hovorov na opakovateľné regresné kontroly s jedným ťahom. Každý príklad uchováva kontext konverzácie, relevantný zvuk volajúceho, pôvodnú odpoveď a očakávané správanie. Opätovné prehrania sa spúšťajú oproti aktuálnemu návrhu agenta bez uskutočnenia ďalšieho hovoru a dialóg nasadenia môže zobraziť, či sa najnovšie spustenie stále zhoduje s týmto návrhom.

Na ovládacom paneli: Validation sets (/dashboard/validation) pre dátovú súpravu organizácie a karta Validation v nástroji na vytváranie agentov pre spustenia. Pozrite si Validačné súpravy.

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

Experimenty

Experiment A/B testuje konfigurácie agentov na živej prevádzke: definujte varianty (rôzne prompty, enginy alebo nastavenia), rozdeľte medzi ne prevádzku a porovnajte výsledky pre každý variant. Použite ho namiesto vlastnej implementácie logiky bucketov vo webhooku.

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

Problémy

Problém je označený problém 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 Issues je front na triedenie: filtrujte, preskúmajte problematický hovor a sledujte opravy.

Na ovládacom paneli: Issues (/dashboard/issues) a tiež označovanie pre jednotlivé hovory v histórii hovorov. Pozrite si Triedenie problémov.

V API: /v1/issue-reports.

Správy

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

Na ovládacom paneli: Reports (/dashboard/reports). Pozrite si Správy.

Pozorovateľnosť

Pozorovateľnosť je rozhranie 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 ovládacom paneli: Observability (/dashboard/observability). Pozrite si Pozorovateľnosť.

Upozornenia

Pravidlo upozornenia sleduje metriku (miera úspešnosti, miera zlyhaní, priemerné skóre, objem hovorov, regresie súprav) v rámci časového okna a spustí sa, keď prekročí váš prah. Oznámenia sa odosielajú e-mailom a do Slacku a vyvolajú udalosť alert.triggered pre vaše koncové body webhookov.

Na ovládacom paneli: Organization → Alerts. Pozrite si Upozornenia.

Webhooky

ThunderPhone odosiela na váš server webhooky HTTP POST, keď nastanú udalosti počas hovoru alebo po jeho skončení. Dva modely doručovania:

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

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ú notifikácie bez čakania na odpoveď, ktoré sa opakovane odosielajú s exponenciálnym predlžovaním intervalov — pozrite si sémantiku doručovania.

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

Nástroje funkcií

Nástroj funkcie 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 zavolá, a ThunderPhone vykoná podpísanú požiadavku HTTP zo svojich serverov a odovzdá výsledok späť agentovi.

Agenti obsahujú aj vstavané funkcie hovoru — presmerovanie hovoru, odosielanie vstupu z klávesnice (DTMF), ukončenie hovoru, čakanie na linke —, ktoré povolíte jednoduchými riadkami promptu 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 nástrojov funkcií.

Tím a roly

Každá organizácia má zoznam členov s dvoma rolami: Členovia vytvárajú a prevádzkujú agentov; Administrátori navyše 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 znižujú sadzbou agenta za minútu (úroveň enginu plus príplatky — nástroj na vytváranie zobrazuje celkovú sadzbu naživo pri zmene nastavení a vybrané ďalšie jazyky pridávajú 3 centy/min). Keď zostatok klesne na nulu, prichádzajúce hovory budú odmietnuté a odchádzajúce hovory vrátia 402 Payment Required.

Dobite zostatok manuálne alebo povoľte automatické dobitie s prahom zostatku, sumou dobitia a voliteľným mesačným limitom výdavkov — aby hovor nikdy neskončil uprostred vety.

Na ovládacom paneli: Organizácia → Nastavenia fakturácie a História fakturácie. Pozrite si Pridanie prostriedkov a zapnutie automatického dobíjania, ako aj kompletný 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 na základe tejto dokumentácie, ponúkne podrobné návody krok za krokom, ktoré zvýraznia skutočné ovládacie prvky, a môže znova prehrať ktorúkoľvek zo sprievodcovských prehliadok. 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