Getting Started

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

Карта всего на платформе: что делает каждый объект, где он находится в панели управления и какой 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 и готовые к работе за несколько секунд. Они поддерживают только входящие звонки, отвечают коротким голосовым уведомлением, а панель управления ограничивает их количество для организации до 10. Идеально для первого теста, но не для продакшена.
• VoIP-номера — подключаются через вашего собственного провайдера с помощью VoIP-подключения. Twilio и Telnyx подключаются напрямую (для Telnyx доступна пошаговая настройка); SignalWire и Vonage появятся в ближайшее время — пока их можно подключить через ручную настройку 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.

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

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

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

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

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

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

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

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

В API: /v1/publishable-key, /v1/mic-session и документация Widget 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.

Отчёты#

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

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

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

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

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

Оповещения#

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

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

Вебхуки#

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

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

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

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

Каждый запрос содержит подпись HMAC-SHA256 в 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.

Встроенный копилот#

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

Всё вместе#