Základné koncepty

Prehľad všetkého na platforme — čo jednotlivé objekty robia, kde sa nachádzajú na ovládacom paneli a ktoré API sa ich týka.

ThunderPhone je kompletná platforma na vytváranie, prevádzku a zlepšovanie hlasových agentov s AI. 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 prebehnite a potom sa k nej vráťte vždy, keď potrebujete objasniť nejaký pojem.

Bočný panel ovládacieho panela zrkadlí túto štruktúru:

Organizácie#

Organizácia je jednotka nájomníka. 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. Práve toto prepojenie robí REST API takým jednoduchým: identifikátor organizácie nikdy neuvádzate v cestách URL, pretože ho už identifikuje váš kľúč.

V ovládacom paneli: prepínač organizácie (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á spracúva hovor. Zahŕňa:

• Prompt, 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 promptu, nie samostatnou konfiguráciou.
• Úroveň enginu (spark, bolt, storm-*): Spark je optimalizovaný na cenu, Bolt na rýchlosť a Storm na inteligenciu pri komplexný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é možnosti: prepojené aplikácie, pripojenia API, znalostné bázy, servery MCP a vložené funkčné nástroje.
• Nastavenia správania: poradie hovorenia, 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 zaznamená 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é nástroje pre prompty.

Hlasy#

Knižnica hlasov obsahuje hlasy, ktoré môže agent používať, ich prehrateľné ukážky, podporované jazyky, skupiny podľa pohlavia a prízvuku a prípadný príplatok za prémiový hlas alebo jazyk. Platený nástroj na ukážku dokáže pred výberom 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; keď sú pripravené, zobrazia sa v rovnakom výbere agentov 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 na agenta (a môže prenášať odchádzajúce hovory). Existujú dva zdroje:

• Čísla ThunderPhone — skutočné čísla v USA zriadené z fondu ThunderPhone, aktívne v priebehu sekúnd, $1/mesiac plus príplatok 1 ¢/minútu. Spočiatku podporujú iba prichádzajúce hovory. Správca organizácie môže na stránke Telefónne čísla požiadať o odchádzajúce volania; ThunderPhone každú žiadosť manuálne posúdi a schválené čísla môžu uskutočňovať hovory a spúšťať kampane. Organizácia môže mať predvolene 25 čísel.
• Čísla VoIP — prinesené od vlastného poskytovateľa prostredníctvom pripojenia VoIP. Twilio a Telnyx sa pripájajú priamo pomocou kľúča API (Telnyx ponúka aj sprievodcu nastavením nového účtu); SignalWire, Vonage, Plivo a akýkoľvek iný kmeň SIP sa pripájajú prostredníctvom nastavenia SIP, manuálnej konfigurácie SIP. Po importovaní a overení čísla VoIP podporujú 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 označiť číslo.

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 stane 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ú cenu a voliteľné hodnotenie AI a hlásenia problémov.

Keď je hovor aktívny, môžete ho otvoriť a odpočúvať — pripojíte sa potichu a nikto v hovore vás nepočuje. Po začatí odpočúvania 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 riadi v reálnom čase.

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

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

Klientske portály#

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

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

V rozhraní API: /v1/client-portals pre správcovské rozhranie.

Webové widgety#

Webový widget poskytuje návštevníkom vašej stránky konverzáciu s agentom cez mikrofón — bez potreby telefónneho čísla. Overuje sa pomocou publikovateľného kľúča (pk_live_...), ktorý môžu prehliadače používať iba z vami povolených domén, takže je bezpečný v kóde na strane klienta. Zoznam domén nie je overovanie a nastavenia relácie, ktoré môže stránka odoslať, sú vypnuté, kým ich na kľúči nepovolíte.

Kľúče fungujú v jednom z dvoch režimov: agent (staticky priradený jednému agentovi) 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 rovnakú 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.

Vedomostné databázy#

Vedomostná databáza je súbor dokumentov, ktoré môže váš agent vyhľadávať počas hovoru, aby svoje odpovede oprel o relevantné informácie — nahrajte súbory, vložte text alebo importujte webové stránky pomocou URL a potom vedomostnú databázu pripojte k agentovi v nástroji na vytváranie. Agent ju dopytuje pomocou vstavaného vyhľadávacieho nástroja vždy, keď si to konverzácia vyžaduje.

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

Pripojenia#

Pripojenia umožňujú agentom komunikovať s okolitým svetom. Štyri typy, 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 ľubovoľnom agentovi zapínajte nástroje pre jednotlivé operácie (odoslanie správy do 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 AI pripraví návrh definície nástroja, alebo ho 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 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 tiež poskytuje 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 odchádzajúce číslo a nastavte okno volania (dni a hodiny s ohľadom na časové pásmo), súbežnosť a politiku 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ň postupuje zoznamom a zaznamenáva každý hovor do Histórie hovorov.

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

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

Monitorovanie naživo#

Naživo zobrazuje každý hovor, ktorý práve prebieha v celej organizácii, a umožňuje vám otvoriť ktorýkoľvek z nich a počúvať ho a šepkať v reálnom čase. Ide o prostredie na dohľad: sledujte, ako nový prompt získava 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 hovormi naživo.

Simulácie#

Simulácia je volajúci riadený AI, ktorý vedie skutočný rozhovor s vaším agentom — s rovnakou telefonickou cestou, reálnym prepisom a reálnym hodnotením — aby ste mohli testovať pred nasadením aj po ňom. Nastavte ju pre 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 akceptovanému základu sa reportujú pre každý scenár.

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

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

Validačné množiny#

Validačná množina mení momenty zo skutočných hovorov na opakovateľné, jednokolové regresné kontroly. Každý príklad uchováva kontext konverzácie, relevantné audio volajúceho, pôvodnú odpoveď a očakávané správanie. Opakované prehratia sa spúšťajú proti aktuálnemu návrhu agenta bez uskutočnenia ďalšieho hovoru a dialóg nasadenia môže zobraziť, či najnovšie spustenie stále zodpovedá tomuto návrhu.

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

V API: /v1/validation-sets a koncové body na opakované prehratie agenta/príkladu na tej istej referenčnej stránke.

Experimenty#

Experiment vykonáva A/B testovanie konfigurácií agenta v živej prevádzke: definujte varianty (rôzne prompty, enginy alebo nastavenia), rozdeľte medzi ne prevádzku a porovnajte výsledky jednotlivých variantov. Použite ho namiesto vlastného vytvárania logiky bucketov vo webhoooku.

Na paneli: Experimenty (/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 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 jednotlivých hovorov 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 dátach hovorov ("Aké boli minulý týždeň tri najčastejšie dôvody, pre ktoré volajúci požiadali o človeka?") pomocou analýzy vytvorenej 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ť, mieru zlyhaní, priemerné skóre, objem hovorov, regresie súprav) v časovom okne a aktivuje sa, keď prekročí váš prah. Oznámenia sa odosielajú e-mailom a do Slacku a pravidlo vyvolá udalosť alert.triggered pre vaše koncové body webhookov.

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

Webhooky#

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

• Koncové body webhookov (odporúčané): spravujte viacero adries URL na /v1/developer/webhook-endpoints pomocou tajomstiev pre jednotlivé koncové body a odberov udalostí pre jednotlivé koncové body.
• Starší webhook s jednou adresou URL: jedna adresa 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á formuje prebiehajúci hovor — ide o udalosti prichádzajúceho hovoru (telephony.incoming / web.incoming). Telefonický hovor čaká až 13 sekúnd vrátane jedného opakovania a relácia widgetu 10 sekúnd. Neexistuje žiadny záložný agent: bez použiteľnej konfigurácie sa telefonický hovor ukončí a relácia widgetu zlyhá.
• Neblokujúce udalosti sú oznámenia typu fire-and-forget, ktoré sa opakujú s exponenciálnym spätným odkladom — pozrite si sémantiku doručovania.

Každá požiadavka obsahuje časovo označený podpis HMAC-SHA256 v hlavičke X-ThunderPhone-Signature-V2 a starší podpis iba tela X-ThunderPhone-Signature. Pozrite si Overenie podpisu.

Nástroje funkcií#

Nástroj funkcie je koncový bod HTTP, ktorý môže váš agent zavolať počas konverzácie. ThunderPhone poskytnete schému funkcie v štýle OpenAI spolu s adresou URL koncového bodu; agent rozhodne, kedy ju zavolá, a ThunderPhone vykoná podpísanú požiadavku HTTP zo svojich serverov a odovzdá výsledok späť agentovi.

Agenti majú aj vstavané schopnosti hovoru — presmerovanie hovoru, odosielanie vstupu z klávesnice (DTMF), ukončenie hovoru, čakanie počas podržania — 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 nástrojov funkcií.

Tím a roly#

Každá organizácia má zoznam členov s dvoma rolami: Členovia vytvárajú a prevádzkujú agentov; Správcovia tiež 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 sa z neho odpočítavajú podľa sadzby 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¢/min). Keď zostatok dosiahne nulu, prichádzajúce hovory sa odmietnu a odchádzajúce hovory vrátia 402 Payment Required.

Doplňte zostatok 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 hovor nikdy neskončil uprostred vety.

Na ovládacom paneli: Organizácia → Nastavenia fakturácie a História fakturácie. Pozrite si Pridajte prostriedky a zapnite automatické dopĺňanie, 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 urobí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 sprievodných prehliadok. Je to najrýchlejší spôsob, ako nájsť ovládací prvok spomenutý na tejto stránke. Pozrite si Spýtajte sa kopilota v aplikácii.

Prepojenie všetkého#