umbot — это TypeScript-фреймворк для разработки голосовых навыков и чат-ботов. Он даёт единую бизнес-логику для всех
платформ — но одинаково эффективен, даже если вы работаете только с одной.
Поддерживаются: Яндекс.Алиса, Сбер Салют (SmartApp), а также Telegram, VK, MAX и Viber из коробки.
Для существующих навыков Маруси есть отдельный адаптер.
В отличие от большинства решений, требующих отдельной реализации под каждую платформу, umbot абстрагирует различия в
форматах запросов и ответов, предоставляя разработчику единый, предсказуемый интерфейс. Это позволяет писать логику один
раз — и запускать её везде.
Фреймворк следует SemVer. Breaking changes возможны только в MAJOR-версиях.
English: documentation in English (machine-translated from Russian).
Больше не нужно писать несколько версий одного приложения.
Больше не нужно разбираться в JSON-форматах Алисы, Сбера, Маруси, Telegram, MAX и т. д.
Бизнес-логика — одна. Платформа — любая.
Ключевые преимущества:
- Одна кодовая база для любой платформы. Хотите только Алису? Легко. Решите добавить Сбер Салют или Telegram — просто добавьте нужный адаптер, логика остаётся.
- В типичных сценариях (до 1 000 команд) полная обработка запроса внутри фреймворка, включая поиск и выполнение команд, занимает менее 30 мс даже в самом сложном случае (fallback); в большинстве случаев — единицы–десятки миллисекунд. На бизнес-логику остаётся практически весь бюджет голосовых платформ: фреймворк пишет предупреждение при обработке дольше 2000 мс и ошибку — дольше 2900 мс, практический ориентир — ~3 секунды (подробнее — в «Производительность и гарантии»).
- При первичной загрузке медиафайлов время ответа может вырасти на 200–1000 мс на файл — поэтому
umbotрекомендует заранее загружать необходимые ресурсы через классPreload. - Безопасная обработка регулярных выражений с защитой от ReDoS из коробки
- Встроенное состояние, кэширование медиа, кнопки, карточки — «из коробки»
- TypeScript, CLI, автодополнение, развитое тестовое покрытие
- Дополнительные утилиты для навигации и поиска текста, ускоряющие разработку.
Ключевая мысль:
umbot— это не «надстройка для мультиплатформенности», а базовый слой, который делает разработку под любую платформу (даже одну) быстрее, чище и готовой к масштабированию.
umbot предоставляет унифицированный интерфейс для работы с ответами, но при этом учитывает специфику каждой платформы:
- Голосовые платформы (Алиса, Сбер Салют, Маруся) — всё, что нужно типичному навыку: текст и TTS, кнопки, карточки,
звуки, состояние сессии и пользователя, авторизация. Отдельные директивы Алисы (запрос геолокации, аудиоплеер,
события аналитики) фреймворк пока не абстрагирует — их можно добавить в своём наследнике
AlisaAdapter. - Чат-боты (Telegram, VK, Viber, MAX и др.) — поддерживается только необходимый и востребованный набор функций ( карточки, кнопки, аудиосообщения). Специфические элементы вроде опросов или кастомных интерфейсов мессенджеров исключены, так как они не имеют аналогов в голосовых платформах и редко нужны в кроссплатформенной логике.
Этот подход гарантирует, что ваш навык/бот будет вести себя предсказуемо и не потребует специальных обходных путей при переходе между платформами.
Большинство фреймворков (например, telegraf, alice-sdk и т.д.) ориентированы только на одну платформу. Чтобы
запустить приложение и в Алисе, и в Telegram, приходится:
- писать две (или больше) версии логики,
- поддерживать разные форматы ответов,
- дублировать обработку состояний, кнопок, медиа
- знать API каждой платформы.
umbot решает эту проблему:
одна бизнес-логика для всех платформ,
единый API для кнопок, карточек, голоса и текста,
автоматическая адаптация под формат каждой платформы "под капотом".
Это особенно ценно, если вы уже поддерживаете навык на Алисе и хотите быстро выйти в Сбер Салют, Telegram, MAX или VK — без переписывания или существенных доработок кода.
Даже если вы пока разрабатываете только под одну платформу, umbot избавляет от boilerplate, даёт единый API для работы
с состоянием, кнопками и медиа, а главное — не мешает, когда придёт время добавлять новые каналы.
umbot — это не просто обёртка под несколько платформ. Это архитектурное решение для проектов, где диалог инициирует
пользователь. Оно одинаково ценно как для одной платформы, так и для десятка.
Вы будете использовать umbot, если:
- Вы разрабатываете под одну платформу (Алиса, Сбер Салют, Telegram, VK и др.). Вы получите чистое разделение логики и транспорта, избавитесь от дублирования кода внутри проекта и заложите архитектуру, которая безболезненно масштабируется, когда потребуется вторая платформа. Инструмент не усложнит — он упорядочит.
- Вы поддерживаете несколько платформ одновременно. Вы перестанете синхронизировать изменения вручную. Новая функциональность появляется сразу везде, а поддержка разных API сводится к единому интерфейсу.
- Вы проектируете систему с прицелом на будущее.
Вы не хотите переписывать ядро, когда бизнес попросит добавить Telegram, корпоративный портал или голосового
ассистента.
umbotделает расширение предсказуемым. - Вы работаете в корпоративной среде с внутренними мессенджерами. Вы унифицируете разработку чат-ботов, упрощаете онбординг и переиспользование компонентов между командами.
- Вы цените чистоту кода и не терпите копипасту.
Вы устали переносить обработчики из проекта в проект или мучительно адаптировать бизнес-логику под каждый новый API.
umbotпозволяет писать ядро один раз и забыть о boilerplate.
| Платформа | Идентификатор | Что поддерживается |
|---|---|---|
| Яндекс.Алиса | alisa |
Протокол навыков: текст, TTS, кнопки, карточки, звуки, состояние, авторизация |
| Сбер Салют | smart_app |
Протокол SmartApp API: текст, озвучка, кнопки, карточки, состояние |
| Telegram | telegram |
Базовый набор: текст, кнопки (inline и reply), фото и медиагруппы, голос, callback, inline-запросы, события сообщений |
| VK | vk |
Базовый набор: текст, клавиатура, карусель, голос, callback-кнопки |
| MAX | max_app |
Базовый набор: текст, inline-клавиатура, изображения, аудио, callback, deep-link bot_started |
| Viber | viber |
Базовый набор: текст, клавиатура, rich media. Боты Viber с 2024 года создаются только на коммерческих условиях |
| Маруся | marusia |
Протокол навыков. VK закрыла создание новых навыков (20.12.2024) — только для существующих |
| Ваша платформа | ... |
За счет адаптеров |
Для мессенджеров «базовый набор» — это то, что имеет смысл в общей логике для всех платформ. Специфичные возможности
(опросы, платежи, редактирование сообщений и т. п.) фреймворк не абстрагирует, но они доступны напрямую: через
controller.api и API-клиенты платформ (TelegramRequest, VkRequest, MaxRequest, ViberRequest из
umbot/plugins, у каждого есть универсальный метод call(method)).
Платформы подключаются через вебхук, а Telegram, VK и MAX — ещё и через long polling:
bot.startPolling() вместо bot.start(), и для проверки бота на локальной машине не нужны ни HTTPS, ни туннель.
Алисе, Марусе, SmartApp и Viber нужен вебхук (для локальной проверки — туннель вроде ngrok). Без сети логику можно
проверить в консоли через BotTest. Проверку подписи вебхука Telegram и MAX включает одна команда:
npx umbot webhook <telegram|max> <https-url>, а npx umbot doctor проверяет токены, .env и состояние
вебхуков.
Нужна своя платформа?
Создайте каркас адаптера командойnpx umbot add platform <Name>— он сразу компилируется и проходит свой тест, а места под API платформы отмеченыTODO. Так же создаются адаптер БД (add db) и middleware (add middleware).
Это позволяет интегрироватьumbotв любую внутреннюю систему, корпоративный мессенджер или поддержать любую другую платформу, например WhatsApp или WeChat.
Отдельные npm-пакеты, которые подключаются одной строкой через bot.use(). Ядро остаётся лёгким: драйверы СУБД и
API сторонних платформ ставятся только тем, кому они нужны.
| Пакет | Назначение |
|---|---|
| umbot-knex-adapter | Реляционные БД через Knex.js: PostgreSQL, MySQL/MariaDB, SQLite, MSSQL |
| umbot-ydb-adapter | YDB (Yandex Database): хранилище для навыков и ботов в Yandex Cloud Functions, таблицы создаются сами |
| umbot-wechat-adapter | WeChat Official Account (Weixin) |
npm install umbot umbot-knex-adapter knex pgimport { Bot } from 'umbot';
import { TelegramAdapter } from 'umbot/plugins';
import { KnexAdapter } from 'umbot-knex-adapter';
const bot = new Bot()
.use(new TelegramAdapter(process.env.TELEGRAM_TOKEN))
.use(new KnexAdapter({ host: 'localhost', database: 'bot_db', options: { client: 'pg' } }));Хотите написать свой адаптер? Технические задания с контрактами и чек-листами готовности:
Установите фреймворк:
npm install umbotСоздайте и запустите проект за пять команд:
npx umbot create echo
cd echo
npm i
npm run build
npm startПоправьте файлы нужным вам образом. Например:
// index.ts
import { Bot } from 'umbot';
import { fullPlatforms } from 'umbot/plugins';
import { EchoController } from './controller/EchoController';
const bot = new Bot()
.use(fullPlatforms)
.setAppConfig({ json: './data', isLocalStorage: true })
.initBotController(EchoController);
bot.start('localhost', 3000);// EchoController.ts
import { BotController, WELCOME_INTENT_NAME } from 'umbot';
export class EchoController extends BotController {
public action(intentName: string | null): void {
if (intentName === WELCOME_INTENT_NAME) {
this.text = 'Привет! Я повторяю за вами.';
} else {
this.text = `Вы сказали: ${this.userCommand}`;
}
}
}Протестируйте приложение, и в случае необходимости опубликуйте его.
👉 Подробное руководство по запуску
В стресс-тестах на стандартном оборудовании (AMD Ryzen 5 5600G, Windows 10) фреймворк при 1003 командах показывает:
- Пропускная способность (реалистичный сценарий) — 68 000 RPS
(эмуляция полного цикла: входящий запрос → нормализация → логика → ответ) - Последовательная пропускная способность (ядро) — ~80 000 RPS
(максимальная скорость одного потока) - Под непрерывным потоком (1000 команд, 200 запросов in-flight) — 580 000–760 000 RPS, в 28–3 000 раз больше, чем у grammy, telegraf, vk-io, viber-bot, max-bot-api и yandex-dialogs-sdk в том же стенде (BENCHMARKS)
Важно:
- Тесты проводились без сетевых вызовов и операций с базами данных, поэтому цифры показывают потенциал ядра фреймворка.
- В реальном проекте итоговый RPS будет определяться внешними факторами (сеть, БД, логика приложения).
- На реальном сервере (2 ядра / 4 ГБ RAM) с фоновой нагрузкой фреймворк показывает 16 000+ RPS — подробнее в Производительность и гарантии.
Длительное тестирование (48 часов) не выявило утечек памяти или снижения производительности: средняя пропускная способность в последовательном сценарии осталась на уровне ~67 000 RPS, а потребление памяти стабильно.
Подробная документация доступна в следующих разделах:
- Быстрый старт - Подробное описание, для быстрого старта проекта
- Подробная инструкция по созданию приложений
- Рецепты - Готовые решения типовых задач
- API Reference - Подробное описание всех классов, методов и интерфейсов
- Поддерживаемые платформы - Руководство по интеграции с различными платформами
- Конфигурация и безопасность
- Кастомизация HTTP-клиента
- Производительность и гарантии
- Тестирование
- Развертывание
- Middleware
- FAQ
- 📚 Официальная документация
- 📢 Telegram канал
- 💬 Telegram группа
- 📦 npm package
- Создание навыка "Я никогда не"
- Примеры проектов
- Список изменений
- Миграция с umbot 2.x на 3.0
- CLI команды
Umbot Flow — визуальный редактор для создания ботов на фреймворке umbot. Собирайте логику на холсте, экспортируйте JSON-конфигурацию и генерируйте TypeScript-проект через CLI.
Цепочка:
Визуальный редактор → JSON-конфигурация → npx umbot create from-flow → TypeScript-проект → Ваш сервер
Быстрый старт с редактором:
- Откройте редактор в браузере
- Соберите логику бота на холсте
- Экспортируйте JSON-конфигурацию → скачайте
flow.json - Выполните:
npx umbot create from-flow flow.json --output ./my-bot
- Готовый проект в папке
my-bot
Описание JSON-формата — полная спецификация всех типов узлов, связей и правил генерации кода.
MIT License. См. LICENSE для деталей.
Если у вас есть вопросы или предложения:
- 📧 Email: maximco36895@yandex.ru
- 🐛 Issues на GitHub