Class BaseBotController<TUserData, TPlatformState>

appContext

appeal

this.appeal = 'official'; // официальное обращение
Copy

appType

emotion

this.emotion = 'good';
Copy

eventType

// В action() или обработчике команды:
if (this.eventType === 'photo') {
  this.text = 'Отличное фото!';
}
Copy

isAuth

this.isAuth = true; // требуется авторизация
Copy

isEnd

this.isEnd = true; // завершить диалог
Copy

isScreen

this.isScreen = true; // экран доступен
Copy

isSendRating

this.isSendRating = true; // запросить оценку
Copy

messageId

this.messageId = 12345;
Copy

oldIntentName

// Пример: Многошаговая регистрация
class RegistrationBot extends BotController {
  public action(intentName: string | null): void {
    // Определяем на каком шаге находимся
    const previousStep = this.oldIntentName;

    if (previousStep === 'enter_name') {
      // Пользователь только что ввел имя, спрашиваем email
      this.userData.name = this.userCommand;
      this.text = 'Отлично! Теперь введите ваш email:';
      this.thisIntentName = 'enter_email'; // Сохранится для следующего шага
    } else if (previousStep === 'enter_email') {
      // Пользователь ввел email, завершаем регистрацию
      this.userData.email = this.userCommand;
      this.text = 'Регистрация завершена!';
    }
  }
}

// Пример: Кнопка "Назад"
if (intentName === 'back') {
  // Возвращаемся к предыдущему шагу
  switch(this.oldIntentName) {
    case 'product_list':
      this.text = 'Выберите категорию:';
      break;
    case 'category_list':
      this.text = 'Добро пожаловать!';
      break;
  }
}
Copy

originalUserCommand

this.originalUserCommand = 'Привет, мир!';
Copy

payload

this.payload = {
  source: 'mobile',
  version: '1.0'
};
Copy

platformOptions

requestObject

this.requestObject = {
  command: 'start',
  payload: { source: 'mobile' }
};
Copy

skipAutoReply

this.skipAutoReply = true; // запросы уже отправлены
Copy

state

this.state = {
  lastIntent: 'greeting',
  step: 1
};
Copy

text

this.text = 'Привет! Чем могу помочь?';
Copy

thisIntentName

this.thisIntentName = 'help';
Copy

tts

this.tts = 'Привет! Я голосовой ассистент.';
Copy

userCommand

this.userCommand = 'привет мир';
Copy

userData

// Тип контроллера с дженериком:
// class MyController extends BotController<MyUserData> { ... }
this.userData.name = 'John';
this.userData.score += 1;
this.userData.preferences = { language: 'ru' };
Copy

userEvents

this.userEvents = {
  auth: { status: true },
  rating: { status: true, value: 5 }
};
Copy

userId

this.userId = 'user_123';    // Telegram (string)
this.userId = 123456789;     // VK (number)
this.userId = null;          // не удалось получить информацию
Copy

userMeta

this.userMeta = {
  timezone: 'Europe/Moscow',
  locale: 'ru-RU'
};
Copy

userToken

this.userToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
Copy

api

• get api(): IControllerApi | null

  API активной платформы: отправка медиа и ответов на callback-кнопки без ручного конструирования платформенных Request-классов.

  Доступно на чат-платформах (Telegram, VK, MAX, Viber с оговорками); на голосовых (Алиса, Маруся, SmartApp) — null: их ответ формируется телом webhook, используйте card/sound.

  Returns IControllerApi | null

  Example

  bot.addEvent('photo', async (ctx) => {
      await ctx.api?.sendPhoto('answer.jpg', { caption: 'Вот ваш отчёт' });
      ctx.skipAutoReply = true; // ответ уже отправлен вручную
  });
  Copy

buttons

• get buttons(): Buttons

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

  Returns Buttons

  Remarks

  🎯 ТИПИЧНОЕ ИСПОЛЬЗОВАНИЕ:

  • Навигация по меню
  • Быстрые ответы (Да/Нет)
  • Выбор из вариантов
  • Быстрое действие/команда

  See

  Buttons

  Example

  this.buttons
    .addBtn('Помощь')
    .addBtn('Выход');
  Copy

card

• get card(): Card

  Компонент для отображения карточек пользователю. Позволяет создавать визуальные элементы с изображениями и текстом. Также при указании нескольких изображений, они автоматически преобразуются в карточку.

  Returns Card

  Remarks

  🎯 КОГДА ИСПОЛЬЗОВАТЬ:

  • Каталог товаров/услуг
  • Галерея изображений
  • Карточки статей/новостей
  • Навигация

  See

  Card

  Example

  // КАТАЛОГ ТОВАРОВ (интернет-магазин):
  this.text = 'Популярные товары:';
  this.card
    .addImage(
      'http://localhost/iphone.jpg',
      'iPhone 15 Pro',
      '99 990 ₽\nЭкран 6.1", процессор A17 Pro'
    )
    .addButton('Купить')
  
    .addImage(
      'http://localhost/macbook.jpg',
      'MacBook Air M2',
      '124 990 ₽\n13.6", 8ГБ RAM, 256ГБ SSD'
    )
    .addButton('Купить');
  
  // ГАЛЕРЕЯ ФОТОГРАФИЙ:
  this.text = 'Наши работы:';
  this.card
    .addImage('photo1.jpg', 'Свадьба', 'Иван и Мария')
    .addImage('photo2.jpg', 'Выпускной', 'Школа №123')
    .addImage('photo3.jpg', 'Корпоратив', 'Компания "Рога и копыта"');
  
  // КАРТОЧКИ НОВОСТЕЙ:
  this.card
    .addImage(
      'news1.jpg',
      'Новое обновление',
      'Добавлена оплата картой и доставка',
      {
          title: 'Перейти',
          url: 'http://localhost/news/1'
      }
    )
  Copy

match

• get match(): RegExpExecArray | null

  Результат совпадения команды с регулярным выражением.

  Заполняется лениво при первом обращении: фреймворк запоминает регулярку сработавшей команды (RegExp-слот, isPattern-паттерн или группу регулярок) и прогоняет её по тексту только если обработчик реально читает match. Содержит RegExpExecArray совпавшей регулярки — группы доступны как this.match[1], this.match.groups. Для строковых команд и событий — null.

  Returns RegExpExecArray | null

  Example

  bot.addCommand('order', [/(?:заказ|купить)\s+(\d+)/], (_, ctx) => {
    ctx.text = `Оформляю заказ №${ctx.match?.[1]}`;
  });
  Copy

nlu

• get nlu(): Nlu

  Обработанный NLU (Natural Language Understanding). Содержит результаты обработки естественного языка, как правило, данные заполняются самой платформой.

  Returns Nlu

  See

  Nlu

sound

• get sound(): Sound

  Компонент для работы со звуками. Позволяет добавлять звуковые эффекты и музыку. Используется вместе с tts.

  Returns Sound

  See

  Sound

clearStoreData

• clearStoreData(): void

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

  Returns void

  Example

  // Вызывается фреймворком автоматически перед следующим запросом;
  // вручную — чтобы переиспользовать контроллер в тестах:
  controller.clearStoreData();
  console.log(controller.text); // ''
  Copy

isButtonsInit

• isButtonsInit(): boolean

  Флаг возвращающий информацию о том, были ли инициализированы кнопки или нет

  Returns boolean

  true если кнопки были инициализированы

isCardInit

• isCardInit(): boolean

  Флаг возвращающий информацию о том, были ли инициализированы карточки или нет

  Returns boolean

  true если карточки были инициализированы

isNluInit

• isNluInit(): boolean

  Метод: возвращает true, только если объект Nlu уже создан (было обращение к геттеру nlu). Вызов setThisUser сам по себе объекта не создаёт: при неинициализированном Nlu данные буферизуются в #thisUserBuffer и применятся при первом же обращении к геттеру.

  Returns boolean

  true если объект NLU был инициализирован

isSoundInit

• isSoundInit(): boolean

  Флаг возвращающий информацию о том, были ли инициализированы звуки или нет

  Returns boolean

  true если звуки были инициализированы

run

• run(): void | Promise<void>

  Основной метод обработки запроса, вызываемый автоматически фреймворком.

  Returns void | Promise<void>

  Может быть асинхронным

  Remarks

  Как это работает:

  1. Пользователь отправляет сообщение → платформа → Bot.run()
  2. run() определяет тип запроса (команда/интент/шаг)
  3. Вызывается ваш метод action() с результатом
  4. Вы заполняете поля ответа (text, buttons, card)
  5. Bot отправляет ответ пользователю

  Не вызывайте run() вручную и не переопределяйте его — для своей логики переопределяйте только action().

  Порядок обработки внутри run():

  run()
    ├── Шаг 0: Вызывает событийные обработчики (bot.addEvent) по controller.eventType
    │     → Обработчик не вернул false → обработка завершена (action(eventType))
    ├── Шаг 1: Проверяет есть ли активный шаг
    │     → Если есть → вызывает action(stepName, false, true)
    ├── Шаг 2: Ищет команду
    │     → Если нашел → вызывает action(commandName, true, false)
    ├── Шаг 3: Ищет интент (включая welcome/help)
    │     → Если нашел → вызывает action(intentName, false, false)
    │     → welcome-интент: messageId === 0 (начало диалога) и fallback-команда
    │       не зарегистрирована
    └── Шаг 4: Если интент не найден → fallback-команда ("*"), если зарегистрирована.
          Fallback проверяется раньше welcome и имеет над ним приоритет —
          welcome при messageId === 0 срабатывает, только если fallback не зарегистрирован
  Copy

  Example

  // ВАШ КОД (контроллер):
  class MyController extends BotController {
    public action(intentName: string | null): void {
      // Ваша логика здесь
      this.text = "Ответ пользователю";
    }
  }
  
  // КОД ФРЕЙМВОРКА (не ваш):
  // Когда приходит запрос от пользователя:
  const controller = new MyController();
  {...}; // Наполняет контроллер данными. Как правило, этим занимается адаптер платформы
  await controller.run(); // Автоматически вызывает ваш action()
  const response = ...; // Адаптер формирует ответ в зависимости от состояния контроллера
  Copy

setAppContext

• setAppContext(appContext: AppContext): this

  Устанавливает контекст приложения (обновляет контекст в уже созданных компонентах buttons и card).

  Parameters

  • appContext: AppContext

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

  Returns this

  Текущий экземпляр для цепочки вызовов

setThisUser

• setThisUser(thisUser: INluThisUser): this

  Записывает данные отправителя сообщения (username/имя/фамилия) в NLU.

  Используется адаптерами чат-платформ (через хелпер setThisUserToNlu из pUtils). Значение сначала держится в приватном буфере: если логика приложения ни разу не обратится к nlu, объект Nlu и его кэш не создаются вовсе. При первом обращении буфер переносится в Nlu (nlu.getUserName() возвращает переданные данные).

  Parameters

  • thisUser: INluThisUser

    Данные отправителя; пустые поля интерпретируются как отсутствие данных

  Returns this

  Текущий экземпляр для цепочки вызовов

  Example

  // Внутри адаптера платформы:
  controller.setThisUser({ username: 'ivan', first_name: 'Иван', last_name: null });
  // ...позже в бизнес-логике:
  const name = this.nlu.getUserName()?.first_name;
  Copy