Конструктор базового адаптера платформы.
OptionalplatformToken: string
Токен платформы (опционально)
OptionaladditionalPlatformOptions: IAdapterOptions
Дополнительные опции платформы (опционально)
Protected_getUserDataProtected
Получает данные пользователя из хранилища
Данные пользователя либо пустой объект при ошибке (ошибка логируется)
Protected_initTTSProtected
Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты
Контроллер приложения
Protected_setUserDataСохраняет данные пользователя в хранилище
Данные для сохранения
Контроллер приложения
Результат HTTP-запроса к внешнему хранилищу
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-ответ SmartApp (ANSWER_TO_USER): текст, TTS/SSML, карточки, кнопки и команду закрытия приложения. Синхронный метод — возвращает готовый объект без промиса.
Контроллер приложения
Готовый ответ для webhook SmartApp
Получает данные из локального хранилища.
Контроллер приложения
Данные пользователя либо пустой объект {}; ошибки логируются через logError
Получает время выполнения запроса в миллисекундах
Время выполнения запроса
Формирует пример webhook-запроса SmartApp (MESSAGE_TO_SKILL) для локального тестирования (BotTest).
Текст команды пользователя
Идентификатор пользователя (uuid.userId)
Номер сообщения (messageId; 0 — новая сессия)
Заготовка запроса в формате webhook SmartApp
Формирует ответ с оценкой навыка
Контроллер приложения
Объект ответа для вебхука
Срок ответа SmartApp: после него смартап считается не ответившим.
MAX_TIME_REQUEST, мс
Инициализация адаптера. Определять не обязательно. Стоит указывать в случаях, когда нужно выполнить доп логику, например указать токены или писать какую-то статистику по использованию.
Контекст приложения
Проверяет запрос при заданной опции smartapp_application_id:
payload.app_info.applicationId должен совпадать с ожидаемым. Отсекает
чужой трафик на ваш URL (другой смартап, чужой сценарий). Это НЕ подпись:
SmartApp не подписывает вебхуки, весь payload контролирует отправитель,
поэтому от целевой подделки (атакующий знает и адрес, и applicationId)
опция не защищает — для этого нужна сетевая изоляция.
Входящий webhook-запрос (сырое тело строкой или объект)
Optional_headers: Record<string, unknown>
Заголовки HTTP-запроса (не используются)
OptionalparsedQuery: unknown
Тело, разобранное из JSON фреймворком
true, если проверка не включена или applicationId совпал
SmartApp всегда имеет внешнее хранилище, поэтому возвращает true.
Проверяет, что входящий webhook-запрос принадлежит SmartApp.
Опознаёт запрос по заголовкам x-sber-smartapp-webhook-token/x-sber-token
либо по связке полей messageName + uuid + payload.character + payload.app_info.
Входящий webhook-запрос
Optionalheaders: Record<string, unknown>
Заголовки HTTP-запроса
true, если запрос относится к платформе SmartApp
Проверка подписи включена, когда выполнены оба условия базовой HMAC-схемы:
задан секрет платформы и имя заголовка подписи. Платформы, переопределившие
isCorrectQuery (Telegram, VK, MAX), переопределяют и этот метод —
источник секрета у них другой (webhookSecret / secret_key).
Используется ядром при старте для предупреждения о вебхуке без защиты.
Умеет ли платформа подписывать вебхук. По умолчанию — да, если задан
signatureName (подпись в заголовке) или переопределён isSignatureCheckEnabled
(подпись в теле, как у VK). Ядро по этому признаку решает, предупреждать ли
при старте о вебхуке без проверки подписи.
true, если у платформы есть механизм подписи вебхука
SmartApp не поддерживает push-сообщения, поэтому всегда возвращает false.
Сохраняет данные пользователя во внешнее хранилище SmartApp.
Данные для сохранения
Контроллер приложения
Разбирает запрос SmartApp и наполняет контроллер данными: команда, NLU, персонаж, сессия, метаданные и данные экрана устройства.
Входящий webhook-запрос SmartApp
Контроллер приложения
true, если запрос успешно разобран
Дополнительная обработка для звуков. В данном методе стоит реализовать логику, с помощью которой будут наложены дополнительные эффекты для озвучивания текста пользователю
Контроллер бота
Публичная точка входа для сброса времени начала обработки запроса. Вызывайте перед началом бизнес-логики, чтобы метрики (см. getProcessingTime) считались отсюда.
StaticisVoiceМетод-флаг: указывает, что платформа голосовая (например, Алиса, Маруся).
Protected_knownPlatformOptionsИзвестные опции адаптера. smartapp_application_id — ожидаемый
payload.app_info.applicationId вебхука: при заданной опции запросы с другим
идентификатором приложения отклоняются (см. 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Максимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)
Идентификатор платформы Сбер SmartApp.
Сколько сообщений в секунду отправляет send (рассылки, bot.broadcast); null — без
ограничения. Ответы на входящие запросы не ограничиваются. Переопределяется адаптером по
лимиту платформы и опцией адаптера send_rate_limit.
OptionalsignatureNameИмя поля в заголовке запроса, по которому можно проверить корректность полученного запроса от платформы.
Универсальные события SmartApp (для валидации addEvent).
ProtectedWARNING_TIME_REQUESTПорог предупреждения в миллисекундах: при его превышении в лог записывается warning
Адаптер, обеспечивающий полную поддержку Сбер SmartApp (голосовой ассистент Салют). Позволяет разрабатывать навыки для SmartApp на TypeScript с использованием всего функционала платформы: от обработки голосовых запросов до работы с карточками и кнопками.
Этот адаптер автоматически обрабатывает входящие вебхуки от SmartApp, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Telegram или VK).
Поддерживает:
=== Локальное хранилище === Адаптер использует внешнее SmartApp Code API для хранения данных пользователя. По умолчанию URL хранилища:
https://smartapp-code.sberdevices.ru/tools/api/data. URL можно переопределить через конфиг:Подключается как любой другой адаптер:
bot.use(new SmartAppAdapter()). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.Токен конструктора адаптеру не требуется: аутентификация навыка происходит через экосистему Сбера, а данные хранилища читаются из
appConfig.tokens.smart_app(см. блок про локальное хранилище выше).Example
See