umbot
    Preparing search index...

    Class MaxAdapter

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

    Подключение адаптера не требует изменения существующей бизнес-логики: после интеграции все команды и обработчики, написанные для umbot, автоматически становятся доступны для MAX. Единый интерфейс позволяет одновременно использовать одну бизнес-логику для нескольких платформ (MAX, VK, Алиса и др.) без дублирования кода.

    Этот адаптер автоматически обрабатывает входящие вебхуки от мессенджера MAX, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Алисы или Маруси).

    Поддерживает:

    • текстовые запросы;
    • карточки, кнопки;

    Подключается как любой другой адаптер: bot.use(new MaxAdapter(token)). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.

    // Простейший бот для MAX, который отвечает на приветствие
    import { Bot } from 'umbot';
    import { MaxAdapter } from 'umbot/plugins';

    const bot = new Bot()
        .use(new MaxAdapter('YOUR_MAX_TOKEN'))
        .addCommand('start', ['привет'], (_text, ctx) => {
            ctx.text = 'Привет! Я твой первый бот для MAX';
        });

    bot.start('localhost', 3000);
    • Bot
    • BotController
    • BasePlatform

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    _initTTS _timeLimitLog createApi destroy getContent getDeliveryId getLocalStorage getProcessingTime getQueryExample getRatingContext getResponseTimeout getUpdates init isCorrectQuery isLocalStorage isPlatformOnQuery isSignatureCheckEnabled isSignatureSupported send setLocalStorage setQueryData soundProcessing updateTimeStart isVoice

    Properties

    _platformOptions? _token? appContext? isVoice limit MAX_TIME_REQUEST platformName signatureName? supportedEvents WARNING_TIME_REQUEST

    Constructors

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

      Parameters

      • OptionalplatformToken: string

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

      • OptionaladditionalPlatformOptions: IAdapterOptions

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

      Returns MaxAdapter

    Methods

    Protected_initTTS

    • _initTTS(controller: BotController): void | Promise<void>
      Protected

      Инициализирует TTS (Text-to-Speech) в контроллере. Обрабатывает звуки и стандартные звуковые эффекты

      Parameters

      • controller: BotController

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

      Returns void | Promise<void>

    Protected_timeLimitLog

    • _timeLimitLog(controller: BotController): void

      При превышении допустимого времени обработки запроса логирует информацию. Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp); адаптеры чат-платформ его не вызывают.

      • >= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.
      • >= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется в controller.platformOptions.error (не в лог).

      Пороги вынесены в protected поля — при необходимости переопределите в потомке.

      Parameters

      Returns void

    • API-фасад MAX для controller.api (медиа через POST /uploads, ответ на callback). Подключается ядром через контракт IPlatformAdapter.

      Parameters

      • controller: BotController

        Контроллер текущего запроса

      Returns IControllerApi | null

    • Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.

      Parameters

      • _bot: Bot

        Основной класс приложения

      Returns void | Promise<void>

    • Формирует и отправляет ответ MAX: текст, клавиатуру, карточки и звуки (с учётом лимитов MAX на частоту сообщений в диалоге). Нажатие callback-кнопки подтверждается POST /answers, а ответ уходит новым сообщением; с опцией max_callback_edit_message: true ответ заменяет сообщение с кнопкой.

      Parameters

      • controller: BotController

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

      Returns string | Promise<string>

      Тело ответа для webhook ('ok')

    • ID доставки для дедупликации повторов вебхука. Отдельного ID у обновления MAX нет, поэтому ключ собирается из типа, времени и объекта события: одно сообщение (mid) приходит и как message_created, и как message_edited.

      Parameters

      Returns string | null

      Ключ доставки или null, если в обновлении нет времени

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

      Parameters

      Returns number

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

    • Формирует пример webhook-запроса MAX (update_type='message_created') для локального тестирования (BotTest).

      Parameters

      • query: string

        Текст команды пользователя

      • userId: string

        Идентификатор пользователя (sender.user_id)

      • count: number

        Номер сообщения (seq)

      Returns Record<string, unknown>

      Заготовка запроса в формате webhook MAX

    • Сколько платформа ждёт ответа на запрос, мс. По умолчанию null — срока нет (мессенджеры). Голосовые адаптеры возвращают MAX_TIME_REQUEST: по нему ядро ограничивает ожидание в очереди запросов пользователя.

      Returns number | null

      Срок ответа в мс или null, если срока нет

      class MyVoiceAdapter extends BasePlatform {
          getResponseTimeout(): number | null {
              return this.MAX_TIME_REQUEST;
          }
      }

    • Long polling: запрашивает новые обновления методом GET /updates. MAX держит запрос до 30 секунд, если обновлений нет; marker из ответа передаётся в следующий запрос. MAX рекомендует long polling для разработки и тестов, а в продакшене — вебхук (POST /subscriptions).

      Parameters

      • signal: AbortSignal

        Сигнал остановки polling

      Returns Promise<unknown[] | null>

      Обновления, null — polling невозможен (нет токена или токен неверный)

      bot.use(new MaxAdapter(process.env.MAX_TOKEN));
      await bot.startPolling(); // ядро вызывает getUpdates в цикле

    • Инициализирует адаптер: вызывает базовую инициализацию, переносит токен и webhook-secret (опция secret либо конфигурация) в настройки платформы.

      Parameters

      • appContext: AppContext

        Контекст приложения (конфиги, токены, логгер)

      Returns void

    • Проверяет webhook-secret MAX. MAX передаёт исходное значение секрета в заголовке, а не HMAC от тела.

      Parameters

      • _query: string | IMaxRequestContent

        Тело запроса (не используется: секрет приходит заголовком)

      • Optionalheaders: Record<string, unknown>

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

      Returns boolean

      true, если секрет совпадает (или проверка не настроена), иначе false

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

      Parameters

      • _controller: BotController

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

      Returns boolean

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

    • Проверяет, что входящий webhook-запрос принадлежит MAX. Опознаёт запрос по известным значениям update_type либо по связке update_type + timestamp.

      Parameters

      • query: IMaxRequestContent

        Входящий webhook-запрос

      • Optionalheaders: Record<string, unknown>

        Заголовки HTTP-запроса (не используются при опознании)

      Returns boolean

      true, если запрос относится к платформе MAX

    • MAX проверяет именно webhookSecret (options.secret / tokens.max_app.webhookSecret), а не токен API из конструктора.

      Returns boolean

    • Умеет ли платформа подписывать вебхук. По умолчанию — да, если задан signatureName (подпись в заголовке) или переопределён isSignatureCheckEnabled (подпись в теле, как у VK). Ядро по этому признаку решает, предупреждать ли при старте о вебхуке без проверки подписи.

      Returns boolean

      true, если у платформы есть механизм подписи вебхука

      class MyAdapter extends BasePlatform {
          // Платформа подписывает запрос полем в теле, заголовка нет
          isSignatureSupported(): boolean {
              return true;
          }
      }

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

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

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

      Parameters

      • userId: string | number

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

      • controllerOrText: string | BotController<IUserData, IPlatformData>

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

      Returns boolean | TContent

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

      // Отправка простого текста
      adapter.send('user123', 'Привет!');

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

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

      Type Parameters

      • TStorageData

      Parameters

      • _data: TStorageData

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

      • _controller: BotController

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

      Returns void | Promise<void>

    • Разбирает update MAX (сообщение, callback-кнопка, служебное событие) и наполняет контроллер данными; служебные события помечаются skipAutoReply.

      Parameters

      Returns boolean

      true, если запрос успешно разобран

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

      Parameters

      Returns void | Promise<void>

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

      Parameters

      Returns void

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

      Returns boolean

    Properties

    Protected Optional_platformOptions

    _platformOptions?: IAdapterOptions

    Опции из второго аргумента конструктора (new TelegramAdapter(token, { telegram_parse_mode })).

    Protected Optional_token

    _token?: string

    Токен из конструктора адаптера (new MyAdapter(token)). Во время работы берите токен из appContext.appConfig.tokens: туда он попадает при bot.use() и может быть перезаписан из .env.

    appContext?: AppContext<unknown, string | IMaxRequestContent>

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

    isVoice: boolean = false

    MAX — чат-платформа (не голосовая).

    limit: number = 30

    Лимит запросов/сек для входящего rateLimiter (лимит MAX Bot API).

    MAX_TIME_REQUEST: number = 2900

    Максимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)

    platformName: string = T_MAX_APP

    Идентификатор платформы MAX.

    signatureName?: string

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

    supportedEvents: readonly TEventType[] = ...

    Универсальные события MAX (для валидации addEvent).

    WARNING_TIME_REQUEST: number = 2000

    Порог предупреждения в миллисекундах: при его превышении в лог записывается warning

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    Properties