Основные понятия

Карта всех элементов платформы: что делает каждый объект, где он находится в панели управления и какой API с ним взаимодействует.

ThunderPhone — это полноценная платформа для создания, запуска и улучшения голосовых ИИ-агентов. Эта страница — карта: каждый концепт, с которым вы столкнётесь, описан в одном коротком разделе вместе с интерфейсом панели управления и API, который его поддерживает. Бегло прочитайте её один раз, а затем возвращайтесь, когда потребуется пояснение термина.

Боковая панель управления отражает эту структуру:

Организации#

Организация — это единица изоляции в многопользовательской среде. Каждый другой ресурс — агенты, номера телефонов, звонки, ключи — принадлежит ровно одной организации. Ваша учётная запись может состоять в нескольких организациях; у каждой есть собственный баланс, собственные ключи и список участников.

API-ключ sk_live_, созданный в разделе Организация → Ключи, привязан к одной организации. Благодаря этой привязке REST API имеет такую простую структуру: вам не нужно указывать идентификатор организации в URL-путях, поскольку ключ уже определяет её.

В панели управления: переключатель организаций в нижней части боковой панели и настройки Организация — вкладки «Моя учётная запись», «Общие», «Ключи», «Оповещения», «Настройки оплаты» и «История платежей». См. справочник по настройкам организации.

В API: /v1/orgs, /v1/developer/api-keys.

Агенты#

Агент — это конфигурация ИИ, которая обрабатывает звонок. Она включает:

• Промпт, определяющий, что говорит агент и как он себя ведёт, — включая действия со звонком, такие как переводы, нажатия клавиш и завершение вызова, которые задаются обычными строками промпта, а не отдельной конфигурацией.
• Уровень движка (spark, bolt, storm-*): Spark оптимизирован по стоимости, Bolt — по скорости, Storm — по интеллекту для сложных промптов.
• Голос, а также основной язык и необязательные дополнительные языки — агент автоматически переключается, когда звонящий меняет язык. См. Поддерживаемые языки.
• Подключённые возможности: подключённые приложения, API-подключения, базы знаний, MCP-серверы и встроенные инструменты функций.
• Параметры поведения: порядок речи, режим подтверждения, фоновая дорожка, тайм-аут удержания.

Изменения в конструкторе автоматически сохраняются в черновик; они не публикуются, пока вы не нажмёте Развернуть. Каждый деплой сохраняется в виде снимка на вкладке История конструктора, поэтому вы можете проверить и восстановить любую предыдущую версию.

В панели управления: Голосовые агенты → конструктор агента (/dashboard/agents). См. Создайте своего первого голосового агента.

В API: /v1/agents — CRUD, дублирование, перевод, история версий и вспомогательные функции для промптов.

Голоса#

Библиотека голосов содержит голоса, которые может использовать агент, их доступные для прослушивания образцы, поддерживаемые языки, группы по полу и акценту, а также доплаты за премиальные голоса и языки. Платный предпросмотр позволяет синтезировать собственную фразу длиной от 1 до 500 символов перед выбором.

Подходящие организации также могут создавать пользовательские голоса на основе короткого образца в формате WAV или MP3. Для пользовательских голосов действует квота и асинхронный статус создания; после готовности они отображаются в том же средстве выбора агента, что и голоса из библиотеки.

В панели управления: Голоса (/dashboard/voices). См. Библиотека голосов и пользовательские голоса.

В API: /v1/voices, образцы голосов и пользовательские голоса.

Номера телефонов#

Номер телефона принадлежит организации и направляет входящие звонки агенту (а также может использоваться для исходящих звонков). Есть два источника:

• Номера ThunderPhone — реальные номера США, предоставляемые из пула ThunderPhone и активируемые за несколько секунд, $1/месяц плюс доплата 1¢/минуту. Изначально они поддерживают только входящие вызовы. Администратор организации может запросить исходящие вызовы на странице «Номера телефонов»; ThunderPhone вручную проверяет каждый запрос, а одобренные номера могут совершать звонки и запускать кампании. По умолчанию организация может иметь до 25 номеров.
• VoIP-номера — номера от вашего собственного провайдера, подключаемые через VoIP-подключение. Twilio и Telnyx подключаются напрямую с помощью API-ключа (Telnyx также предлагает пошаговую настройку новой учётной записи); SignalWire, Vonage, Plivo и любые другие SIP-транки подключаются через настройку SIP — ручную конфигурацию SIP. После импорта и проверки VoIP-номера поддерживают входящие и исходящие вызовы.

В каждой строке номера можно задать режим маршрутизации, выбрать агента для входящих звонков и добавить метку номера.

В панели управления: Номера телефонов (/dashboard/phone-numbers). См. Получить номер телефона.

В API: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Звонки#

Каждый входящий звонок, исходящий звонок, симуляция и сеанс виджета становятся журналом звонка. Звонок содержит полную расшифровку с указанием ролей, структурированную историю реплик (включая вызовы инструментов), запись, итоговую стоимость, а также при необходимости оценку ИИ и отчёты о проблемах.

Пока звонок активен, его можно открыть и подключиться к прослушиванию — вы подключаетесь беззвучно, и никто из участников звонка вас не слышит. После подключения к прослушиванию можно шепнуть: введите инструкцию, которая сразу поступит вашему агенту во время звонка; звонящий её не услышит, а агент выполнит её в реальном времени.

В панели управления: История звонков (/dashboard/call-history) для архива и сведений по каждому звонку; В реальном времени для текущих звонков. См. Просматривайте, прослушивайте и сопровождайте свои звонки.

В API: /v1/calls — список, расшифровка, история, аудио, оценка, экспорт; /v1/issue-reports.

Клиентские порталы#

Клиентский портал — это брендированный режим просмотра истории звонков только для чтения для внешнего клиента. Администраторы организации выбирают агентов, звонки которых отображаются, добавляют адреса электронной почты одобренных пользователей, загружают логотип и задают акцентный цвет, а также при необходимости подтверждают пользовательский домен. Пользователи портала могут просматривать сведения о звонках, расшифровки и доступные записи без доступа к панели управления.

В панели управления: Клиентские порталы (/dashboard/client-portals). См. Клиентские порталы.

В API: /v1/client-portals для интерфейса администрирования.

Веб-виджеты#

Веб-виджет предоставляет посетителям вашего сайта разговор с агентом через микрофон — номер телефона не нужен. Он аутентифицируется с помощью публикуемого ключа (pk_live_...), который браузеры могут использовать только с разрешённых вами доменов, поэтому его безопасно применять в клиентском коде. Список доменов не является аутентификацией, а настройки сеанса, которые может отправлять страница, отключены, пока вы не разрешите их для ключа.

Ключи работают в одном из двух режимов: agent (статически привязан к одному агенту) или webhook (ваш сервер выбирает конфигурацию для каждого посетителя — см. Динамическая конфигурация для каждого звонка). Сеансы виджета используют ту же инфраструктуру звонков, что и телефонные звонки.

На панели управления: Веб-виджеты (/dashboard/web-widgets) — создавайте виджеты, задавайте режим и агента, управляйте разрешёнными доменами и копируйте код для встраивания. См. Создание веб-виджета.

В API: /v1/publishable-key, /v1/mic-session и документация SDK виджета.

Базы знаний#

База знаний — это набор документов, в которых ваш агент может искать информацию во время звонка, чтобы обосновывать свои ответы: загружайте файлы, вставляйте текст или импортируйте веб-страницы по URL, затем подключайте базу знаний к агенту в конструкторе. Агент обращается к ней с помощью встроенного инструмента поиска, когда этого требует разговор.

На панели управления: Знания (/dashboard/knowledge) для библиотеки документов; раздел Знания в конструкторе, чтобы подключить базу к агенту. См. Добавление базы знаний агенту.

Подключения#

Подключения позволяют агентам взаимодействовать с внешним миром. Четыре типа, одна группа на боковой панели:

• Приложения (/dashboard/app-connections) — OAuth-подключения к Slack, HubSpot, Salesforce, Google Calendar, Google Sheets и Cal.com. Подключитесь один раз, затем включайте для любого агента инструменты отдельных операций (отправить сообщение в Slack, создать или обновить контакт HubSpot, забронировать слот Cal.com…). См. Подключение приложений.
• API (/dashboard/api-connections) — превратите любой HTTP API в действие агента. Вставьте команду cURL, и мастер ИИ создаст черновик определения инструмента, или настройте его вручную; кнопка Тестовый запрос выполняет вызов в песочнице перед выпуском в продакшен. См. Подключения API — интерфейс панели управления для /v1/integrations.
• MCP (/dashboard/mcp-connections) — добавьте сервер Model Context Protocol по URL и разрешите агенту использовать предоставляемые им инструменты. См. Добавление MCP-сервера.
• VoIP (/dashboard/voip-connections) — учётные данные провайдера для подключения собственных номеров телефонов. См. Подключение VoIP-провайдера.

ThunderPhone также предоставляет собственную конечную точку MCP, чтобы внешний клиент MCP мог просматривать список агентов, проверять звонки и расшифровки, а также совершать звонки. См. Использование ThunderPhone в качестве MCP-сервера.

В API: /v1/integrations, /v1/mcp-servers и /v1/voip-connections; также см. Создание интеграции инструмента.

Кампании#

Кампания совершает исходящие звонки в масштабе: загрузите CSV-файл контактов, выберите агента и номер, с которого будут совершаться звонки, а также задайте окно звонков (дни и часы с учётом часового пояса), параллельность и политику повторных попыток (максимальное число попыток и результаты — нет ответа, голосовая почта, сбой, — для которых будут выполняться повторные попытки). Кампания последовательно обрабатывает список и записывает каждый звонок в историю звонков.

На панели управления: Кампании (/dashboard/campaigns). См. Запуск кампании исходящих звонков.

Для разовых программных звонков: используйте API исходящих звонков.

Мониторинг в реальном времени#

В реальном времени отображаются все текущие звонки в организации и позволяют открыть любой из них, чтобы прослушивать разговор и давать подсказки в реальном времени. Это интерфейс контроля: следите за первым реальным трафиком нового промпта или контролируйте запущенную кампанию.

В панели управления: В реальном времени (/dashboard/live). См. Просмотр и контроль звонков в реальном времени.

Симуляции#

Симуляция — это ИИ-звонящий, который ведёт реальный разговор с вашим агентом: тот же путь телефонии, настоящая расшифровка, реальная оценка. Это позволяет тестировать до и после выпуска. Укажите агента или номер телефона, самостоятельно опишите сценарий звонящего или создайте сценарии с помощью ИИ на основе промпта агента (включая пограничные случаи, если попросите) и наблюдайте за звонком в реальном времени.

Сценарии объединяются в наборы, которые фиксируют минимальный процент успешных прохождений и могут блокировать релизы в CI; регрессии относительно принятого базового уровня отображаются для каждого сценария.

В панели управления: Симуляции (/dashboard/simulations), а также кнопка Симуляция в конструкторе агента. См. Симуляция звонка.

В API: /v1/test-calls и средство запуска наборов — см. Сквозное тестирование агента.

Наборы валидации#

Набор валидации превращает реальные моменты звонков в повторяемые одношаговые проверки регрессий. Каждый пример фиксирует контекст разговора, релевантное аудио звонящего, исходный ответ и ожидаемое поведение. Повторные запуски выполняются для текущего черновика агента без нового звонка, а диалог развёртывания может показывать, соответствует ли последний запуск этому черновику.

В панели управления: Наборы валидации (/dashboard/validation) для набора данных организации и вкладка Валидация в конструкторе агента для запусков. См. Наборы валидации.

В API: /v1/validation-sets и конечные точки повторного запуска агента и примеров на той же справочной странице.

Эксперименты#

Эксперимент выполняет A/B-тестирование конфигураций агента на реальном трафике: определите варианты (разные промпты, движки или настройки), разделите между ними трафик и сравните результаты для каждого варианта. Используйте его вместо самостоятельной реализации логики сегментов в вебхуке.

В панели управления: Эксперименты (/dashboard/experiments) и вкладка A/B в конструкторе агента. См. Эксперименты (A/B-тестирование).

Проблемы#

Проблема — это отмеченная неполадка в конкретном звонке, зарегистрированная рецензентом или обнаруженная ИИ при оценке. Проблемы содержат уровень серьёзности, источник и статус, а страница проблем служит очередью для триажа: фильтруйте, проверяйте проблемный звонок и отслеживайте исправления.

В панели управления: Проблемы (/dashboard/issues), а также отметка проблемы для каждого звонка в истории звонков. См. Триаж проблем.

В API: /v1/issue-reports.

Отчёты#

Отчёт отвечает на вопрос на естественном языке о данных ваших звонков («По каким трём основным причинам звонящие просили соединить с человеком на прошлой неделе?») с помощью анализа, созданного ИИ и ограниченного выбранными вами агентами и диапазоном дат.

В панели управления: Отчёты (/dashboard/reports). См. Отчёты.

Наблюдаемость#

Наблюдаемость — это интерфейс метрик: объём звонков, результаты и качество с течением времени с фильтрацией по агенту и временному окну, а также экспортом для последующего анализа.

В панели управления: Наблюдаемость (/dashboard/observability). См. Наблюдаемость.

Оповещения#

Правило оповещения отслеживает метрику (долю успешных звонков, долю неудачных звонков, среднюю оценку, объём звонков, регрессии наборов) за временное окно и срабатывает, когда она пересекает заданный порог. Уведомления отправляются по email и в Slack, а также отправляется событие alert.triggered в ваши конечные точки вебхуков.

В панели управления: Организация → Оповещения. См. Оповещения.

Вебхуки#

ThunderPhone отправляет HTTP POST-вебхуки на ваш сервер, когда во время и после звонка происходят события. Две модели доставки:

• Конечные точки вебхуков (рекомендуется): управляйте множеством URL-адресов в /v1/developer/webhook-endpoints с секретами и подписками на события для каждой конечной точки.
• Устаревший вебхук с одним URL: один URL для каждой организации. Управляется через /v1/webhook или в разделе Организация → Общие. Сохранён для обратной совместимости.

События делятся на два класса:

• Блокирующие события ожидают, что ваш сервер ответит конфигурацией, которая определяет ход текущего звонка, — это события входящего звонка (telephony.incoming / web.incoming). Телефонный звонок ожидает до 13 секунд, включая одну повторную попытку, а сессия виджета — 10 секунд. Резервного агента нет: без пригодной конфигурации телефонный звонок завершается, а сессия виджета завершается с ошибкой.
• Неблокирующие события — это уведомления типа «отправил и забыл» с повторными попытками по схеме экспоненциальной задержки — см. семантику доставки.

Каждый запрос содержит HMAC-SHA256-подпись с меткой времени в X-ThunderPhone-Signature-V2, а также устаревшую подпись только для тела X-ThunderPhone-Signature. См. проверку подписи.

Инструменты функций#

Инструмент функции — это HTTP-конечная точка, которую ваш агент может вызвать в ходе разговора. Вы предоставляете ThunderPhone схему функции в стиле OpenAI и URL конечной точки; агент решает, когда её вызвать, а ThunderPhone выполняет подписанный HTTP-запрос со своих серверов и передаёт результат агенту.

Агенты также поддерживают встроенные возможности звонков — перевод звонка, отправку ввода с клавиатуры (DTMF), завершение звонка, ожидание на удержании — которые включаются обычными строками промпта, а не определениями инструментов.

В панели управления: раздел конструктора API-подключения (см. Подключения).

В API: /v1/integrations и спецификация инструментов функций.

Команда и роли#

В каждой организации есть список участников с двумя ролями: Участники создают и управляют агентами; Администраторы также управляют командой и оплатой. Приглашайте по email — срок действия приглашений истекает через 7 дней, и их можно отозвать; меню ⋯ в строке участника позволяет менять роли или удалять участников. Единый вход можно настроить для всей организации — см. SSO.

В панели управления: Организация → Общие. См. Пригласите команду.

В API: /v1/members, /v1/invites.

Оплата#

ThunderPhone работает по предоплате. У каждой организации есть баланс в USD; стоимость звонков списывается с него по поминутному тарифу агента (уровень движка плюс доплаты — конструктор показывает итоговый тариф в реальном времени при изменении настроек, а некоторые дополнительные языки добавляют 3¢/мин). Когда баланс достигает нуля, входящие звонки отклоняются, а исходящие возвращают 402 Payment Required.

Пополняйте баланс вручную или включите автопополнение, указав порог баланса, сумму пополнения и необязательный месячный лимит расходов — чтобы звонок никогда не прерывался на середине фразы.

В панели управления: Организация → Настройки оплаты и История оплат. См. Пополните баланс и включите автопополнение, а также полное справочное руководство по тарифам.

В API: /v1/billing.

Встроенный copilot#

Панель управления включает встроенный copilot — спросите его «как мне X», и он ответит на основе этой документации, предложит пошаговые инструкции, которые выделяют реальные элементы управления, и сможет воспроизвести любой из пошаговых туров. Это самый быстрый способ найти элемент управления, упомянутый на этой странице. См. Спросите встроенный copilot.

Как всё связать#