> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Основные понятия
> Карта всего в платформе: что делает каждый объект, где он находится в панели управления и какой API с ним взаимодействует.
ThunderPhone — это полноценная платформа для создания, запуска и улучшения
голосовых ИИ-агентов. Эта страница — карта: все понятия, которые вам встретятся,
по одному короткому разделу для каждого, с соответствующими элементами панели управления
и API. Бегло просмотрите её один раз, а затем возвращайтесь, когда потребуется пояснение термина.
Боковая панель управления повторяет эту структуру:
[Агенты](#agents), [номера телефонов](#phone-numbers),
[веб-виджеты](#web-widgets), [звонки](#calls),
[базы знаний](#knowledge-bases).
[Мониторинг в реальном времени](#live-monitoring) и исходящие
[кампании](#campaigns).
[Приложения, API, серверы MCP и провайдеры VoIP](#connections), которые могут
использовать ваши агенты.
[Симуляции](#simulations), [эксперименты](#experiments),
[проблемы](#issues), [отчёты](#reports),
[наблюдаемость](#observability).
[Команда и роли](#team-and-roles), [ключи API](#organizations),
[оповещения](#alerts), [оплата](#billing).
[Вебхуки](#webhooks) и [инструменты функций](#function-tools) для
вашего кода.
***
## Организации
**Организация** — это единица изоляции. Каждый другой ресурс —
агенты, номера телефонов, звонки, ключи — принадлежит ровно одной организации. Ваша
учётная запись может состоять во многих организациях; у каждой есть собственный баланс,
собственные ключи и собственный список участников.
Ключ API `sk_live_`, который вы создаёте в разделе **Организация → Ключи**,
привязан к одной организации. Эта привязка делает REST API таким
простым: вам никогда не нужно указывать идентификатор организации в путях URL, поскольку ваш ключ
уже определяет её.
**В панели управления:** переключатель организаций (внизу боковой панели) и
настройки **Организация** — вкладки «Общие», «Ключи», «Оповещения», «Настройки оплаты»
и «История платежей».
**В 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,
дублирование, перевод, история версий и вспомогательные функции для промптов.
***
## Номера телефонов
**Номер телефона** принадлежит организации и направляет входящие звонки
агенту (а также может использоваться для исходящих звонков). Два источника:
* **Демонстрационные номера** — реальные номера США, предоставляемые из пула
ThunderPhone и готовые за несколько секунд. Только для входящих звонков:
они отвечают коротким голосовым уведомлением, а панель управления ограничивает
организацию 10 такими номерами. Идеально для первого теста, но не для
продакшена.
* **VoIP-номера** — подключаются от вашего провайдера через
[VoIP-подключение](#connections). Twilio и Telnyx подключаются напрямую
(для Telnyx доступна пошаговая настройка); SignalWire и Vonage появятся
в ближайшее время — сейчас их можно подключить через ручную настройку 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).
***
## Веб-виджеты
**Веб-виджет** позволяет посетителям вашего сайта общаться с агентом через
микрофон — номер телефона не требуется. Он аутентифицируется с помощью
**публичного ключа** (`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) и
[документация Widget SDK](/ru/widget/overview).
***
## Базы знаний
**База знаний** — это набор документов, в котором ваш агент может искать
информацию во время звонка для обоснования своих ответов: загружайте файлы
напрямую или импортируйте их из Google Drive, затем прикрепите базу знаний
к агенту в конструкторе. Агент обращается к ней с помощью встроенного
инструмента поиска, когда этого требует разговор.
**В панели управления:** **Знания** (`/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).
**В API:** [`/v1/integrations`](/api-reference/integrations) и
[`/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).
***
## Эксперименты
**Эксперимент** выполняет 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`). У вас есть до 10 секунд
на ответ; при тайм-ауте звонок обработает статически назначенный агент.
* **Неблокирующие события** — это уведомления без ожидания ответа, повторяемые
с экспоненциальной задержкой — см.
[семантику доставки](/ru/webhooks/overview).
Каждый запрос содержит подпись HMAC-SHA256 в
`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) добавляют 2¢/мин). Когда баланс достигает нуля, входящие звонки отклоняются, а исходящие возвращают `402 Payment Required`.
Пополняйте баланс вручную или включите **автопополнение**, задав порог баланса, сумму пополнения и необязательный месячный лимит расходов — чтобы звонок никогда не прерывался на середине фразы.
**В панели управления:** **Организация → Настройки биллинга** и
**История биллинга**. См. [Пополнение баланса и включение автопополнения](/ru/guides/billing-and-topups).
**В API:** [`/v1/billing`](/api-reference/billing).
***
## Встроенный копилот
В панели управления есть встроенный **копилот** — спросите его «как мне сделать X»,
и он ответит на основе этой документации, предложит пошаговые инструкции
с подсветкой реальных элементов управления и сможет повторно запустить любой из пошаговых
туров. Это самый быстрый способ найти элемент управления, упомянутый на этой странице.
См. [Как спросить встроенного копилота](/ru/guides/ask-the-copilot).
***
## Всё вместе
Мастер из 5 этапов: агент → биллинг → номер → симуляция → проверка.
Тот же первый звонок за 4 REST-вызова.
Создайте агента, пополните баланс, получите номер, проведите симуляцию и проверьте звонки.
OAuth-приложения, пользовательские API, MCP-серверы и VoIP-провайдеры.
Отчёты, наблюдаемость, эксперименты, проблемы и оповещения.
Приглашения и роли, API-ключи, безопасность и SSO.
Рецепты API: входящие, исходящие, динамическая конфигурация, инструменты, тестирование.
Один раз правильно настройте проверку HMAC и используйте её везде.