Optionaltype: stringOptionalbotController: TBotControllerClassProtected_Protected_Полученный запрос от пользователя. Может быть JSON-строкой, текстом или null
Возвращает установленный тип приложения.
Явно устанавливает тип платформы для всего приложения. Стоит использовать в крайнем случае
Protected_Очищает состояние пользователя
Protected_ProtectedУстановка контроллера. Используется только для тестирования
Регистрирует команду — обработчик, срабатывающий при совпадении входящего текста с одним из шаблонов.
Поиск команд оптимизирован:
Первая совпавшая команда выполняется.
Уникальное имя команды (например, 'greeting'). Используется для логирования и отладки.
Массив шаблонов для сопоставления:
text.includes(...))..test(text)).isPattern учитывается только если в slots нет RegExp.RegExp, isPattern = false игнорируется, и каждый элемент
обрабатывается согласно своему типу.Обработчик команды. Принимает:
text — исходный текст от пользователя;controller — экземпляр BotController для формирования ответа (кнопки, текст, шаги, данные и т.д.);Поддерживает async.
Если true и в slots нет RegExp, все строки преобразуются в регулярные выражения.
⚠️ Используйте с осторожностью: возможен ReDoS. Все RegExp проверяются на уязвимости.
Простая текстовая команда:
bot.addCommand(
'greeting',
['привет', 'здравствуй'],
(cmd, ctrl) => {
ctrl.text = 'Здравствуйте!';
}
);
Команда с регулярными выражениями:
// Обработка чисел от 0 до 999
bot.addCommand(
'number',
['\\b(\\d{0,3})\\b'],
(cmd, ctrl) => {
ctrl.text = `Вы ввели число: ${cmd}`;
},
true // включаем поддержку регулярных выражений
);
Команда с доступом к состоянию:
bot.addCommand(
'stats',
['статистика'],
async (cmd, ctrl) => {
if (ctrl) {
// Доступ к пользовательским данным
const visits = ctrl.userData?.visits || 0;
ctrl.text = `Вы использовали бота ${visits} раз`;
// Доступ к кнопкам и другим UI элементам
ctrl.buttons
.addBtn('Сбросить статистику')
.addBtn('Закрыть');
}
}
);
// Асинхронная команда (работа с API):
bot.addCommand('weather', ['погода'], async (text, controller) => {
const weather = await fetch('https://api.weather.com');
controller.text = `Погода: ${await weather.text()}`;
});
// Fallback: срабатывает, если ни одна команда не подошла:
bot.addCommand('*', [], (text, controller) => {
controller.text = `Извините, я не понял "${text}". Скажите "помощь" для списка команд.`;
});
Поиск команд оптимизирован:
При регистрации более 300 команд с регулярными выражениями фреймворк автоматически объединяет их в группы для повышения производительности.
При isPattern=true используются регулярные выражения JavaScript В callback доступен весь функционал BotController Можно использовать async функции в callback
Регистрирует обработчик для именованного шага диалога.
Шаг — это часть многошагового сценария (например: "регистрация", "оформление заказа").
После вызова ctx.thisIntentName = 'myStep' в команде или другом шаге,
следующее сообщение пользователя будет обработано этим обработчиком.
💡 Обработчик получает полный
BotController, как и в командах: доступныthis.text,this.userData,this.buttonsи т.д.
— Уникальное имя шага (например, 'enter_email').
— Функция, вызываемая при получении сообщения в этом шаге.
Текущий экземпляр Bot (для цепочки вызовов).
bot.addCommand('start', ['начать'], (_, ctx) => {
ctx.text = 'Готовы начать приключение?';
ctx.buttons.addBtn('Да').addBtn('Нет');
ctx.thisIntentName = 'confirm';
});
bot.addStep('confirm', (ctx) => {
if (ctx.userCommand === 'да') {
ctx.text = 'Отлично! Добро пожаловать.';
} else {
ctx.text = 'Извините, вход запрещён.';
ctx.thisIntentName = 'goodbye'; // переходим к другому шагу
}
});
// Пример многошаговой формы
bot.addCommand('order', ['заказать'], (_, ctx) => {
ctx.text = 'Введите ваше имя:';
ctx.thisIntentName = 'step_name';
});
bot.addStep('step_name', (ctx) => {
ctx.userData.name = ctx.userCommand;
ctx.text = `Приятно познакомиться, ${ctx.userData.name}! Теперь введите email:`;
ctx.thisIntentName = 'step_email';
});
bot.addStep('step_email', (ctx) => {
ctx.userData.email = ctx.userCommand;
ctx.text = `Заказ оформлен! Имя: ${ctx.userData.name}, Email: ${ctx.userData.email}`;
ctx.thisIntentName = null; // сбрасываем шаг
});
Удаляет все зарегистрированные команды
⚠️ Это глобальная операция: все сценарии станут недоступны. Используйте с осторожностью (например, при перезагрузке логики бота).
Удаляет все зарегистрированные шаги.
⚠️ Это глобальная операция: все сценарии станут недоступны. Используйте с осторожностью (например, при перезагрузке логики бота).
Текущий экземпляр Bot.
Удаляет все зарегистрированные платформы, плагины и middleware службы.
⚠️ Это глобальная операция: все сценарии станут недоступны. Используйте с осторожностью (например, при перезагрузке логики бота).
Текущий экземпляр Bot.
Корректно завершает работу встроенного HTTP-сервера (если он был запущен через start). Ожидает завершения всех текущих запросов, освобождает сетевые ресурсы и отменяет все активные асинхронные операции, связанные с жизненным циклом бота.
Метод безопасен для повторного вызова.
Завершается, когда сервер остановлен и все ресурсы освобождены.
Возвращает контекст приложения — центральный объект для расширенной настройки фреймворка.
Когда использовать:
bot.getAppContext().httpClient = customFetchbot.getAppContext().platformsПример:
// Добавление таймаутов к запросам
const customFetch: THttpClient = async (url, init) => {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);
return fetch(url, { ...init, signal: controller.signal });
};
bot.getAppContext().httpClient = customFetch;
⚠️ Важно: Не модифицируйте внутренние поля контекста напрямую (например, commands, steps). Используйте публичные методы addCommand(), addStep
ProtectedgetProtectedФормирует конфигурацию для тестирования конкретной платформы. Создает структуру данных, соответствующую формату выбранной платформы
Пользовательский запрос
Номер сообщения в диалоге
Данные из хранилища
Конфигурация для выбранной платформы
Устанавливает контроллер, метод action() которого вызывается после обработки каждого запроса —
независимо от того, была ли распознана команда, активен ли шаг сценария, или обработан базовый интент.
Метод action() получает флаги isCommand и isStep, чтобы вы могли:
💡 Рекомендация: основную бизнес-логику размещайте в командах (
addCommand) и шагах (addStep), а вaction()— только сквозную логику, которую не хочется дублировать.
Контроллер по умолчанию уже обрабатывает интенты welcome, help и fallback,
но вы можете заменить его, если нужно кастомное поведение.
Экземпляр контроллера, наследующий BotController<TUserData>
class MyController extends BotController {
public action(intentName: string): void {
switch (intentName) {
case 'greeting':
this.text = 'Привет!';
break;
case 'help':
this.text = 'Чем могу помочь?';
break;
}
}
}
bot.initBotController(MyController);
// Добавление рекламы ко всем ответам
class MyController extends BotController {
public action(
intentName: string | null,
isCommand: boolean = false,
isStep: boolean = false
): void {
// Добавим кнопку "Подписаться" везде, кроме шагов
if (!isStep) {
this.buttons.addBtn('Подписаться на рассылку', 'https://example.com');
}
// Логирование
console.log(`Обработано: ${isCommand ? 'команда' : isStep ? 'шаг' : 'интент'} – ${intentName}`);
}
}
bot.initBotController(MyController);
Удаляет зарегистрированную команду по имени
Имя команды
Удаляет зарегистрированный шаг по имени.
После удаления шаг больше не будет обрабатываться, даже если активен у пользователя.
(Рекомендуется завершать активные сценарии через ctx.clearStep() перед удалением.)
— Имя шага для удаления.
Текущий экземпляр Bot.
Запуск обработку запроса Не рекомендуется вызывать самостоятельно, ответственность за вызов метода лежит за классом.
OptionalappType: string | nullOptionalcontent: string | nullОтправка текста пользователю
Этот метод используется для активных рассылок — когда бот инициирует диалог первым (например, уведомление).
В методе реализована механика преобразования текстового значения controllerOrText в контроллер, а также базовый механизм для отправки ответа.
Если платформа не поддерживает возможность начать диалог самостоятельно, то вернется false
Ид пользователя, которому нужно отправить сообщение
Контроллер приложения или текст. Если необходимо отправить просто текст, можно передать строку, в случае, если необходимо передать картинку звук и тд, то необходимо корректно заполнить контроллер.
Платформа, на которую необходимо отправить запрос
Задаёт инфраструктурную конфигурацию приложения: подключение к БД, загрузку .env, и другие
настройки, связанные с окружением выполнения (а не с бизнес-логикой бота).
🔒 Безопасность: никогда не храните секреты (пароли, токены, API-ключи) прямо в коде. Всегда используйте
.env-файлы или переменные окружения.
Конфигурация приложения
Устанавливает режим работы приложения
Режим работы:
⚠️ ВАЖНО: В продакшене всегда используйте 'strict_prod' для защиты от атак через регулярные выражения. Режим 'prod' оставлен для обратной совместимости, но небезопасен.
Задает режим работы с регулярным выражениями. При значении auto, регулярные выражения будут группироваться в группу, благодаря чему уменьшается время обработки. Логика начинает отрабатывать после того, как добавили более 300 команд. При значении no-group, группировка регулярных выражений производиться не будет, из-за чего каждое регулярное выражение будет обрабатываться отдельно. Указывать данное значение стоит в том случае, если вы получаете сильную деградацию при обработке групп. При значении group, все регулярные выражения будут добавляться в группу. Перед использованием данного значения, перепроверьте производительность, так как при группировке определенных регулярных выражений, производительность может быть ниже.
Определяет режим работы с регулярными выражениями.
Устанавливает контент запроса. Используется для передачи данных от пользователя в бот. Не рекомендуется использовать напрямую, использовать только в крайнем случае, либо для тестов
Контент запроса
Позволяет заменить встроенный механизм сопоставления команд на кастомный алгоритм поиска.
По умолчанию umbot использует оптимизированный поиск:
includes),Это обеспечивает предсказуемость, простоту отладки и соответствие поведению большинства платформ: первая совпавшая команда (в порядке регистрации) — выигрывает.
Однако при:
Функция вида (userText: string, commands: Map<string, ICommand>) => string | null.
Должна вернуть имя команды или null, если совпадений нет.
// Пример: кэширование частых запросов
const cache = new Map<string, string | null>();
bot.setCustomCommandResolver((text, commands) => {
if (cache.has(text)) return cache.get(text)!;
for (const [name, cmd] of commands) {
if (cmd.slots && cmd.slots.some(slot => typeof slot === 'string' && text.includes(slot))) {
cache.set(text, name);
return name;
}
}
cache.set(text, null);
return null;
});
Рекомендации при реализации resolver'а:
fuse.js, natural или trie-структуры.Задаёт параметры, управляющие логикой бота на всех платформах.
Сюда входят:
help, welcome и др.),welcome_text, help_text, empty_text),Параметры платформы
Запускает встроенный HTTP-сервер на указанном хосте и порту для приёма webhook-запросов
от поддерживаемых платформ. Сервер использует нативный http.createServer.
Метод возвращает экземпляр http.Server, что позволяет, например, корректно
остановить сервер или добавить обработчики событий ('listening', 'error' и т.д.).
Если требуется интеграция с фреймворком (например, Express, Fastify и др.), рекомендуется использовать webhookHandle как middleware-обработчик.
Имя хоста
Порт
OptionalresponseCb: TBotResponseCbCallback, для пользовательской обработки ответа пользователю. Стоит использовать в том случае, если есть необходимость переопределить стандартный ответ фреймворка.
// Запуск встроенного сервера
const bot = new Bot();
bot.start('0.0.0.0', 8080);
// Интеграция с Express (вместо встроенного сервера)
import express from 'express';
import { Bot } from 'umbot';
const bot = new Bot();
const app = express();
app.use(express.json());
app.post('/webhook', (req, res) => bot.webhookHandle(req, res));
app.listen(3000, () => {
console.log('Bot listening on port 3000');
});
// Пример с переопределением ответа
const bot = new Bot();
// В случае если вернулся статус отличный от 200, вернет содержимое какой-то страницы.
bot.start('0.0.0.0', 8080, (reg: IncomingMessage, _res: ServerResponse, state: IBotResponseState) => {
if (state.statusCode === 200) {
return state.defaultSend(_res, state);
}
res.statusCode = 200;
res.end(...);// Какое-то содержимое страницы
});
Запускает интерактивное тестирование бота Позволяет вводить команды и получать ответы в консоли
Optionalparams: IBotTestParams = {}Параметры тестирования
Регистрирует middleware, вызываемый до выполнения BotController.action().
Middleware получает доступ к полному BotController (включая text, isEnd, userData, buttons и т.д.)
и может:
next())Middleware-функция
Текущий экземпляр Bot для цепочки вызовов
Регистрирует middleware, вызываемый только для указанной платформы.
Идентификатор платформы (alisa, telegram, vk, и т.д.)
Middleware-функция
Текущий экземпляр Bot
Регистрирует плагин — объект, расширяющий функциональность приложения.
Плагин может быть как функцией, так и классом.
Если он реализован как метод, то должен быть указан флаг isPlugin.
В случае когда используется класс, то должен быть реализован метод init(appContext: AppContext)
— Объект плагина, совместимый с TPlugin.
Текущий экземпляр Bot.
Обрабатывает входящий webhook-запрос от поддерживаемой платформы (Telegram, VK, Алиса и др.).
Метод автоматически распознаёт платформу по заголовкам или телу запроса и делегирует обработку
соответствующему адаптеру. Ответ отправляется автоматически через переданный объект res.
Объект входящего запроса (IncomingMessage или совместимый)
Объект ответа (ServerResponse или совместимый)
OptionalresponseCb: TBotResponseCbCallback, для пользовательской обработки ответа пользователю. Стоит использовать в том случае, если есть необходимость переопределить стандартный ответ фреймворка. Если передан, ВЫ ДОЛЖНЫ вызвать res.end() самостоятельно. Без колбэка фреймворк автоматически завершит ответ через res.end().
// Использование с Express
import express from 'express';
const app = express();
app.use(express.json());
const bot = new Bot();
app.post('/webhook', (req, res) => bot.webhookHandle(req, res));
// Использование с встроенным HTTP-сервером Node.js
import { createServer } from 'http';
const bot = new Bot();
const server = createServer((req, res) => {
if (req.method === 'POST' && req.url === '/webhook') {
bot.webhookHandle(req, res);
} else {
res.statusCode = 404;
res.end();
}
});
server.listen(3000);
// Пример с переопределением ответа
import { createServer } from 'http';
const bot = new Bot();
const server = createServer((req, res) => {
if (req.method === 'POST' && req.url === '/webhook') {
// В случае если вернулся статус отличный от 200, вернет содержимое какой-то страницы.
bot.webhookHandle(req, res, (_reg: IncomingMessage, _res: ServerResponse, state: IBotResponseState) => {
if (state.statusCode === 200) {
return state.defaultSend(_res, state);
}
res.statusCode = 200;
res.end(...);// Какое-то содержимое страницы
});
} else {
res.statusCode = 404;
res.end();
}
});
server.listen(3000);
Класс для тестирования бота. Предоставляет интерактивный режим для отладки и тестирования функциональности. Для того чтобы протестировать необходимую платформу, необходимо указать
appType, в случае если значение не указано или установлено в auto, то для тестирования будет использоваться первая платформа.Example