--- title: "Основні поняття" description: "Карта всього, що є на платформі: що робить кожен об’єкт, де він розташований у панелі керування та який API його використовує." --- ThunderPhone — це повна платформа для створення, запуску й покращення голосових агентів ШІ. Ця сторінка — ваша карта: кожна концепція, з якою ви зіткнетеся, описана в одному короткому розділі разом з інтерфейсом панелі керування та API, що її підтримує. Швидко перегляньте її один раз, а потім повертайтеся, коли потрібно уточнити значення терміна. Бічна панель керування відображає цю структуру: [Агенти](#agents), [голоси](#voices), [номери телефонів](#phone-numbers), [вебвіджети](#web-widgets), [дзвінки](#calls), [клієнтські портали](#client-portals), [бази знань](#knowledge-bases). [Моніторинг у реальному часі](#live-monitoring) і вихідні [кампанії](#campaigns). [Застосунки, API, сервери MCP і VoIP-провайдери](#connections), які можуть використовувати ваші агенти. [Симуляції](#simulations), [набори валідації](#validation-sets), [експерименти](#experiments), [проблеми](#issues), [звіти](#reports), [спостережуваність](#observability). [Команда й ролі](#team-and-roles), [ключі API](#organizations), [сповіщення](#alerts), [білінг](#billing). [Вебхуки](#webhooks) і [інструменти функцій](#function-tools) для вашого коду. --- ## Організації **Організація** — це одиниця ізоляції даних. Кожен інший ресурс — агенти, номери телефонів, дзвінки, ключі — належить рівно одній організації. Ваш обліковий запис може належати багатьом організаціям; кожна має власний баланс, власні ключі та власний список учасників. Ключ API `sk_live_`, який ви створюєте в розділі **Організація → Ключі**, прив’язаний до однієї організації. Саме ця прив’язка робить REST API таким простим: вам ніколи не потрібно вказувати ідентифікатор організації в шляхах URL, оскільки ваш ключ уже її визначає. **У панелі керування:** перемикач організацій (у нижній частині бічної панелі) та налаштування **Організація** — вкладки Мій обліковий запис, Загальні, Ключі, Сповіщення, Налаштування білінгу та Історія білінгу. Див. [довідник налаштувань організації](/uk/guides/organization-settings). **В API:** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/developer-api-keys). --- ## Агенти **Агент** — це конфігурація ШІ, яка обробляє дзвінок. Вона містить: - **Промпт**, який визначає, що каже агент і як він поводиться — зокрема дії під час дзвінка, як-от переведення дзвінка, натискання клавіш і завершення виклику; це звичайні рядки промпту, а не окрема конфігурація. - **Рівень рушія** (`spark`, `bolt`, `storm-*`): Spark оптимізований для вартості, Bolt — для швидкості, Storm — для інтелектуальної роботи зі складними промптами. - **Голос**, а також **основну мову** й необов’язкові **додаткові мови** — агент автоматично перемикається, коли абонент змінює мову. Див. [Підтримувані мови](/uk/guides/supported-languages). - Підключені можливості: [підключені застосунки](#connections), [підключення API](#connections), [бази знань](#knowledge-bases), [сервери MCP](#connections) і вбудовані [інструменти функцій](#function-tools). - Налаштування поведінки: порядок мовлення, режим підтвердження, фоновий трек, тайм-аут утримання. Зміни в конструкторі **автоматично зберігаються як чернетка**; вони не потрапляють у продакшн, доки ви не натиснете **Розгорнути**. Кожне розгортання зберігається як знімок на вкладці **Історія** конструктора, тому ви можете переглянути та відновити будь-яку попередню версію. **У панелі керування:** **Голосові агенти** → конструктор агента (`/dashboard/agents`). Див. [Створіть свого першого голосового агента](/uk/guides/build-an-agent). **В API:** [`/v1/agents`](/api-reference/agents) — CRUD, дублювання, переведення, історія версій і допоміжні засоби для промптів. --- ## Голоси **Бібліотека голосів** містить голоси, які може використовувати агент, їхні відтворювані зразки, сумісні мови, групування за статтю й акцентом, а також будь-яку доплату за преміумголос або мову. Платний інструмент для зразків може синтезувати вашу власну фразу з 1–500 символів, перш ніж ви зробите вибір. Організації, що відповідають вимогам, також можуть створювати **власні голоси** з короткого зразка WAV або MP3. Власні голоси мають квоту та асинхронний статус створення; після готовності вони з’являються в тому самому списку вибору агентів, що й голоси з бібліотеки. **У панелі керування:** **Голоси** (`/dashboard/voices`). Див. [Бібліотека голосів і власні голоси](/uk/guides/voice-library). **В API:** [`/v1/voices`](/api-reference/voices), [зразки голосів](/api-reference/voice-samples) і [власні голоси](/api-reference/custom-voices). --- ## Номери телефонів **Номер телефону** належить організації та спрямовує вхідні дзвінки до агента (а також може використовуватися для вихідних дзвінків). Є два джерела: - **Номери ThunderPhone** — реальні номери США, надані з пулу ThunderPhone, активні за лічені секунди, {/* rate:phone */}$1/місяць плюс 1¢/хвилину{/* /rate */} доплати. Спочатку вони доступні лише для вхідних дзвінків. Адміністратор організації може подати запит на вихідні дзвінки на сторінці «Номери телефонів»; ThunderPhone розглядає кожен запит вручну, а схвалені номери можуть здійснювати дзвінки та запускати кампанії. За замовчуванням організація може мати 25 номерів. - **VoIP-номери** — додаються від вашого постачальника через [VoIP-підключення](#connections). Twilio та Telnyx підключаються безпосередньо за допомогою ключа API (Telnyx також має кероване налаштування нового облікового запису); SignalWire, Vonage, Plivo та будь-які інші SIP-транки підключаються через налаштування SIP — ручну конфігурацію SIP. Після імпорту та перевірки VoIP-номери підтримують вхідні й вихідні дзвінки. У кожному рядку номера можна налаштувати режим маршрутизації, вибрати агента для вхідних дзвінків і додати мітку номера. **У панелі керування:** **Номери телефонів** (`/dashboard/phone-numbers`). Див. [Отримати номер телефону](/uk/guides/get-a-phone-number). **В API:** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/phone-number-labels). --- ## Дзвінки Кожен вхідний дзвінок, вихідний дзвінок, симуляція та сеанс віджета стає **журналом дзвінка**. Дзвінок містить повний транскрипт із позначенням ролей, структуровану історію ходів (зокрема виклики інструментів), запис, загальну суму списань, а також необов’язкове оцінювання ШІ та звіти про проблеми. Поки дзвінок **триває**, ви можете відкрити його та **прослуховувати** — ви підключаєтеся беззвучно, і ніхто під час дзвінка вас не чує. Під час прослуховування ви можете **шепотіти**: введіть інструкцію, яка надсилається безпосередньо вашому агенту посеред дзвінка; абонент ніколи її не чує, а агент виконує її в реальному часі. **У панелі керування:** **Історія дзвінків** (`/dashboard/call-history`) для архіву та відомостей про кожен дзвінок; **Наживо** для дзвінків, що тривають. Див. [Перегляд, прослуховування та супровід ваших дзвінків](/uk/guides/review-calls). **В API:** [`/v1/calls`](/api-reference/calls) — список, транскрипт, історія, аудіо, оцінювання, експорт; [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Клієнтські портали **Клієнтський портал** — це брендований режим лише для читання для перегляду історії дзвінків зовнішнім клієнтом. Адміністратори організації вибирають агентів, дзвінки яких відображатимуться, додають схвалені електронні адреси глядачів, завантажують логотип і акцентний колір, а також за потреби перевіряють власний домен. Глядачі порталу можуть переглядати відомості про дзвінки, транскрипти та доступні записи, не отримуючи доступу до панелі керування. **У панелі керування:** **Клієнтські портали** (`/dashboard/client-portals`). Див. [Клієнтські портали](/uk/guides/client-portals). **В API:** [`/v1/client-portals`](/api-reference/client-portals) для поверхні адміністрування. ## Вебвіджети **Вебвіджет** надає відвідувачам вашого сайту розмову з агентом через мікрофон без потреби в номері телефону. Він автентифікується за допомогою **публічного ключа** (`pk_live_...`), який браузери можуть використовувати лише з дозволених вами доменів, тому його безпечно використовувати в клієнтському коді. Список доменів не є автентифікацією, а налаштування сесії, які може надсилати сторінка, вимкнені, доки ви не дозволите їх для ключа. Ключі працюють в одному з двох режимів: `agent` (статично прив’язаний до одного агента) або `webhook` (ваш сервер вибирає конфігурацію для кожного відвідувача — див. [Динамічна конфігурація для кожного виклику](/uk/guides/dynamic-call-config)). Сесії віджета використовують ту саму інфраструктуру викликів, що й телефонні виклики. **На панелі керування:** **Вебвіджети** (`/dashboard/web-widgets`) — створюйте віджети, задавайте режим і агента, керуйте дозволеними доменами та копіюйте фрагмент для вбудовування. Див. [Створення вебвіджета](/uk/guides/embed-a-web-widget-dashboard). **В API:** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) і [документація Widget SDK](/uk/widget/overview). --- ## Бази знань **База знань** — це набір документів, у якому ваш агент може шукати інформацію під час виклику, щоб обґрунтовувати свої відповіді: завантажуйте файли, вставляйте текст або імпортуйте вебсторінки за URL, а потім прикріплюйте базу знань до агента в конструкторі. Агент використовує вбудований інструмент пошуку, коли цього потребує розмова. **На панелі керування:** **Знання** (`/dashboard/knowledge`) для бібліотеки документів; розділ **Знання** в конструкторі, щоб прикріпити базу до агента. Див. [Додайте базу знань своєму агенту](/uk/guides/knowledge-base). --- ## Підключення Підключення дають агентам доступ до зовнішнього світу. Чотири типи, одна група на бічній панелі: - **Застосунки** (`/dashboard/app-connections`) — OAuth-підключення до Slack, HubSpot, Salesforce, Google Calendar, Google Sheets і Cal.com. Підключіться один раз, а потім увімкніть для будь-якого агента інструменти для окремих операцій (надіслати повідомлення в Slack, оновити або створити контакт у HubSpot, забронювати слот у Cal.com…). Див. [Підключення застосунків](/uk/guides/connect-apps). - **API** (`/dashboard/api-connections`) — перетворюйте будь-який HTTP API на дію агента. Вставте команду cURL, і майстер ШІ створить чернетку визначення інструмента, або створіть його вручну; кнопка **Тестовий запит** виконує виклик у пісочниці перед розгортанням. Див. [Підключення API](/uk/guides/api-connections) — інтерфейс панелі керування для [`/v1/integrations`](/api-reference/integrations). - **MCP** (`/dashboard/mcp-connections`) — додайте сервер Model Context Protocol за URL і дозвольте агенту використовувати інструменти, які він надає. Див. [Додавання MCP-сервера](/uk/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`) — облікові дані постачальника для [використання власних телефонних номерів](#phone-numbers). Див. [Підключення VoIP-постачальника](/uk/guides/voip-providers). ThunderPhone також надає власну кінцеву точку MCP, щоб зовнішній клієнт MCP міг перелічувати агентів, переглядати виклики й транскрипти та здійснювати виклики. Див. [Використання ThunderPhone як MCP-сервера](/uk/guides/thunderphone-mcp-server). **В API:** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) і [`/v1/voip-connections`](/api-reference/voip-connections); також див. [Створення інтеграції інструмента](/uk/guides/build-tool-integration). --- ## Кампанії **Кампанія** здійснює масові вихідні виклики: завантажте CSV із контактами, виберіть агента та номер для викликів, а також налаштуйте вікно дзвінків (дні й години з урахуванням часового поясу), паралельність і політику повторних спроб (максимальну кількість спроб і результати — немає відповіді, голосова пошта, помилка — для яких виконуватимуться повторні спроби). Кампанія проходить список і записує кожен виклик в Історії викликів. **На панелі керування:** **Кампанії** (`/dashboard/campaigns`). Див. [Запуск кампанії вихідних викликів](/uk/guides/outbound-campaigns). **Для одноразових програмних викликів:** [API вихідних викликів](/uk/guides/place-outbound-calls). ## Моніторинг у реальному часі **Наживо** показує всі активні дзвінки в організації та дає змогу відкрити будь-який із них, щоб [слухати та підказувати пошепки](#calls) у реальному часі. Це інтерфейс нагляду: стежте, як новий промпт отримує перший реальний трафік, або контролюйте активну кампанію. **У дашборді:** **Наживо** (`/dashboard/live`). Див. [Перегляд і нагляд за дзвінками наживо](/uk/guides/monitor-live-calls). --- ## Симуляції **Симуляція** — це ШІ-абонент, який веде реальну розмову з вашим агентом: той самий шлях телефонії, реальна транскрипція, реальне оцінювання. Це дає змогу тестувати до (і після) розгортання. Спрямуйте її на агента або номер телефону, самостійно опишіть сценарій абонента або **згенеруйте сценарії за допомогою ШІ** з промпту агента (зокрема крайові випадки, якщо ви їх запитаєте) і спостерігайте за дзвінком наживо. Сценарії об’єднуються в **набори**, які фіксують мінімальний відсоток успішного проходження та можуть блокувати релізи в CI; регресії щодо прийнятого базового рівня відображаються для кожного сценарію. **У дашборді:** **Симуляції** (`/dashboard/simulations`), а також кнопка **Симуляція** в конструкторі агента. Див. [Симуляція дзвінка](/uk/guides/simulate-a-call). **В API:** [`/v1/test-calls`](/api-reference/test-calls) і запускач наборів — див. [Наскрізне тестування агента](/uk/guides/test-agents). --- ## Набори валідації **Набір валідації** перетворює моменти реальних дзвінків на повторювані одноходові перевірки регресій. Кожен приклад фіксує контекст розмови, релевантне аудіо абонента, початкову відповідь і очікувану поведінку. Повторне відтворення виконується для поточного чернеткового варіанта агента без здійснення нового дзвінка, а діалог розгортання може показати, чи останній запуск досі відповідає цій чернетці. **У дашборді:** **Набори валідації** (`/dashboard/validation`) для набору даних організації та вкладка **Валідація** в конструкторі агента для запусків. Див. [Набори валідації](/uk/guides/validation-sets). **В API:** [`/v1/validation-sets`](/api-reference/validation-sets) і кінцеві точки повторного відтворення агента/прикладу на тій самій довідковій сторінці. --- ## Експерименти **Експеримент** виконує A/B-тестування конфігурацій агента на реальному трафіку: визначте варіанти (різні промпти, рушії або налаштування), розподіліть між ними трафік і порівняйте результати для кожного варіанта. Використовуйте його замість ручної реалізації логіки розподілу у вебхуку. **У дашборді:** **Експерименти** (`/dashboard/experiments`) і вкладка **A/B** у конструкторі агента. Див. [Експерименти (A/B-тестування)](/uk/guides/experiments-ab-testing). --- ## Проблеми **Проблема** — це позначена проблема в конкретному дзвінку, яку створив рецензент-людина або виявило оцінювання ШІ. Проблеми містять рівень серйозності, джерело та статус, а сторінка проблем є чергою тріажу: фільтруйте, переглядайте проблемний дзвінок і відстежуйте виправлення. **У дашборді:** **Проблеми** (`/dashboard/issues`), а також позначення для кожного дзвінка в історії дзвінків. Див. [Тріаж проблем](/uk/guides/issues). **В API:** [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Звіти **Звіт** відповідає на запитання природною мовою про дані ваших дзвінків («Які три найпоширеніші причини, через які абоненти просили з’єднати з людиною минулого тижня?») за допомогою аналізу, створеного ШІ та обмеженого вибраними вами агентами й діапазоном дат. **У дашборді:** **Звіти** (`/dashboard/reports`). Див. [Звіти](/uk/guides/reports). --- ## Спостережуваність **Спостережуваність** — це інтерфейс метрик: обсяг дзвінків, результати та якість із плином часу з можливістю фільтрування за агентом і часовим вікном, а також експорту для подальшого аналізу. **У дашборді:** **Спостережуваність** (`/dashboard/observability`). Див. [Спостережуваність](/uk/guides/observability). --- ## Сповіщення **Правило сповіщення** відстежує метрику (відсоток успіху, відсоток помилок, середній бал, обсяг дзвінків, регресії набору) у часовому вікні та спрацьовує, коли вона перетинає заданий вами поріг. Сповіщення надсилаються електронною поштою та в Slack, а також генерують подію `alert.triggered` для ваших [кінцевих точок вебхуків](/uk/webhooks/endpoints). **У дашборді:** **Організація → Сповіщення**. Див. [Сповіщення](/uk/guides/alerts). --- ## Вебхуки ThunderPhone надсилає **вебхуки HTTP POST** на ваш сервер, коли щось відбувається під час і після дзвінка. Є дві моделі доставки: - **Кінцеві точки вебхуків** (рекомендовано): керуйте багатьма URL за адресою [`/v1/developer/webhook-endpoints`](/uk/webhooks/endpoints) із окремими секретами та підписками на події для кожної кінцевої точки. - **Застарілий вебхук з однією URL-адресою**: одна URL-адреса на організацію. Керується через [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) або в розділі **Організація → Загальні**. Збережено для зворотної сумісності. Події поділяються на два класи: - **Блокувальні події** очікують, що ваш сервер поверне конфігурацію, яка визначає перебіг активного дзвінка — це [події вхідного дзвінка](/uk/webhooks/call-incoming) (`telephony.incoming` / `web.incoming`). Телефонний дзвінок очікує до 13 секунд, включно з однією повторною спробою, а сеанс віджета — 10 секунд. Резервного агента немає: без придатної конфігурації телефонний дзвінок завершується, а сеанс віджета зазнає помилки. - **Неблокувальні події** — це сповіщення без очікування відповіді, що повторюються з експоненційною затримкою — див. [семантику доставки](/uk/webhooks/overview). Кожен запит містить HMAC-SHA256 підпис із позначкою часу в `X-ThunderPhone-Signature-V2`, а також застарілий підпис лише для тіла `X-ThunderPhone-Signature`. Див. [Перевірка підпису](/uk/webhooks/overview). --- ## Інструменти-функції **Інструмент-функція** — це кінцева точка HTTP, яку ваш агент може викликати під час розмови. Ви надаєте ThunderPhone схему функції у стилі OpenAI та URL-адресу кінцевої точки; агент вирішує, коли її викликати, а ThunderPhone надсилає підписаний HTTP-запит зі своїх серверів і передає результат агенту. Агенти також мають **вбудовані можливості для дзвінків** — переведення дзвінка, надсилання введення з клавіатури (DTMF), завершення дзвінка, очікування на утриманні — які ви вмикаєте звичайними рядками в промпті, а не визначеннями інструментів. **У панелі керування:** розділ конструктора **Підключення API** (див. [Підключення](#connections)). **В API:** [`/v1/integrations`](/api-reference/integrations) та [специфікація Function Tools](/uk/tools/overview). --- ## Команда та ролі Кожна організація має список учасників із двома ролями: **Учасники** створюють і керують агентами; **Адміністратори** також керують командою та оплатою. Надсилайте запрошення електронною поштою — вони спливають через 7 днів і їх можна відкликати; меню ⋯ у рядку учасника змінює ролі або видаляє користувача. Єдиний вхід можна налаштувати для всієї організації — див. [SSO](/uk/guides/sso). **У панелі керування:** **Організація → Загальні**. Див. [Запросіть свою команду](/uk/guides/invite-your-team). **В API:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/invites). --- ## Оплата ThunderPhone працює за моделлю **передоплати**. Кожна організація має баланс у доларах США; вартість дзвінків списується за похвилинним тарифом агента (рівень рушія та додаткові нарахування — конструктор показує повний тариф у реальному часі, коли ви змінюєте налаштування, а [вибрані додаткові мови](/uk/guides/supported-languages) додають {/* rate:language */}3 ¢/хв{/* /rate */}). Коли баланс стає нульовим, вхідні дзвінки відхиляються, а вихідні дзвінки повертають `402 Payment Required`. Поповнюйте баланс вручну або увімкніть **автоматичне поповнення** з порогом балансу, сумою поповнення та необов'язковим місячним лімітом витрат — щоб дзвінок ніколи не обривався посеред речення. **У панелі керування:** **Організація → Налаштування оплати** та **Історія оплат**. Див. [Додайте кошти та увімкніть автоматичне поповнення](/uk/guides/billing-and-topups), а також [повний довідник цін](/uk/guides/pricing). **В API:** [`/v1/billing`](/api-reference/billing). --- ## Вбудований copilot Панель керування має вбудований **copilot** — запитайте його «як мені зробити X», і він відповість на основі цієї документації, запропонує покрокові інструкції з підсвічуванням реальних елементів керування та може повторно відтворити будь-який із навчальних турів. Це найшвидший спосіб знайти елемент керування, згаданий на цій сторінці. Див. [Запитайте вбудований copilot](/uk/guides/ask-the-copilot). --- ## Збираємо все разом П’ятиетапний майстер: агент → оплата → номер → симуляція → перевірка. Той самий перший виклик у чотирьох REST-викликах. Створіть агента, поповніть баланс, отримайте номер, виконайте симуляцію та перегляньте виклики. OAuth-застосунки, власні API, сервери MCP і провайдери VoIP. Звіти, спостережуваність, експерименти, проблеми та сповіщення. Запрошення та ролі, ключі API, безпека й SSO. Рецепти API: вхідні, вихідні, динамічна конфігурація, інструменти, тестування. Один раз правильно налаштуйте перевірку HMAC і використовуйте її всюди.