Создает новый экземпляр приложения
Optionaltype: stringТип платформы (по умолчанию автоопределение)
OptionalbotController: TBotControllerClass<TUserData>Контроллер с логикой
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('Какой-то сервис для получения погоды');
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
Устанавливает контроллер, метод 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('Подписаться на рассылку', 'http://localhost');
}
// Логирование
console.log(`Обработано: ${isCommand ? 'команда' : isStep ? 'шаг' : 'интент'} – ${intentName}`);
}
}
bot.initBotController(MyController);
Удаляет зарегистрированную команду по имени
Имя команды
Удаляет зарегистрированный шаг по имени.
После удаления шаг больше не будет обрабатываться, даже если активен у пользователя.
(Рекомендуется завершать активные сценарии через ctx.clearStep() перед удалением.)
— Имя шага для удаления.
Текущий экземпляр Bot.
Выполняет непосредственную обработку входящего запроса от платформы. Этот метод не запускает HTTP-сервер и не обрабатывает HTTP-запросы напрямую — он принимает уже распарсенные данные и возвращает результат обработки.
Обычно вызывается внутри webhookHandle, но может использоваться напрямую, если вы реализуете собственный обработчик запросов, тестируете логику приложения или запускаете его вне HTTP-контекста (например, из консоли или очереди сообщений).
OptionalappType: string | null = nullТип приложения. Если не указан, будет определен автоматически в зависимости от запроса.
Optionalcontent: string | object | null = 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),Параметры платформы
Устанавливает кастомный обработчик для определения типа платформы.
По умолчанию фреймворк определяет платформу автоматически, перебирая зарегистрированные адаптеры
и вызывая их метод isPlatformOnQuery. Этот метод позволяет переопределить логику определения,
что полезно в следующих случаях:
Важно: резолвер выполняется до вызова isPlatformOnQuery любого адаптера.
Если резолвер возвращает строку (имя платформы), фреймворк использует это значение
и не выполняет стандартное автоопределение. Если возвращает null, то запускается
стандартный перебор адаптеров.
В резолвер передаётся опциональная функция detect, которая вызывает встроенное
автоопределение. Это позволяет, например, получить результат стандартного определения
и затем скорректировать его.
Функция, принимающая запрос, заголовки и опционально detect.
Должна вернуть имя платформы (строка) или null.
Тот же экземпляр приложения для цепочечных вызовов.
// Простейший резолвер, который для всех запросов использует платформу 'alisa'
bot.setPlatformResolver(() => 'alisa');
// Резолвер, который вызывает стандартное определение и при необходимости
// заменяет результат для конкретного заголовка.
bot.setPlatformResolver((query, headers, detect) => {
const platform = detect?.(query, headers);
if (platform === 'telegram' && headers?.['x-force-vk']) {
return 'vk';
}
return platform;
});
// Полное переопределение: обработка запросов от собственного сервиса.
bot.setPlatformResolver((query) => {
if (typeof query === 'object' && query?.source === 'my_service') {
return 'my_platform';
}
return null;
});
async и возвращайте Promise<string | null>. Фреймворк дождётся
результата перед продолжением.query или headers, если нужно повлиять
на дальнейшую обработку (например, добавить недостающие поля).Запускает встроенный 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(...);// Какое-то содержимое страницы
});
Регистрирует 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);
Мультиплатформенный фреймворк для разработки голосовых навыков и чат-ботов. Он даёт единую бизнес-логику для все платформ — но одинаково эффективен, даже если вы работаете только с одной.
Bot— главный класс, управляющий всем жизненным циклом приложения:Фреймворк построен на адаптерах — каждый адаптер отвечает за преобразование специфичного для платформы запроса в унифицированный
BotController, который содержит всю информацию о пользователе, текст команды, NLU, состояние и методы ответа (кнопки, карточки, TTS). Вы пишете один код, а фреймворк доставляет его на все поддерживаемые платформы.📖 КРАТКОЕ РУКОВОДСТВО
const bot = new Bot();bot.setAppConfig({ tokens: { telegram: {token: '...'}} });bot.initBotController(MyController);bot.addCommand('start', ['старт'], handler);bot.start();🎯 Ключевые возможности
🚀 БЫСТРЫЙ СТАРТ
Создание простого Telegram бота
Создание простого приложения со своим контроллером:
Использование с базой данных:
See
BotController