Class BasePlatformAdapter<TQuery>Abstract

constructor

• new BasePlatformAdapter<TQuery = unknown>(
      platformToken?: string,
      additionalPlatformOptions?: IAdapterOptions,
  ): BasePlatformAdapter<TQuery>

  Конструктор базового адаптера платформы.

  Type Parameters

  • TQuery = unknown

  Parameters

  • OptionalplatformToken: string

    Токен платформы (опционально)

  • OptionaladditionalPlatformOptions: IAdapterOptions

    Дополнительные опции платформы (опционально)

  Returns BasePlatformAdapter<TQuery>

OptionalappContext

isVoice

limit

platformName

OptionalsignatureName

supportedEvents

class MyPlatformAdapter extends BasePlatform {
    supportedEvents: readonly TEventType[] = ['message', 'photo', 'callback'];
    // ...
}
Copy

createApi

• createApi(_controller: BotController): IControllerApi | null

  Создаёт API-фасад платформы для controller.api — унифицированный доступ к исходящим возможностям платформы (sendPhoto, answerCallback и т.д.).

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

  Для кастомных платформ: если платформа умеет исходящие API-вызовы (отправка медиа, ответ на callback-кнопку), переопределите метод и верните свой фасад IControllerApi. Удобно завернуть готовую фабрику и дополнить её, либо собрать фасад с нуля. Для голосовых платформ (ответ формируется телом webhook) переопределять не нужно.

  Parameters

  • _controller: BotController

    Контроллер текущего запроса (не используется базовой реализацией; доступен переопределяющим методам)

  Returns IControllerApi | null

  Фасад либо null, если для платформы он недоступен

  Example

  class MyPlatformAdapter extends BasePlatform {
      createApi(controller: BotController): IControllerApi | null {
          return makeMyApi(controller); // своя фабрика фасада
      }
  }
  Copy

AbstractgetContent

• getContent(
      controller: BotController,
      stateData?: Record<string, unknown> | null,
  ): TContent

  Формирует тело ответа для отправки пользователю.

  Возвращает платформо-специфичный ответ (например, JSON для Алисы). Для платформ, которые отправляют ответ напрямую (например, Telegram через sendMessage), метод может возвращать строку 'ok' или объект.

  Parameters

  • controller: BotController

    контроллер с готовым ответом

  • OptionalstateData: Record<string, unknown> | null

    данные для локального хранилища

  Returns TContent

  ответ в формате, понятном платформе

getLocalStorage

• getLocalStorage<TStorageResult = unknown>(
      _controller: BotController,
  ): TStorageResult | Promise<TStorageResult>

  Получает данные из локального хранилища платформы.

  Type Parameters

  • TStorageResult = unknown

  Parameters

  • _controller: BotController

    контроллер приложения

  Returns TStorageResult | Promise<TStorageResult>

  данные, сохранённые ранее

getProcessingTime

• getProcessingTime(controller: BotController): number

  Получает время выполнения запроса в миллисекундах

  Parameters

  • controller: BotController

  Returns number

  Время выполнения запроса

getQueryExample

• getQueryExample(
      query: string,
      userId: string,
      count: number,
      state: string | Record<string, unknown>,
  ): Record<string, unknown>

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

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

  Parameters

  • query: string

    Запрос пользователя

  • userId: string

    Идентификатор пользователя

  • count: number

    Порядковый номер запроса

  • state: string | Record<string, unknown>

    Данные из локального хранилища

  Returns Record<string, unknown>

  Пример входящего запроса платформы (Record)

  Example

  // Пример переопределения для кастомной платформы
  getQueryExample(query, userId, count, state) {
      return { text: query, userId, messageId: count, state };
  }
  Copy

getRatingContext

• getRatingContext(controller: BotController): TContent

  Формирует ответ на запрос оценки (по умолчанию — обычный ответ getContent; спец-формат — например, SmartApp).

  Parameters

  • controller: BotController

    контроллер приложения

  Returns TContent

init

• init(appContext: AppContext<IDatabaseInfo, TQuery>): void

  Инициализация адаптера. Определять не обязательно. Стоит указывать в случаях, когда нужно выполнить доп логику, например указать токены или писать какую-то статистику по использованию.

  Parameters

  • appContext: AppContext<IDatabaseInfo, TQuery>

    Контекст приложения

  Returns void

isCorrectQuery

• isCorrectQuery(query: TQuery, headers?: Record<string, unknown>): boolean

  Проверяет полученный запрос от платформы на корректность. Из коробки проверка идет по sha256-hmac и включается только если одновременно заданы:

  • appConfig.tokens[<platformName>].token — секретный ключ
  • this.signatureName — имя http-заголовка с подписью

  Если хотя бы один из этих параметров не задан, метод вернёт true без проверки — это opt-in механизм.

  ⚠️ Важно: не все платформы используют HMAC-SHA256 от тела. Переопределите этот метод в адаптере платформы, если её формат подписи отличается:

  • Telegram — переопределён (использует plain x-telegram-bot-api-secret-token).
  • Viber — умолчание корректно (Viber шлёт x-viber-content-signature как HMAC-SHA256(auth_token, body)).
  • VK — переопределён: сверяет поле secret из тела запроса с secret_key из конфигурации (plain-сравнение через timingSafeEqual, без HMAC).
  • Max — переопределён: сверяет заголовок x-max-bot-api-secret со значением webhook-secret (options.secret / tokens.max_app.webhookSecret).
  • Для платформ без подписи (Alisa, Marusia, SmartApp) проверка пропускается из-за отсутствия signatureName.

  Parameters

  • query: TQuery

    Объект запроса от платформы

  • Optionalheaders: Record<string, unknown>

    HTTP-заголовки запроса

  Returns boolean

  true — запрос валиден / проверка не включена, false — подпись не сошлась или отсутствует.

isLocalStorage

• isLocalStorage(_controller: BotController): boolean

  Указывает, поддерживает ли платформа локальное хранилище.

  Parameters

  • _controller: BotController

    контроллер приложения

  Returns boolean

  true, если локальное хранилище доступно

AbstractisPlatformOnQuery

• isPlatformOnQuery(query: TQuery, headers?: Record<string, unknown>): boolean

  Возвращает признак того, соответствует ли запрос текущей платформе или нет

  Parameters

  • query: TQuery

    Запрос, который пришел в приложение

  • Optionalheaders: Record<string, unknown>

    Заголовок с которым был отправлен запрос

  Returns boolean

  true, если запрос относится к этой платформе, иначе false

  Example: Пример кастомной платформы (не поведение встроенного TelegramAdapter,

  который определяет запрос по полю update_id в теле)

  isPlatformOnQuery(query, headers) {
    return headers?.['x-telegram-bot-api-secret-token'] === this._token;
  }
  Copy

  Example: Алиса

  isPlatformOnQuery(query) {
    return !!(query.request && query.version && query.session);
  }
  Copy

isSignatureCheckEnabled

• isSignatureCheckEnabled(): boolean

  Проверка подписи включена, когда выполнены оба условия базовой HMAC-схемы: задан секрет платформы и имя заголовка подписи. Платформы, переопределившие isCorrectQuery (Telegram, VK, MAX), переопределяют и этот метод — источник секрета у них другой (webhookSecret / secret_key).

  Используется ядром при старте для предупреждения о вебхуке без защиты.

  Returns boolean

send

• send(
      userId: string | number,
      controllerOrText: string | BotController<IUserData, IPlatformData>,
  ): boolean | TContent

  Отправка текста пользователю Этот метод используется для активных рассылок — когда голосовой навык или чат-бот инициирует диалог первым (например, уведомление). В методе реализована механика преобразования текстового значения controllerOrText в контроллер, а также базовый механизм для отправки ответа.

  Переопределять данный метод не рекомендуется. Переопределить стоит только в том случае, если по каким-то технических условиям текущая реализация метода вам не подходит.

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

  Parameters

  • userId: string | number

    Ид пользователя, которому нужно отправить сообщение

  • controllerOrText: string | BotController<IUserData, IPlatformData>

    Контроллер приложения или текст. Если необходимо отправить просто текст, можно передать строку, в случае, если необходимо передать картинку звук и тд, то необходимо корректно заполнить контроллер.

  Returns boolean | TContent

  Результат getContent() — ответ в формате платформы (TContent), либо boolean для платформ без рассылки

  Example

  // Отправка простого текста
  adapter.send('user123', 'Привет!');
  
  // Отправка через контроллер (текст + кнопки/карточки)
  const controller = new BaseBotController(appContext);
  controller.text = 'Уведомление';
  adapter.send('user123', controller);
  Copy

setLocalStorage

• setLocalStorage<TStorageData>(
      _data: TStorageData,
      _controller: BotController,
  ): void | Promise<void>

  Сохраняет данные в локальное хранилище платформы.

  Type Parameters

  • TStorageData

  Parameters

  • _data: TStorageData

    данные для сохранения

  • _controller: BotController

    контроллер приложения

  Returns void | Promise<void>

AbstractsetQueryData

• setQueryData(
      query: TQuery,
      controller: BotController,
  ): boolean | Promise<boolean>

  Обрабатывает входящий запрос и заполняет контроллер данными.

  Обязательно установите:

  • controller.userCommand и controller.originalUserCommand — текст сообщения пользователя
  • controller.userId — уникальный ID пользователя
  • controller.appType = this.platformName

  Опционально:

  • controller.userToken — если платформа присылает токен авторизации
  • controller.userMeta — если платформа присылает метаданные
  • controller.state — если платформа поддерживает локальное хранилище
  • controller.nlu — если платформа присылает NLU/интенты (через controller.nlu.setNlu(...))

  Parameters

  • query: TQuery

    Запрос от платформы

  • controller: BotController

    Контроллер приложения

  Returns boolean | Promise<boolean>

  false, если запрос повреждён или не может быть обработан; иначе true

soundProcessing

• soundProcessing(_controller: BotController): void | Promise<void>

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

  Parameters

  • _controller: BotController

    Контроллер бота

  Returns void | Promise<void>

updateTimeStart

• updateTimeStart(controller: BotController): void

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

  Parameters

  • controller: BotController

  Returns void

StaticisVoice

• isVoice(): boolean

  Метод-флаг: указывает, что платформа голосовая (например, Алиса, Маруся).

  Returns boolean