umbot

This page is machine-translated from the Russian original. If something reads oddly, the Russian version is the source of truth — open an issue.

umbot is a TypeScript framework for building voice skills and chatbots. It gives you a single business logic for all platforms — yet it is just as effective if you work with only one. Supported out of the box: Yandex Alice, Sber Salute (SmartApp), as well as Telegram, VK, MAX and Viber. There is a separate adapter for existing Marusia skills.

Unlike most solutions that require a separate implementation for each platform, umbot abstracts the differences in request and response formats, giving the developer a single, predictable interface. This lets you write the logic once — and run it everywhere.

The framework follows SemVer. Breaking changes are possible only in MAJOR versions.

English: documentation in English (machine-translated from Russian).

---

Why umbot?

No more writing several versions of the same application.
No more digging into the JSON formats of Alice, Sber, Marusia, Telegram, MAX and so on.
One business logic. Any platform.

Key benefits:

• One codebase for any platform. Only want Alice? Easy. Decide to add Sber Salute or Telegram — just add the adapter you need, and the logic stays the same.
• In typical scenarios (up to 1 000 commands), full request processing inside the framework, including finding and running commands, takes less than 30 ms even in the hardest case (fallback); in most cases — a few to tens of milliseconds. Practically the whole budget of voice platforms is left for your business logic: the framework logs a warning when processing takes longer than 2000 ms and an error when it takes longer than 2900 ms; the practical reference point is ~3 seconds (more in "Performance and guarantees").
• The first upload of media files can add 200–1000 ms per file to the response time — so umbot recommends uploading the resources you need in advance with the Preload class.
• Safe regular expression handling with ReDoS protection out of the box
• Built-in state, media caching, buttons, cards — out of the box
• TypeScript, CLI, autocompletion, extensive test coverage
• Extra utilities for navigation and text search that speed up development.

The key idea: umbot is not a "multi-platform add-on" but a base layer that makes development for any platform (even a single one) faster, cleaner and ready to scale.

umbot provides a unified interface for building responses while taking each platform's specifics into account:

• Voice platforms (Alice, Sber Salute, Marusia) — everything a typical skill needs: text and TTS, buttons, cards, sounds, session and user state, authorization. Some Alice directives (location requests, the audio player, analytics events) are not abstracted by the framework yet — you can add them in your own subclass of AlisaAdapter.
• Chatbots (Telegram, VK, Viber, MAX, etc.) — only the necessary and in-demand feature set is supported ( cards, buttons, voice messages). Specific elements such as polls or custom messenger interfaces are excluded, since they have no equivalents on voice platforms and are rarely needed in cross-platform logic.

This approach guarantees that your skill/bot behaves predictably and needs no special workarounds when moving between platforms.

How is umbot different from other solutions?

Most frameworks (for example, telegraf, alice-sdk, etc.) target only one platform. To run an application both in Alice and in Telegram, you have to:

• write two (or more) versions of the logic,
• support different response formats,
• duplicate state, button and media handling
• know the API of every platform.

umbot solves this problem:
one business logic for all platforms,
a single API for buttons, cards, voice and text,
automatic adaptation to each platform's format "under the hood".

This is especially valuable if you already maintain an Alice skill and want to move quickly to Sber Salute, Telegram, MAX or VK — without rewriting or substantially reworking the code.

Even if you develop for a single platform for now, umbot saves you from boilerplate, gives you a single API for state, buttons and media, and, most importantly, does not get in the way when it is time to add new channels.

Who is umbot for?

umbot is not just a wrapper for several platforms. It is an architectural solution for projects where the user initiates the dialog. It is equally valuable for one platform and for a dozen.

You will use umbot if:

• You develop for a single platform (Alice, Sber Salute, Telegram, VK, etc.). You get a clean separation of logic and transport, get rid of code duplication inside the project and lay down an architecture that scales painlessly when a second platform is needed. The tool does not complicate things — it brings order.
• You support several platforms at once. You stop syncing changes by hand. New functionality appears everywhere at once, and supporting different APIs comes down to a single interface.
• You design a system with the future in mind. You do not want to rewrite the core when the business asks to add Telegram, a corporate portal or a voice assistant. umbot makes extension predictable.
• You work in a corporate environment with internal messengers. You unify chatbot development and simplify onboarding and component reuse between teams.
• You value clean code and cannot stand copy-paste. You are tired of moving handlers from project to project or painfully adapting business logic to every new API. umbot lets you write the core once and forget about boilerplate.

---

Supported platforms

Platform	Identifier	What is supported
Yandex Alice	alisa	The skills protocol: text, TTS, buttons, cards, sounds, state, authorization
Sber Salute	smart_app	The SmartApp API protocol: text, speech, buttons, cards, state
Telegram	telegram	The basic set: text, buttons (inline and reply), photos and media groups, voice, callback, inline queries, message events
VK	vk	The basic set: text, keyboard, carousel, voice, callback buttons
MAX	max_app	The basic set: text, inline keyboard, images, audio, callback, the bot_started deep link
Viber	viber	The basic set: text, keyboard, rich media. Since 2024 Viber bots are created only on commercial terms
Marusia	marusia	The skills protocol. VK stopped accepting new skills (20.12.2024) — existing skills only
Your platform	...	Through adapters

For messengers, the "basic set" is what makes sense in shared logic across all platforms. Platform-specific features (polls, payments, message editing, etc.) are not abstracted by the framework, but they are available directly: through controller.api and the platform API clients (TelegramRequest, VkRequest, MaxRequest, ViberRequest from umbot/plugins; each has a universal call(method) method).

Platforms are connected via a webhook, and Telegram, VK and MAX also via long polling: bot.startPolling() instead of bot.start(), and you need neither HTTPS nor a tunnel to check the bot on your local machine. Alice, Marusia, SmartApp and Viber need a webhook (for local checks, a tunnel such as ngrok). Without a network you can check the logic in the console with BotTest. One command enables webhook signature verification for Telegram and MAX: npx umbot webhook <telegram|max> <https-url>, and npx umbot doctor checks tokens, .env and the webhook status.

Need your own platform?
Create an adapter scaffold with npx umbot add platform <Name> — it compiles and passes its own test right away, and the places for the platform API are marked TODO. A DB adapter (add db) and middleware (add middleware) are created the same way.
This lets you integrate umbot into any internal system or corporate messenger, or support any other platform, for example WhatsApp or WeChat.

---

🧩 Ecosystem

Separate npm packages that connect with one line via bot.use(). The core stays lightweight: DBMS drivers and third-party platform APIs are installed only by those who need them.

Package	Purpose
umbot-knex-adapter	Relational databases via Knex.js: PostgreSQL, MySQL/MariaDB, SQLite, MSSQL
umbot-ydb-adapter	YDB (Yandex Database): storage for skills and bots in Yandex Cloud Functions, tables are created automatically
umbot-wechat-adapter	WeChat Official Account (Weixin)

npm install umbot umbot-knex-adapter knex pg
Copy

import { 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' } }));
Copy

Want to write your own adapter? Specifications with contracts and readiness checklists:

• Platform adapter
• Database adapter

---

🚀 Quick start

Install the framework:

npm install umbot
Copy

Create and run a project in five commands:

npx umbot create echo
cd echo
npm i
npm run build
npm start
Copy

Adjust the files to your needs. For example:

// 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);
Copy

// 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 = 'Hi! I repeat after you.';
        } else {
            this.text = `You said: ${this.userCommand}`;
        }
    }
}
Copy

Test the application and publish it if needed.

👉 A detailed getting started guide

Performance

In stress tests on standard hardware (AMD Ryzen 5 5600G, Windows 10), with 1003 commands the framework shows:

• Throughput (realistic scenario) — 68 000 RPS
  (emulating the full cycle: incoming request → normalization → logic → response)
• Sequential throughput (core) — ~80 000 RPS
  (maximum single-thread speed)
• Under a continuous stream (1000 commands, 200 in-flight requests) — 580 000–760 000 RPS, 28–3 000 times more than grammy, telegraf, vk-io, viber-bot, max-bot-api and yandex-dialogs-sdk on the same bench (BENCHMARKS)

Important:

• The tests were run without network calls or database operations, so the numbers show the potential of the framework core.
• In a real project the final RPS is determined by external factors (network, database, application logic).
• On a real server (2 cores / 4 GB RAM) with background load the framework shows 16 000+ RPS — more in Performance and guarantees.

Long-running testing (48 hours) revealed no memory leaks or performance degradation: the average throughput in the sequential scenario stayed at ~67 000 RPS, and memory usage was stable.

📚 Documentation

Detailed documentation is available in the following sections:

• Quick start - a detailed description for getting a project started quickly
• A detailed guide to building applications
• Recipes - ready-made solutions for common tasks
• API Reference - a detailed description of all classes, methods and interfaces
• Supported platforms - a guide to integrating with different platforms
• Configuration and security
• Customizing the HTTP client
• Performance and guarantees
• Testing
• Deployment
• Middleware
• FAQ

Useful links

• 📚 Official documentation
• 📢 Telegram channel
• 💬 Telegram group
• 📦 npm package
• Building the "Never have I ever" skill (in Russian)
• Example projects
• Changelog
• Migrating from umbot 2.x to 3.0

🛠 Developer tools

• CLI commands

Visual editor (Umbot Flow)

Umbot Flow is a visual editor for building bots on the umbot framework. Assemble the logic on a canvas, export the JSON configuration and generate a TypeScript project with the CLI.

The pipeline:

Visual editor → JSON configuration → npx umbot create from-flow → TypeScript project → Your server
Copy

Quick start with the editor:

1. Open the editor in your browser
2. Assemble the bot logic on the canvas
3. Export the JSON configuration → download flow.json
4. Run:

   npx umbot create from-flow flow.json --output ./my-bot
   Copy

5. The finished project is in the my-bot folder

JSON format description — the full specification of all node types, connections and code generation rules.

📝 License

MIT License. See LICENSE for details.

🤝 Support

If you have questions or suggestions:

• 📧 Email: maximco36895@yandex.ru
• 🐛 Issues on GitHub