Конструктор базового адаптера платформы.
OptionalplatformToken: string
Токен платформы (опционально)
OptionaladditionalPlatformOptions: IAdapterOptions
Дополнительные опции платформы (опционально)
Protected_getResponseФормирует ответ для пользователя. Собирает текст, TTS, карточки и кнопки в единый объект ответа
Контроллер приложения
Объект ответа для Алисы
Protected_initTTSProtected
Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты
Контроллер приложения
Protected_timeLimitLogПри превышении допустимого времени обработки запроса логирует информацию.
Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp);
адаптеры чат-платформ его не вызывают.
>= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.>= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется
в controller.platformOptions.error (не в лог).Пороги вынесены в protected поля — при необходимости переопределите в потомке.
ProtectedcheckSendResultОтмечает в контроллере, что платформа отклонила отправку: тогда send вернёт false.
Вызывается в getContent с результатом запроса отправки; тело ответа на вебхук не меняется.
Контроллер ответа
Результат запроса к API (null/false — ошибка)
Учитывает дополнительные вызовы API платформы в лимите отправки (sendLimit), не ожидая очереди.
Один send — не всегда один вызов API: например, отправка карточки VK с
незакэшированной картинкой — это ещё и загрузка (photos.getMessagesUploadServer,
photos.saveMessagesPhoto), а методами платформы делится общий лимит запросов/с.
Вызывайте перед вспомогательными API-вызовами своей отправки (из getContent
адаптера или обработчика карточек) — очередь рассылки разредится, и платформа
не ответит ошибкой «Too many requests».
Сколько дополнительных вызовов API сейчас будет сделано
Создаёт API-фасад платформы для controller.api — унифицированный доступ
к исходящим возможностям платформы (sendPhoto, answerCallback и т.д.).
Базовая реализация возвращает null: фасад считается недоступным. Ядро
подключает фасад к контроллеру только у адаптеров, переопределивших этот
метод, — поэтому добавить фасад своей платформе можно без правок ядра.
Для кастомных платформ: если платформа умеет исходящие API-вызовы
(отправка медиа, ответ на callback-кнопку), переопределите метод и
верните свой фасад IControllerApi. Удобно завернуть готовую фабрику
и дополнить её, либо собрать фасад с нуля. Для голосовых платформ
(ответ формируется телом webhook) переопределять не нужно.
Контроллер текущего запроса (не используется базовой реализацией; доступен переопределяющим методам)
Фасад либо null, если для платформы он недоступен
Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.
Основной класс приложения
Формирует итоговый webhook-ответ Алисы: версию протокола, response, директивы авторизации и выбранное state-хранилище (с проверкой лимита байт).
Контроллер приложения
OptionalstateData: Record<string, unknown> | null
Состояние для сохранения (user/application/session)
Готовый ответ для webhook Алисы
Возвращает состояние из request.state (user/application/session).
Тип состояния определяется настройками навыка в Яндекс.Диалогах.
Контроллер приложения
Получает время выполнения запроса в миллисекундах
Время выполнения запроса
Формирует пример webhook-запроса Алисы для локального тестирования (BotTest).
Текст команды пользователя
Идентификатор пользователя
Номер сообщения в сессии (0 — новая сессия)
Состояние (session/user/application) для подстановки в запрос
Заготовка запроса в формате webhook Алисы
Формирует ответ на запрос оценки (по умолчанию — обычный ответ getContent; спец-формат — например, SmartApp).
контроллер приложения
Срок ответа Алисе: после него навык считается не ответившим.
MAX_TIME_REQUEST, мс
Инициализирует адаптер: вызывает базовую инициализацию и пробрасывает переданный в конструкторе токен в конфигурацию платформы.
Контекст приложения (конфиги, токены, логгер)
Проверяет запрос при заданной опции alisa_skill_id: session.skill_id
должен совпадать с ожидаемым. Отсекает чужой трафик на ваш URL (другой
навык, чужой сценарий, опечатка роутинга). Это НЕ подпись: Алиса не
подписывает вебхуки, весь payload контролирует отправитель, поэтому
от целевой подделки (атакующий знает и адрес, и skill_id) опция не
защищает — для этого нужна сетевая изоляция.
Входящий webhook-запрос (сырое тело строкой или объект)
Optional_headers: Record<string, unknown>
Заголовки HTTP-запроса (не используются)
OptionalparsedQuery: unknown
Тело, разобранное из JSON фреймворком
true, если проверка не включена или skill_id совпал
Проверяет, присутствует ли сохранённое состояние в запросе.
контроллер с бизнес-логикой приложения
true, если состояние есть (не null)
Проверяет, что входящий webhook-запрос принадлежит Алисе.
Отличает Алису от Маруси по meta.client_id и виду session.application.application_id.
Входящий webhook-запрос
Optional_headers: Record<string, unknown>
Заголовки HTTP-запроса (не используются: у Алисы нет подписи webhook)
true, если запрос относится к платформе Алиса
Проверка подписи включена, когда выполнены оба условия базовой HMAC-схемы:
задан секрет платформы и имя заголовка подписи. Платформы, переопределившие
isCorrectQuery (Telegram, VK, MAX), переопределяют и этот метод —
источник секрета у них другой (webhookSecret / secret_key).
Используется ядром при старте для предупреждения о вебхуке без защиты.
Умеет ли платформа подписывать вебхук. По умолчанию — да, если задан
signatureName (подпись в заголовке) или переопределён isSignatureCheckEnabled
(подпись в теле, как у VK). Ядро по этому признаку решает, предупреждать ли
при старте о вебхуке без проверки подписи.
true, если у платформы есть механизм подписи вебхука
Алиса не поддерживает push-сообщения, поэтому всегда возвращает false.
Сохраняет данные в локальное хранилище платформы.
данные для сохранения
контроллер приложения
Разбирает запрос Алисы и наполняет контроллер данными: команда, NLU, идентификатор пользователя, состояние, метаданные, health-check ping.
Входящий webhook-запрос Алисы
Контроллер приложения
true, если запрос успешно разобран
Использует кастомную обработку TTS через импортируемую функцию
soundProcessing из ./Sound для вставки звуковых эффектов
в соответствии с требованиями Алисы.
Контроллер приложения
Публичная точка входа для сброса времени начала обработки запроса. Вызывайте перед началом бизнес-логики, чтобы метрики (см. getProcessingTime) считались отсюда.
StaticisVoiceМетод-флаг: указывает, что платформа голосовая (например, Алиса, Маруся).
Protected_knownPlatformOptionsИзвестные опции адаптера. alisa_skill_id — ожидаемый session.skill_id
вебхука: при заданной опции запросы с другим skill_id отклоняются (см.
isCorrectQuery). Остальные ключи дают предупреждение (см. BasePlatform).
Protected Optional_platformOptionsОпции из второго аргумента конструктора (new TelegramAdapter(token, { telegram_parse_mode })).
Protected Optional_tokenТокен из конструктора адаптера (new MyAdapter(token)). Во время работы берите токен из
appContext.appConfig.tokens: туда он попадает при bot.use() и может быть перезаписан из .env.
OptionalappContextКонтекст приложения
Голосовая ли платформа (TTS-ответ в теле HTTP). Чат-платформы переопределяют на false.
Лимит запросов/сек для входящего rateLimiter; null — не ограничивать. Переопределяется адаптером платформы.
ProtectedMAX_TIME_REQUESTМаксимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)
Идентификатор платформы Яндекс.Алиса.
Сколько сообщений в секунду отправляет send (рассылки, bot.broadcast); null — без
ограничения. Ответы на входящие запросы не ограничиваются. Переопределяется адаптером по
лимиту платформы и опцией адаптера send_rate_limit.
OptionalsignatureNameИмя поля в заголовке запроса, по которому можно проверить корректность полученного запроса от платформы.
Универсальные события Алисы (для валидации addEvent): текст и account_linking.
ProtectedWARNING_TIME_REQUESTПорог предупреждения в миллисекундах: при его превышении в лог записывается warning
Адаптер, обеспечивающий полную поддержку платформы Яндекс.Диалоги (Алиса). Позволяет разрабатывать навыки для Алисы на TypeScript с использованием всего функционала платформы: от обработки голосовых запросов до работы с карточками и кнопками.
Подключение адаптера не требует изменения существующей бизнес-логики: после интеграции все команды и обработчики, написанные для umbot, автоматически становятся доступны для Алисы. Единый интерфейс позволяет одновременно использовать одну бизнес-логику для нескольких платформ (Telegram, VK, Алиса и др.) без дублирования кода.
Этот адаптер автоматически обрабатывает входящие вебхуки от Алисы, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Telegram или VK).
Поддерживает:
ping→pong);Подключается как любой другой адаптер:
bot.use(new AlisaAdapter(token)). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.Example
See