Getting Started

Základní koncepty

Přehled všeho na platformě — k čemu jednotlivé objekty slouží, kde je najdete na ovládacím panelu a které API je používá.

ThunderPhone je kompletní platforma pro vytváření, provozování a zlepšování hlasových AI agentů. Tato stránka je mapou: každý pojem, se kterým se setkáte, má vlastní krátkou část s odpovídající částí dashboardu a rozhraním API, které jej podporuje. Jednou ji prolétněte a vraťte se k ní, kdykoli bude potřeba některý pojem vysvětlit.

Postranní panel dashboardu tuto strukturu odráží:

Organizace#

Organizace je jednotka tenantství. Každý další prostředek — agenti, telefonní čísla, hovory, klíče — patří právě do jedné organizace. Váš účet může patřit do více 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. Právě toto propojení činí rozhraní REST API tak jednoduchým: do cest URL nikdy nezadáváte ID organizace, protože ji váš klíč už identifikuje.

V dashboardu: přepínač organizací (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á obsluhuje hovor. Zahrnuje:

• Prompt, který určuje, co agent říká a jak se chová — včetně akcí hovoru, jako jsou přepojení, stisky klávesnice 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 při komplexních promptech.
• 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é funkce: propojené aplikace, připojení API, znalostní báze, servery MCP a vložené funkční nástroje.
• Parametry chování: pořadí mluvení, režim potvrzování, zvuková stopa 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í je zachyceno na kartě Historie editoru, takže můžete zkontrolovat a obnovit jakoukoli předchozí verzi.

V dashboardu: Hlasoví agenti → editor agenta (/dashboard/agents). Viz Vytvoření prvního hlasového agenta.

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

Hlasy#

Knihovna hlasů obsahuje hlasy, které může agent používat, jejich přehratelné ukázky, kompatibilní jazyky, skupiny podle pohlaví a přízvuku a případné příplatky za prémiové hlasy nebo jazyky. Placený nástroj pro ukázku 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 asynchronní stav vytváření; po dokončení se zobrazí ve stejném výběru agentů jako hlasy z knihovny.

Na dashboardu: Hlasy (/dashboard/voices). Viz Knihovna hlasů 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 lze je použít pro odchozí hovory). Dva zdroje:

• Demo čísla — skutečná americká čísla zřízená z fondu ThunderPhone, aktivní během několika sekund. Jsou pouze pro příchozí hovory, odpovídají krátkým hlasovým upozorněním a dashboard omezuje organizaci na 10 těchto čísel. Ideální pro první test, nikoli pro produkční provoz.
• VoIP čísla — přenesená od vlastního poskytovatele prostřednictvím VoIP připojení. Twilio a Telnyx se připojují přímo (Telnyx nabízí provázené nastavení); SignalWire a Vonage budou brzy k dispozici — dnes je lze připojit přes ruční konfiguraci SIP, která podporuje libovolný SIP trunk. Po importu a ověření podporují VoIP čísla 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.

Na dashboardu: Telefonní čísla (/dashboard/phone-numbers). Viz Získejte telefonní číslo.

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 se značkami rolí, strukturovanou historii tahů (včetně volání nástrojů), nahrávku, celkovou cenu, volitelné hodnocení AI a hlášení problémů.

Když je hovor živý, můžete jej otevřít a poslouchat — připojíte se tiše a nikdo v hovoru vás neuslyší. Po připojení můžete našeptávat: napište pokyn, který během hovoru přejde přímo vašemu agentovi; volající jej nikdy neuslyší a agent se jím bude řídit v reálném čase.

Na dashboardu: Historie hovorů (/dashboard/call-history) pro archiv a podrobnosti jednotlivých hovorů; Živě pro probíhající hovory. Viz Kontrola, poslech a koučování hovorů.

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

Klientské portály#

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

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

V API: /v1/client-portals pro správu administrátory.

Webové widgety#

Webový widget umožňuje návštěvníkům vašeho webu vést konverzaci s hlasovým agentem pomocí mikrofonu — není potřeba telefonní číslo. Ověřuje se pomocí publikovatelného klíče (pk_live_...), který je omezen na zdroje z vašich povolených domén, takže jej lze bezpečně použít v kódu na straně klienta.

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

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

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

Znalostní báze#

Znalostní báze je sada dokumentů, ve kterých může váš agent během hovoru vyhledávat, aby své odpovědi opřel o relevantní informace — 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 jí dotazuje pomocí integrované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.

Připojení#

Připojení 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 Slacku, HubSpotu, Salesforce, Google Calendar, Google Sheets 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, aktualizace nebo vytvoření kontaktu v HubSpotu, rezervace termínu v Cal.com…). Viz Připojení aplikací.
• API (/dashboard/api-connections) — přeměňte libovolné HTTP API na 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 provede volání v sandboxu, než vše nasadíte. Viz Připojení API — rozhraní dashboardu pro /v1/integrations.
• MCP (/dashboard/mcp-connections) — přidejte server Model Context Protocol podle 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, takže externí klient MCP může zobrazit seznam agentů, prohlížet 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 pro 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 — u nichž se má pokus opakovat). Kampaň postupuje seznamem a zaznamenává každý hovor do historie hovorů.

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

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

Živé monitorování#

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

V dashboardu: Živě (/dashboard/live). Viz Sledování a dohled nad živými hovory.

Simulace#

Simulace je AI volající, 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 seskupují do sad, které stanovují minimální úspěšnost a mohou blokovat vydání v CI; regrese oproti přijatému základu se vykazují pro každý scénář.

V dashboardu: Simulace (/dashboard/simulations) a také tlačítko Simulace v editoru agenta. Viz Simulace hovoru.

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

Validační sady#

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

V dashboardu: Validační sady (/dashboard/validation) pro datovou sadu organizace a karta Validace v editoru agenta pro spuštění. 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 (různé prompty, enginy nebo nastavení), rozdělte mezi ně provoz a porovnejte výsledky pro jednotlivé varianty. Použijte jej namísto ruční implementace logiky bucketů ve webhooku.

V dashboardu: 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 u konkrétního hovoru — nahlášený lidským hodnotitelem 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.

V dashboardu: Problémy (/dashboard/issues) a také označování problémů u 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 o datech vašich hovorů („Jaké byly minulý týden tři hlavní důvody, proč volající požadovali člověka?“) pomocí analýzy vytvořené AI, omezené na agenty a časový rozsah, které zvolíte.

V dashboardu: Reporty (/dashboard/reports). Viz Reporty.

Observabilita#

Observabilita je plocha pro metriky: objem hovorů, výsledky a kvalita v čase, s možností filtrování podle agenta a časového okna a exportem pro následnou analýzu.

V dashboardu: Observabilita (/dashboard/observability). Viz Observabilita.

Upozornění#

Pravidlo upozornění sleduje metriku (úspěšnost, míru selhání, průměrné skóre, objem hovorů, regrese sad) v časovém okně a spustí se, když překročí váš práh. Oznámení se odesílají e-mailem a do Slacku a spouštějí událost alert.triggered pro vaše koncové body webhooku.

V dashboardu: Organizace → Upozornění. Viz Upozornění.

Webhooky#

ThunderPhone odesílá na váš server webhooky HTTP POST, když během hovoru a po něm dojde k událostem. Dva modely doručování:

• Koncové body webhooků (doporučeno): spravujte více adres URL na /v1/developer/webhook-endpoints se samostatnými tajnými klíči a odběry událostí pro každý koncový bod.
• Starší webhook s jednou adresou URL: jedna adresa URL pro každou organizaci. Spravuje se na /v1/webhook nebo v Organizace → Obecné. 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ího hovoru (telephony.incoming / web.incoming). Na odpověď máte až 10 sekund; při vypršení časového limitu hovor obslouží staticky přiřazený agent.
• Neblokující události jsou oznámení typu fire-and-forget, která se opakují s exponenciálním prodlužováním intervalů — viz sémantika doručování.

Každý požadavek obsahuje podpis HMAC-SHA256 v X-ThunderPhone-Signature. Viz ověření podpisu.

Funkční nástroje#

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

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

Na řídicím panelu: sekce Připojení API v nástroji pro vytváření (viz Připojení).

V rozhraní 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 členy e-mailem — pozvánky vyprší po 7 dnech a lze je odvolat; nabídka ⋯ na řádku člena umožňuje změnit roli nebo někoho odebrat. Jednotné přihlášení lze nakonfigurovat pro celou organizaci — viz SSO.

Na řídicím panelu: Organizace → Obecné. Viz Pozvěte svůj tým.

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

Fakturace#

ThunderPhone je předplacený. Každá organizace má zůstatek v USD; hovory z něj odečítají sazbu agenta za minutu (úroveň enginu a příplatky — nástroj pro vytváření zobrazuje celkovou sazbu v reálném čase při změně nastavení a vybrané další jazyky přidávají 3 ¢ za minutu). Když zůstatek dosáhne nuly, příchozí hovory jsou odmítnuty a odchozí hovory vrátí 402 Payment Required.

Dobijte zůstatek ručně nebo povolte automatické dobíjení s prahem zůstatku, částkou dobíjení a volitelným měsíčním limitem útrat — aby hovor nikdy neskončil uprostřed věty.

Na řídicím panelu: Organizace → Nastavení fakturace a Historie fakturace. Viz Přidejte prostředky a zapněte automatické dobíjení a kompletní přehled cen.

V rozhraní API: /v1/billing.

Kopilot v aplikaci#

Řídicí panel obsahuje vestavěného kopilota — zeptejte se jej „jak mohu provést X“ a odpoví na základě této dokumentace, nabídne prohlídky krok za krokem, které zvýrazní skutečné ovládací prvky, a může znovu spustit kteroukoli z prohlídek. Je to nejrychlejší způsob, jak najít ovládací prvek zmíněný na této stránce. Viz Zeptejte se kopilota v aplikaci.

Jak to celé spojit#