Class BotController<TUserData, TPlatformState>`Abstract`

Контроллер приложения – главный класс для реализации единой бизнес-логики вашего приложения. Именно в этом классе обрабатывается вся логика вашего приложения, которая потом передается в саму платформу, будь то голосовой навык для Алисы, либо чат-бот для VK.

Этот класс связывает входящие запросы от пользователя с вашей бизнес‑логикой. Вы наследуетесь от BotController, переопределяете метод action и получаете доступ ко всем инструментам: кнопкам, карточкам, состоянию диалога, пользовательским данным, NLU и многому другому.

Адаптеры платформ (например, AlisaAdapter) автоматически наполняют контроллер данными, вызывают внутренний метод {@link run} (он вызывает ваш action()), а затем формируют ответ на основе заполненных вами полей (text, buttons, card и т.д.).

Ключевая особенность: вся логика вашего голосового навыка или бота описывается в одном месте – в методе action(). Фреймворк сам позаботится о маршрутизации: команды, интенты, шаги диалога – всё придёт в action с соответствующим флагом.

Remarks

Основные возможности:

Обработка пользовательских команд и интентов
Управление состоянием диалога
Работа с UI компонентами (кнопки, карточки)
Управление пользовательскими данными

Example

import { BotController } from 'umbot';
// Определение пользовательских данных
interface MyUserData extends IUserData {
  score: number;
  level: number;
  preferences: {
    language: string;
    theme: string;
  };
}

class MyController extends BotController<MyUserData> {
  public action(intentName: string | null): void {
    try {
      // Обработка приветствия
      if (intentName === WELCOME_INTENT_NAME) {
        // Текстовый ответ
        this.text = 'Привет! Чем могу помочь?';

        // Добавление кнопок
        this.buttons
          .addBtn('Помощь')
          .addBtn('Выход');

        // Добавление карточки
        this.card
          .addImage('xxx', 'Добро пожаловать!', 'Выберите действие:')
          .addButton('Начать игру')

        // Установка пользовательских данных
        this.userData = {
          score: 0,
          level: 1,
          preferences: {
            language: 'ru',
            theme: 'light'
          }
        };
        return;
      }

      // Обработка команды помощи
      if (intentName === HELP_INTENT_NAME) {
        this.text = 'Я могу помочь вам с...';
        this.buttons.addBtn('Назад');
        return;
      }

      // Обработка пользовательских событий
      if (this.userEvents?.auth?.status) {
        this.text = 'Вы успешно авторизовались!';
      }

      // Обработка оценки
      if (this.userEvents?.rating?.status) {
        const rating = this.userEvents.rating.value;
        this.text = `Спасибо за оценку ${rating}!`;
      }

    } catch (error) {
      // Обработка ошибки
      this.text = 'Произошла ошибка. Попробуйте позже.';
    }
  }
}

See

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

Type Parameters

TUserData extends IUserData = IUserData
TPlatformState extends IPlatformData = IPlatformData

Hierarchy (View Summary)

BotController
- BaseBotController

Constructors

constructor

new BotController<
    TUserData extends IUserData = IUserData,
    TPlatformState extends IPlatformData = IPlatformData,
>(
    appContext?: AppContext<IDatabaseInfo, unknown>,
): BotController<TUserData, TPlatformState>
Создает новый экземпляр контроллера. Инициализирует все необходимые компоненты.
Type Parameters
- TUserData extends IUserData = IUserData
- TPlatformState extends IPlatformData = IPlatformData
Parameters
- OptionalappContext: AppContext<IDatabaseInfo, unknown>
Returns BotController<TUserData, TPlatformState>
- Defined in controller/BotController.ts:685

Properties

appContext

appContext: AppContext

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

appeal

appeal: "official" | "no_official" | null = null

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

Remarks

Возможные значения:

'official': официальное обращение
'no_official': неофициальное обращение
null: стиль не определен

Example

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

appType

appType: string | null = null

Платформа от которой был получен запрос.

emotion

emotion: string | null = null

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

Example

this.emotion = 'good';

isAuth

isAuth: boolean = false

Флаг необходимости авторизации. Определяет, требуется ли авторизация пользователя или нет.

Example

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

isEnd

isEnd: boolean = false

Флаг, определяющий необходимость завершения диалога. Актуально когда необходимо принудительно завершить диалог с пользователем. Поддержка работы флага зависит от платформы.

Example

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

isScreen

isScreen: boolean = false

Определяет, с колонки пользователь запустил приложение или с устройства с экраном.

Example

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

isSendRating

isSendRating: boolean = false

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

Example

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

messageId

messageId: string | number | null = null

ID сообщения. Используется для определения начала нового диалога.

Example

this.messageId = 12345;

oldIntentName

oldIntentName: string | null = null

Название предыдущего интента/команды, полученное из userData.oldIntentName. Используется для отслеживания контекста диалога.

Remarks

КАК ЭТО РАБОТАЕТ:

В конце обработки каждого запроса, this.thisIntentName сохраняется в userData.oldIntentName
При следующем запросе это значение копируется в this.oldIntentName
Используется для определения, с какого шага продолжить диалог

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

Возврат к предыдущему шагу
Многошаговые формы ("вернуться назад")
Диалоги с контекстом
Использование в шагах bot.addStep()

Example

// Пример: Многошаговая регистрация
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;
  }
}

originalUserCommand

originalUserCommand: string | null = null

Оригинальный запрос пользователя. Текст запроса без изменений, включая регистр и знаки препинания.

Example

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

payload

payload: string | Record<string, unknown> | null | undefined = null

Дополнительные параметры запроса. Может содержать любые дополнительные данные полученные от платформы.

Example

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

platformOptions

platformOptions: IPlatformOptions = {}

Дополнительные опции платформы. ⚠️ Внутреннее свойство. Заполняется адаптером платформы. Не предназначено для прямого использования в пользовательском коде.

requestObject

requestObject: unknown = null

Полученный запрос от платформы. Содержит оригинальный объект запроса.

Example

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

skipAutoReply

skipAutoReply: boolean = false

Флаг, указывающий, что ответ уже отправлен через API и не требуется автоматическая отправка. Как правило, данный флаг стоит использовать для платформ, которые не ждут ответ в виде возвращаемого содержимого, а ожидают что к самой платформе будет отправлен запрос. Например, чат-бот для Telegram, для отображения результата пользователю, отправляется запрос к платформе с нужным содержимым.

Remarks

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

Example

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

state

state: TPlatformState | null = null

Пользовательское локальное хранилище. Используется для временного хранения данных, специфичных для текущего диалога. Работает только при включённой опции isLocalStorage: true в конфигурации. bot.setAppConfig({ isLocalStorage: true, });

Правила синхронизации с базой данных (если подключена):

Если заполнены и userData, и state:
- userData сохраняется в БД,
- state сохраняется в локальное хранилище платформы.
Если заполнен только userData (а state пуст или равен userData):
- данные сохраняются только в БД (состояние платформы не обновляется).
Если заполнен только state:
- данные сохраняются только в локальное хранилище.

При загрузке данных:

Если есть данные из локального хранилища и из БД, они попадают соответственно в state и userData.
Если есть только данные из хранилища, они копируются и в userData, и в state (для удобства).
Если есть только данные из БД, они записываются в userData.

See

userData — для постоянного хранения данных пользователя.

Example

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

text

text: string = ''

Текст, который будет отображен пользователю. Основной способ коммуникации с пользователем, так как именно этот текст пользователь увидит в интерфейсе.

Example

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

thisIntentName

thisIntentName: string | null = null

Название текущего интента. Определяет следующий шаг диалога.

Example

this.thisIntentName = 'help';

tts

tts: string | null = null

Текст, который пользователь может услышать. Для голосовых платформ, озвучка будет произведена силами самой платформы, для не голосовых платформ, поведение зависит непосредственно от реализации адаптера. Так для некоторых стандартных адаптеров, в случае заполнения поля и указания токена yandex SpeechKit, будет отправлен запрос на преобразование текста в аудиофайл, после чего аудиофайл будет отправлен пользователю.

Example

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

userCommand

userCommand: string | null = null

Запрос пользователя в нижнем регистре.

Example

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

userData

userData: TUserData = ...

Пользовательские данные, который были сохранены.

Example

this.userData = {
  name: 'John',
  preferences: {
    language: 'ru'
  }
};

userEvents

userEvents: IUserEvent | null = null

Пользовательские событий. Содержит информацию об авторизации или оценке.

See

IUserEvent

Example

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

userId

userId: string | number | null = null

Уникальный идентификатор пользователя.

Example

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

userMeta

userMeta: unknown = null

Дополнительная информация о пользователе.

Example

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

userToken

userToken: string | null = null

Пользовательский токен авторизации. Используется для авторизованных запросов (например, в Алисе).

Example

this.userToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

Accessors

buttons

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

Returns Buttons
Remarks
🎯 ТИПИЧНОЕ ИСПОЛЬЗОВАНИЕ:
- Навигация по меню
- Быстрые ответы (Да/Нет)
- Выбор из вариантов
- Быстрое действие/команда
See
Buttons
Example
```
this.buttons
  .addBtn('Помощь')
  .addBtn('Выход');
```
- Defined in controller/BotController.ts:711

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'
    }
  )

nlu

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

Returns Nlu
See
Nlu
- Defined in controller/BotController.ts:820

sound

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

Returns Sound
See
Sound
- Defined in controller/BotController.ts:799

Methods

`Protected`_actionMetric

_actionMetric(
    commandName: string | null,
    isCommand?: boolean,
    isStep?: boolean,
): void
Запуск обработки пользовательских команд с учетом метрик.
Parameters
- commandName: string | null
- isCommand: boolean = false
- isStep: boolean = false
Returns void
- Defined in controller/BotController.ts:1226

`Protected`_getCommand

_getCommand(): void | Promise<void> | null
Извлекает нужную команду из запроса.

Returns void | Promise<void> | null
найденная команда или null если не удалось найти команду
- Defined in controller/BotController.ts:1057

`Protected`_getIntent

_getIntent(text: string | null): string | null
Находит нужный интент по тексту запроса.
Parameters
- text: string | null
  Текст запроса
Returns string | null
Название интента или null
- Defined in controller/BotController.ts:905

`Protected`_intents

_intents(): IAppIntent[]
Возвращает список всех зарегистрированных интентов.

Returns IAppIntent[]
Массив интентов
- Defined in controller/BotController.ts:895

`Abstract`action

action(intentName: string | null, isCommand?: boolean, isStep?: boolean): void
Основной метод, в котором вы реализуете логику вашего голосового навыка или бота.

Этот метод вызывается фреймворком автоматически после того, как запрос пользователя был распознан как команда, интент или шаг диалога. В параметр intentName передаётся имя команды. Флаги isCommand и isStep позволяют различить источник вызова. Используется для более глубокой логики приложения, например можно использовать в качестве логирования, если все обработчики реализованы через команды. Либо использовать в качестве обработки команд, что не рекомендуется, так как из-за подобного подхода, размер метода может быть большим.

Метод необходимо обязательно реализовать в дочерних классах.
Parameters
- intentName: string | null
  Название интента или команды
- OptionalisCommand: boolean
  Флаг, указывающий что это команда
- OptionalisStep: boolean
  Флаг, указывающий что это шаг
Returns void
Example
```
// Пример с обработкой интентов
class MyController extends BotController {
  public action(intentName: string | null): void {
    if (intentName === 'greeting') {
      this.text = 'Привет!';
    } else if (intentName === 'help') {
      this.text = 'Помощь:';
      this.buttons.addBtn('Назад');
    }
  }
}

// Пример с логированием
class MyController extends BotController {
  public action(intentName: string | null, isCommand?: boolean, isStep?: boolean): void {
    console.log(`Прошли по ${isCommand ? 'команде' : isStep ? 'шагу' : 'интенту'} с именем: ${intentName}`);
  }
}
```
- Defined in controller/BotController.ts:1182

clearStoreData

clearStoreData(): void
Очищает все временные данные необходимые для отправки ответа.

Returns void
- Defined in controller/BotController.ts:856

isButtonsInit

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

Returns boolean
- Defined in controller/BotController.ts:722

isCardInit

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

Returns boolean
- Defined in controller/BotController.ts:789

isNluInit

isNluInit(): boolean
Флаг возвращающий информацию о том, были ли инициализирован nlu или нет

Returns boolean
- Defined in controller/BotController.ts:831

isSoundInit

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

Returns boolean
- Defined in controller/BotController.ts:810

run

run(): void | Promise<void>

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

Returns void | Promise<void>

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

Remarks

КРАТКИЙ ОБЗОР РАБОТЫ:

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

ЧТО НЕ НУЖНО ДЕЛАТЬ:

❌ Не вызывайте run() вручную в своем коде
❌ Не переопределяйте этот метод
✅ Переопределяйте только метод action() для своей логики

ПОСЛЕДОВАТЕЛЬНОСТЬ ОБРАБОТКИ ВНУТРИ run():

run()
  ├── Шаг 1: Проверяет есть ли активный шаг
  │     → Если есть → вызывает action(stepName, false, true)
  ├── Шаг 2: Ищет команду
  │     → Если нашел → вызывает action(commandName, true, false)
  ├── Шаг 3: Ищет интент
  │     → Если нашел → вызывает action(intentName, false, false)
  └── Шаг 4: Если ничего не нашел → Fallback команда

Example

// ВАШ КОД (контроллер):
class MyController extends BotController {
  public action(intentName: string | null): void {
    // Ваша логика здесь
    this.text = "Ответ пользователю";
  }
}

// КОД ФРЕЙМВОРКА (не ваш):
// Когда приходит запрос от пользователя:
const controller = new MyController();
{...}; // Наполняет контроллер данными. Как правило, этим занимается адаптер платформы
await controller.run(); // Автоматически вызывает ваш action()
const response = ...; // Адаптер формирует ответ в зависимости от состояния контроллера

setAppContext

setAppContext(appContext: AppContext): this
Устанавливает контекст приложения.
Parameters
- appContext: AppContext
Returns this
- Defined in controller/BotController.ts:839

Class BotController<TUserData, TPlatformState>Abstract

Remarks

Example

See

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns BotController<TUserData, TPlatformState>

Properties

appContext

appeal

Remarks

Example

appType

emotion

Example

isAuth

Example

isEnd

Example

isScreen

Example

isSendRating

Example

messageId

Example

oldIntentName

Remarks

Example

originalUserCommand

Example

payload

Example

platformOptions

requestObject

Example

skipAutoReply

Remarks

Example

state

See

Example

text

Example

thisIntentName

Example

tts

Example

userCommand

Example

userData

Example

userEvents

See

Example

userId

Example

userMeta

Example

userToken

Example

Accessors

buttons

Returns Buttons

Remarks

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

See

Example

card

Returns Card

Remarks

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

Class BotController<TUserData, TPlatformState>`Abstract`

`Protected`_actionMetric

`Protected`_getCommand

`Protected`_getIntent

`Protected`_intents

`Abstract`action