--- title: "Základní pojmy" description: "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: [Agenti](#agents), [hlasy](#voices), [telefonní čísla](#phone-numbers), [webové widgety](#web-widgets), [hovory](#calls), [klientské portály](#client-portals), [znalostní báze](#knowledge-bases). [Živé monitorování](#live-monitoring) a odchozí [kampaně](#campaigns). [Aplikace, rozhraní API, servery MCP a poskytovatelé VoIP](#connections), které mohou vaši agenti používat. [Simulace](#simulations), [validační sady](#validation-sets), [experimenty](#experiments), [problémy](#issues), [reporty](#reports), [pozorovatelnost](#observability). [Tým a role](#team-and-roles), [klíče API](#organizations), [upozornění](#alerts), [fakturace](#billing). [Webhooky](#webhooks) a [funkční nástroje](#function-tools) pro váš vlastní kód. --- ## 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](/cs/guides/organization-settings). **V rozhraní API:** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/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](/cs/guides/supported-languages). - Připojené schopnosti: [propojené aplikace](#connections), [připojení API](#connections), [znalostní báze](#knowledge-bases), [servery MCP](#connections) a vložené [funkční nástroje](#function-tools). - 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](/cs/guides/build-an-agent). **V rozhraní API:** [`/v1/agents`](/api-reference/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](/cs/guides/voice-library). **V API:** [`/v1/voices`](/api-reference/voices), [ukázky hlasů](/api-reference/voice-samples) a [vlastní hlasy](/api-reference/custom-voices). --- ## 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, {/* rate:phone */}1 $/měsíc plus příplatek 1 ¢ za minutu{/* /rate */}. 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](#connections). 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](/cs/guides/get-a-phone-number). **V API:** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/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ů](/cs/guides/review-calls). **V API:** [`/v1/calls`](/api-reference/calls) — seznam, přepis, historie, zvuk, hodnocení, export; [`/v1/issue-reports`](/api-reference/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](/cs/guides/client-portals). **V API:** [`/v1/client-portals`](/api-reference/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](/cs/guides/dynamic-call-config)). 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](/cs/guides/embed-a-web-widget-dashboard). **V API:** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) a [dokumentace Widget SDK](/cs/widget/overview). --- ## 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](/cs/guides/knowledge-base). --- ## 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í](/cs/guides/connect-apps). - **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](/cs/guides/api-connections) — rozhraní dashboardu pro [`/v1/integrations`](/api-reference/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](/cs/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`) — přihlašovací údaje poskytovatele pro [použití vlastních telefonních čísel](#phone-numbers). Viz [Připojení poskytovatele VoIP](/cs/guides/voip-providers). 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](/cs/guides/thunderphone-mcp-server). **V API:** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) a [`/v1/voip-connections`](/api-reference/voip-connections); viz také [Vytvoření integrace nástroje](/cs/guides/build-tool-integration). --- ## 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ů](/cs/guides/outbound-campaigns). **Pro jednorázové programové hovory:** [API pro odchozí hovory](/cs/guides/place-outbound-calls). ## Ž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](#calls) 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](/cs/guides/monitor-live-calls). --- ## 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](/cs/guides/simulate-a-call). **V API:** [`/v1/test-calls`](/api-reference/test-calls) a spouštěč sad — viz [Komplexní testování agenta](/cs/guides/test-agents). --- ## 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](/cs/guides/validation-sets). **V API:** [`/v1/validation-sets`](/api-reference/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í)](/cs/guides/experiments-ab-testing). --- ## 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ů](/cs/guides/issues). **V API:** [`/v1/issue-reports`](/api-reference/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](/cs/guides/reports). --- ## 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](/cs/guides/observability). --- ## 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ů](/cs/webhooks/endpoints). **Na řídicím panelu:** **Organizace → Upozornění**. Viz [Upozornění](/cs/guides/alerts). --- ## 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`](/cs/webhooks/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`](/api-reference/organizations#legacy-single-url-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ů](/cs/webhooks/call-incoming) (`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í](/cs/webhooks/overview). 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](/cs/webhooks/overview). --- ## 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í](#connections)). **V API:** [`/v1/integrations`](/api-reference/integrations) a [specifikace funkčních nástrojů](/cs/tools/overview). --- ## 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](/cs/guides/sso). **V dashboardu:** **Organizace → Obecné**. Viz [Pozvěte svůj tým](/cs/guides/invite-your-team). **V API:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/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](/cs/guides/supported-languages) přidávají {/* rate:language */}3 ¢/min{/* /rate */}). 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í](/cs/guides/billing-and-topups) a [úplný přehled cen](/cs/guides/pricing). **V API:** [`/v1/billing`](/api-reference/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](/cs/guides/ask-the-copilot). --- ## Dejte to dohromady Průvodce v pěti krocích: agent → fakturace → číslo → simulace → kontrola. Stejný první hovor ve čtyřech voláních REST. Vytvořte agenta, nabijte kredit, získejte číslo, simulujte a zkontrolujte hovory. Aplikace OAuth, vlastní API, servery MCP a poskytovatelé VoIP. Přehledy, pozorovatelnost, experimenty, problémy a upozornění. Pozvánky a role, klíče API, zabezpečení a SSO. Recepty pro API: příchozí a odchozí hovory, dynamická konfigurace, nástroje a testování. Správně nastavte kontrolu HMAC jednou a používejte ji všude.