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