Základní pojmy

Přehled všeho na platformě — co jednotlivé objekty dělají, kde je najdete v dashboardu a které API je používá.

ThunderPhone je kompletní platforma pro vytváření, provoz a zlepšování hlasových agentů s AI. Tato stránka je mapou: každý koncept, se kterým se setkáte, má vlastní krátkou sekci spolu s rozhraním řídicího panelu a rozhraním API, které jej podporuje. Jednou si ji projděte a pak se sem vraťte, kdykoli bude potřeba některý pojem vysvětlit.

Postranní panel řídicího panelu odráží tuto strukturu:

Organizace#

Organizace je jednotka tenantu. Každý další zdroj — agenti, telefonní čísla, hovory, klíče — patří právě jedné organizaci. Váš účet může patřit do mnoha organizací; každá má vlastní zůstatek, vlastní klíče a vlastní seznam členů.

Klíč API sk_live_, který vytvoříte v části Organizace → Klíče, je vázán na jednu organizaci. Toto přiřazení udržuje rozhraní REST API tak jednoduché: identifikátor organizace nikdy neuvádíte v cestách URL, protože jej váš klíč již identifikuje.

V řídicím panelu: přepínač organizace (v zápatí postranního panelu) a nastavení Organizace — karty Můj účet, Obecné, Klíče, Upozornění, Nastavení fakturace a Historie fakturace. Viz referenční dokumentace nastavení organizace.

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

Agenti#

Agent je konfigurace AI, která řídí hovor. Zahrnuje:

• Prompt, který určuje, co agent říká a jak se chová — včetně akcí hovoru, jako jsou přepojení, stisknutí kláves a ukončení hovoru, které jsou běžnými řádky promptu, nikoli samostatnou konfigurací.
• Úroveň enginu (spark, bolt, storm-*): Spark je optimalizovaný pro náklady, Bolt pro rychlost a Storm pro inteligenci u složitých promptů.
• Hlas spolu s primárním jazykem a volitelnými dalšími jazyky — agent se automaticky přepne, když volající změní jazyk. Viz Podporované jazyky.
• Připojené schopnosti: propojené aplikace, připojení API, znalostní báze, servery MCP a vložené funkční nástroje.
• Nastavení chování: pořadí mluvení, režim potvrzování, zvuk na pozadí, časový limit podržení.

Úpravy v editoru se automaticky ukládají do konceptu; nic se nenasadí, dokud nekliknete na Nasadit. Každé nasazení se uloží jako snímek na kartě Historie editoru, takže můžete zkontrolovat a obnovit libovolnou předchozí verzi.

V řídicím panelu: Hlasoví agenti → editor agenta (/dashboard/agents). Viz Vytvořte svého prvního hlasového agenta.

V rozhraní API: /v1/agents — CRUD, duplikování, přepojení, historie verzí a pomocné nástroje pro prompty.

Hlasy#

Hlasová knihovna obsahuje hlasy, které může agent používat, jejich přehratelné ukázky, kompatibilní jazyky, seskupení podle pohlaví a přízvuku a případný příplatek za prémiový hlas nebo jazyk. Placený nástroj pro ukázky může před výběrem syntetizovat vlastní frázi o délce 1–500 znaků.

Oprávněné organizace mohou také vytvářet vlastní hlasy z krátké ukázky ve formátu WAV nebo MP3. Vlastní hlasy mají kvótu a stav asynchronního vytváření; po dokončení se zobrazí ve stejném výběru agentů jako hlasy z knihovny.

V dashboardu: Hlasy (/dashboard/voices). Viz Hlasová knihovna a vlastní hlasy.

V API: /v1/voices, ukázky hlasů a vlastní hlasy.

Telefonní čísla#

Telefonní číslo patří organizaci a směruje příchozí hovory k agentovi (a může zajišťovat odchozí hovory). Dva zdroje:

• Čísla ThunderPhone — skutečná americká čísla zřízená z fondu ThunderPhone, aktivní během několika sekund, 1 $/měsíc plus příplatek 1 ¢ za minutu. Zpočátku jsou pouze pro příchozí hovory. Správce organizace může na stránce Telefonní čísla požádat o odchozí volání; ThunderPhone každou žádost ručně posoudí a schválená čísla mohou volat a spouštět kampaně. Organizace může ve výchozím nastavení vlastnit 25 čísel.
• Čísla VoIP — přenesená od vlastního poskytovatele prostřednictvím připojení VoIP. Twilio a Telnyx se připojují přímo pomocí klíče API (Telnyx nabízí také provázené nastavení nového účtu); SignalWire, Vonage, Plivo a jakýkoli jiný SIP trunk se připojují prostřednictvím nastavení SIP, tedy ruční konfigurace SIP. Po importu a ověření podporují čísla VoIP příchozí i odchozí hovory.

U každého řádku čísla můžete nastavit režim směrování, vybrat agenta pro příchozí hovory a číslo označit.

V dashboardu: Telefonní čísla (/dashboard/phone-numbers). Viz Získání telefonního čísla.

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

Hovory#

Každý příchozí hovor, odchozí hovor, simulace a relace widgetu se stává záznamem hovoru. Hovor obsahuje úplný přepis s označením rolí, strukturovanou historii tahů (včetně volání nástrojů), nahrávku, celkovou cenu a volitelné hodnocení AI a hlášení problémů.

Dokud je hovor živý, můžete jej otevřít a poslouchat — připojíte se neslyšně a nikdo v hovoru vás neuslyší. Po připojení k poslechu můžete šeptat: napište pokyn, který se během hovoru odešle přímo vašemu agentovi; volající jej nikdy neuslyší a agent se jím ihned řídí.

V dashboardu: Historie hovorů (/dashboard/call-history) pro archiv a podrobnosti jednotlivých hovorů; Živé pro probíhající hovory. Viz Kontrola, poslech a vedení hovorů.

V API: /v1/calls — seznam, přepis, historie, zvuk, hodnocení, export; /v1/issue-reports.

Klientské portály#

Klientský portál je značkový pohled na historii hovorů pouze pro čtení pro externího klienta. Administrátoři organizace vybírají agenty, jejichž hovory se zobrazí, přidávají schválené e-mailové adresy diváků, nahrávají logo a barvu zvýraznění a volitelně ověřují vlastní doménu. Diváci portálu mohou kontrolovat podrobnosti hovorů, přepisy a dostupné nahrávky, aniž by získali přístup do dashboardu.

V dashboardu: Klientské portály (/dashboard/client-portals). Viz Klientské portály.

V API: /v1/client-portals pro rozhraní správy administrátory.

Webové widgety#

Webový widget umožňuje návštěvníkům vašeho webu konverzaci s agentem pomocí mikrofonu — bez nutnosti telefonního čísla. Ověřuje se pomocí publikovatelného klíče (pk_live_...), který mohou prohlížeče používat pouze z vámi povolených domén, takže je bezpečný pro použití v kódu na straně klienta. Seznam domén není ověřování a nastavení relace, která může stránka odeslat, jsou vypnutá, dokud je u klíče nepovolíte.

Klíče fungují v jednom ze dvou režimů: agent (staticky vázaný na jednoho agenta) nebo webhook (váš server vybírá konfiguraci pro každého návštěvníka — viz Dynamická konfigurace pro jednotlivé hovory). Relace widgetů procházejí stejnou infrastrukturou pro hovory jako telefonní hovory.

V dashboardu: Webové widgety (/dashboard/web-widgets) — vytvářejte widgety, nastavujte režim a agenta, spravujte povolené domény a kopírujte vložený úryvek. Viz Vytvoření webového widgetu.

V API: /v1/publishable-key, /v1/mic-session a dokumentace Widget SDK.

Znalostní báze#

Znalostní báze je sada dokumentů, ve kterých může váš agent během hovoru vyhledávat, aby zakotvil své odpovědi ve faktech — nahrajte soubory, vložte text nebo importujte webové stránky podle URL a poté znalostní bázi připojte k agentovi v editoru. Agent se na ni dotazuje pomocí vestavěného vyhledávacího nástroje, kdykoli to konverzace vyžaduje.

V dashboardu: Znalosti (/dashboard/knowledge) pro knihovnu dokumentů; sekce Znalosti v editoru pro připojení znalostní báze k agentovi. Viz Poskytnutí znalostní báze agentovi.

Propojení#

Propojení umožňují agentům komunikovat s okolním světem. Čtyři typy, jedna skupina v postranním panelu:

• Aplikace (/dashboard/app-connections) — připojení OAuth ke službám Slack, HubSpot, Salesforce, Kalendář Google, Tabulky Google a Cal.com. Připojte je jednou a poté u libovolného agenta zapínejte nástroje pro jednotlivé operace (odeslání zprávy do Slacku, vytvoření nebo aktualizace kontaktu v HubSpotu, rezervace termínu v Cal.com…). Viz Připojení aplikací.
• API (/dashboard/api-connections) — proměňte libovolné HTTP API v akci agenta. Vložte příkaz cURL a průvodce AI připraví návrh definice nástroje, nebo ji vytvořte ručně; tlačítko Testovací požadavek před nasazením provede volání v sandboxu. Viz Připojení API — rozhraní dashboardu pro /v1/integrations.
• MCP (/dashboard/mcp-connections) — přidejte server Model Context Protocol pomocí URL a umožněte agentovi používat nástroje, které zpřístupňuje. Viz Přidání serveru MCP.
• VoIP (/dashboard/voip-connections) — přihlašovací údaje poskytovatele pro použití vlastních telefonních čísel. Viz Připojení poskytovatele VoIP.

ThunderPhone také zpřístupňuje vlastní koncový bod MCP, aby externí klient MCP mohl zobrazit seznam agentů, kontrolovat hovory a přepisy a uskutečňovat hovory. Viz Použití ThunderPhone jako serveru MCP.

V API: /v1/integrations, /v1/mcp-servers a /v1/voip-connections; viz také Vytvoření integrace nástroje.

Kampaně#

Kampaň uskutečňuje odchozí hovory ve velkém měřítku: nahrajte CSV se kontakty, vyberte agenta a číslo volajícího a nastavte okno volání (dny a hodiny se zohledněním časového pásma), souběžnost a zásady opakování (maximální počet pokusů a výsledky — bez odpovědi, hlasová schránka, neúspěch — které se budou opakovat). Kampaň postupuje seznamem a zaznamenává každý hovor v Historii hovorů.

V dashboardu: Kampaně (/dashboard/campaigns). Viz Spuštění kampaně odchozích hovorů.

Pro jednorázové programové hovory: API pro odchozí hovory.

Živé monitorování#

Živě zobrazuje každý právě probíhající hovor v celé organizaci a umožňuje vám otevřít kterýkoli z nich a odposlouchávat jej a našeptávat v reálném čase. Jde o rozhraní pro dohled: sledujte, jak nový prompt přijímá první skutečný provoz, nebo mějte přehled o probíhající kampani.

Na řídicím panelu: Živě (/dashboard/live). Viz Sledování a dohled nad živými hovory.

Simulace#

Simulace je volající s umělou inteligencí, který vede skutečný rozhovor s vaším agentem — stejná telefonní cesta, skutečný přepis, skutečné hodnocení — takže můžete testovat před nasazením i po něm. Nasměrujte ji na agenta nebo telefonní číslo, scénář volajícího napište sami nebo vygenerujte scénáře pomocí AI z promptu agenta (včetně okrajových případů, pokud o ně požádáte) a sledujte hovor živě.

Scénáře se sdružují do sad, které stanovují minimální míru úspěšnosti a mohou blokovat vydání v CI; regrese oproti přijatému základu se hlásí pro každý scénář.

Na řídicím panelu: Simulace (/dashboard/simulations) a také tlačítko Simulace v editoru agenta. Viz Simulace hovoru.

V API: /v1/test-calls a spouštěč sad — viz Komplexní testování agenta.

Validační sady#

Validační sada převádí skutečné okamžiky z hovorů na opakovatelné jednokolové kontroly regresí. Každý příklad zachycuje kontext konverzace, relevantní zvuk volajícího, původní odpověď a očekávané chování. Přehrání probíhají proti aktuálnímu návrhu agenta bez uskutečnění dalšího hovoru a dialog nasazení může zobrazit, zda nejnovější běh stále odpovídá tomuto návrhu.

Na řídicím panelu: Validační sady (/dashboard/validation) pro datovou sadu organizace a karta Validace v editoru agenta pro běhy. Viz Validační sady.

V API: /v1/validation-sets a koncové body pro přehrání agenta/příkladu na stejné referenční stránce.

Experimenty#

Experiment provádí A/B testování konfigurací agenta na živém provozu: definujte varianty (odlišné prompty, enginy nebo nastavení), rozdělte mezi ně provoz a porovnejte výsledky pro jednotlivé varianty. Použijte jej místo ruční implementace logiky segmentů ve webhooku.

Na řídicím panelu: Experimenty (/dashboard/experiments) a karta A/B v editoru agenta. Viz Experimenty (A/B testování).

Problémy#

Problém je označený problém v konkrétním hovoru — nahlášený lidským kontrolorem nebo zjištěný hodnocením AI. Problémy obsahují závažnost, zdroj a stav a stránka Problémy slouží jako fronta pro třídění: filtrujte, prozkoumejte problematický hovor a sledujte opravy.

Na řídicím panelu: Problémy (/dashboard/issues) a také označování jednotlivých hovorů v Historii hovorů. Viz Třídění problémů.

V API: /v1/issue-reports.

Reporty#

Report odpovídá na otázku v přirozeném jazyce týkající se vašich dat hovorů („Jaké byly minulý týden tři hlavní důvody, proč volající žádali o člověka?“) pomocí analýzy vytvořené AI, omezené na agenty a období, které zvolíte.

Na řídicím panelu: Reporty (/dashboard/reports). Viz Reporty.

Pozorovatelnost#

Pozorovatelnost je rozhraní metrik: objem hovorů, výsledky a kvalita v čase, s možností filtrování podle agenta a časového období a exportem pro navazující analýzu.

Na řídicím panelu: Pozorovatelnost (/dashboard/observability). Viz Pozorovatelnost.

Upozornění#

Pravidlo upozornění sleduje metriku (míru úspěšnosti, míru selhání, průměrné skóre, objem hovorů, regrese sady) v časovém období a spustí se, když překročí vámi stanovenou prahovou hodnotu. Oznámení se odesílají e-mailem a do Slacku a vyvolají událost alert.triggered pro vaše koncové body webhooků.

Na řídicím panelu: Organizace → Upozornění. Viz Upozornění.

Webhooky#

ThunderPhone odesílá na váš server webhooky HTTP POST, když během hovoru a po jeho skončení nastanou určité události. Dva modely doručování:

• Koncové body webhooků (doporučeno): spravujte více URL na /v1/developer/webhook-endpoints s tajnými klíči a odběry událostí pro jednotlivé koncové body.
• Starší webhook s jednou URL: jedna URL pro organizaci. Spravuje se na /v1/webhook nebo v nabídce Organizace → Obecné. Je zachován kvůli zpětné kompatibilitě.

Události se dělí do dvou tříd:

• Blokující události očekávají, že váš server odpoví konfigurací, která ovlivní probíhající hovor — jedná se o události příchozích hovorů (telephony.incoming / web.incoming). Telefonní hovor čeká až 13 sekund včetně jednoho opakování a relace widgetu 10 sekund. Náhradní agent není k dispozici: bez použitelné konfigurace je telefonní hovor ukončen a relace widgetu selže.
• Neblokující události jsou oznámení typu fire-and-forget, která se opakují s exponenciálním backoffem — viz sémantika doručování.

Každý požadavek obsahuje časové razítko a podpis HMAC-SHA256 v X-ThunderPhone-Signature-V2 a také starší podpis X-ThunderPhone-Signature, který zahrnuje pouze tělo požadavku. Viz Ověření podpisu.

Funkční nástroje#

Funkční nástroj je koncový bod HTTP, který může váš agent volat uprostřed konverzace. ThunderPhone poskytnete schéma funkce ve stylu OpenAI spolu s URL koncového bodu; agent rozhodne, kdy jej zavolat, a ThunderPhone odešle ze svých serverů podepsaný požadavek HTTP a předá výsledek zpět agentovi.

Agenti také obsahují vestavěné možnosti pro hovory — přepojení hovoru, odeslání vstupu z klávesnice (DTMF), ukončení hovoru, čekání na lince — které povolíte běžnými řádky v promptu namísto definic nástrojů.

V dashboardu: sekce API připojení v nástroji pro vytváření (viz Připojení).

V API: /v1/integrations a specifikace funkčních nástrojů.

Tým a role#

Každá organizace má seznam členů se dvěma rolemi: Členové vytvářejí a provozují agenty; Administrátoři také spravují tým a fakturaci. Pozvěte je e-mailem — pozvánky vyprší po 7 dnech a lze je odvolat; nabídka ⋯ v řádku člena mění role nebo někoho odebere. Jednotné přihlášení lze nakonfigurovat pro celou organizaci — viz SSO.

V dashboardu: Organizace → Obecné. Viz Pozvěte svůj tým.

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

Fakturace#

ThunderPhone je předplacený. Každá organizace má zůstatek v USD; hovory jej odečítají podle minutové sazby agenta (úroveň enginu plus příplatky — nástroj pro vytváření zobrazuje celkovou sazbu živě při změně nastavení a vybrané další jazyky přidávají 3 ¢/min). Když zůstatek klesne na nulu, příchozí hovory jsou odmítnuty a odchozí hovory vrátí 402 Payment Required.

Doplňte kredit ručně nebo povolte automatické doplňování s prahem zůstatku, částkou doplnění a volitelným měsíčním limitem výdajů — aby hovor nikdy neskončil uprostřed věty.

V dashboardu: Organizace → Nastavení fakturace a Historie fakturace. Viz Přidejte prostředky a zapněte automatické doplňování a úplný přehled cen.

V API: /v1/billing.

Kopilot v aplikaci#

Dashboard obsahuje vestavěného kopilota — zeptejte se ho „jak udělám X“ a odpoví vám na základě této dokumentace, nabídne podrobné postupy kliknutí po kliknutí, které zvýrazní skutečné ovládací prvky, a může znovu přehrát kteroukoli z prohlídek. Je to nejrychlejší způsob, jak najít ovládací prvek, který tato stránka zmiňuje. Viz Zeptejte se kopilota v aplikaci.

Dejte to dohromady#