Class BotController<TUserData, TPlatformState>`Abstract`

Базовый класс контроллера приложения. Предоставляет базовый функционал для обработки пользовательских запросов.

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 = 'Произошла ошибка. Попробуйте позже.';
    }
  }
}

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>,
): BotController<TUserData, TPlatformState>
Создает новый экземпляр контроллера. Инициализирует все необходимые компоненты.
Type Parameters
- TUserData extends IUserData = IUserData
- TPlatformState extends IPlatformData = IPlatformData
Parameters
- OptionalappContext: AppContext<IDatabaseInfo>
Returns BotController<TUserData, TPlatformState>
- Defined in src/controller/BotController.ts:668

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; // экран доступен

isSend

isSend: boolean = false

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

Remarks

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

Example

this.isSend = 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 | object | 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' }
};

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: object | null = 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 src/controller/BotController.ts:694

card

get card(): Card

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

Returns Card

Remarks

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

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

See

Card

Example

// КАТАЛОГ ТОВАРОВ (интернет-магазин):
this.text = 'Популярные товары:';
this.card
  .addImage(
    'https://example.com/iphone.jpg',
    'iPhone 15 Pro',
    '99 990 ₽\nЭкран 6.1", процессор A17 Pro'
  )
  .addButton('Купить')

  .addImage(
    'https://example.com/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: 'https://example.com/news/1'
    }
  )

nlu

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

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

sound

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

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

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 src/controller/BotController.ts:1170

`Protected`_getCommand

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

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

`Protected`_getIntent

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

`Protected`_intents

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

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

`Abstract`action

action(intentName: string | null, isCommand?: boolean, isStep?: boolean): void
Метод для обработки пользовательских команд и интентов. Используется для более глубокой логики приложения, например можно использовать в качестве логирования, если все обработчики реализованы через команды. Либо использовать в качестве обработки команд, что не рекомендуется, так как из-за подобного подхода, размер метода может быть большим.

Метод необходимо обязательно реализовать в дочерних классах.
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 src/controller/BotController.ts:1126

clearStoreData

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

Returns void
- Defined in src/controller/BotController.ts:839

isButtonsInit

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

Returns boolean
- Defined in src/controller/BotController.ts:705

isCardInit

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

Returns boolean
- Defined in src/controller/BotController.ts:772

isNluInit

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

Returns boolean
- Defined in src/controller/BotController.ts:814

isSoundInit

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

Returns boolean
- Defined in src/controller/BotController.ts:793

setAppContext

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

Class BotController<TUserData, TPlatformState>Abstract

Remarks

Example

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

isSend

Remarks

Example

isSendRating

Example

messageId

Example

oldIntentName

Remarks

Example

originalUserCommand

Example

payload

Example

platformOptions

requestObject

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

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

See

Class BotController<TUserData, TPlatformState>`Abstract`

`Protected`_actionMetric

`Protected`_getCommand

`Protected`_getIntent

`Protected`_intents

`Abstract`action