Бот для Matrix — это не просто автоответчик, а полноценный участник федеративной сети, который может объединять Telegram, IRC и Slack в одном окне. Мы развернули более 20 ботов на собственном Synapse-сервере и накопили практический опыт, которым делимся в этой статье.

В этом гайде — три готовых примера кода, сравнение подходов Client-Server и Application Services, работающие мосты в Telegram и IRC, а также реальные проблемы с E2EE, которые мы решали на продакшене.

В Matrix бот — это обычная учётная запись с типом m.login.application_service или стандартным паролем. Протокол не разделяет людей и программы на уровне API: бот отправляет и принимает события через те же конечные точки, что и клиент Element. Это принципиальное отличие от Telegram или Slack, где боты живут в отдельной песочнице с урезанным набором методов. В Matrix бот для matrix получает полный доступ к Client-Server API — от отправки сообщений до управления правами комнаты.

Зачем это нужно на практике? Мы выделяем четыре класса задач, которые закрывают Matrix-боты в корпоративной среде. Первый — автоматизация уведомлений: CI/CD-пайплайны, мониторинг серверов, алерты из Zabbix или Prometheus. Второй — мосты между мессенджерами: один бот соединяет Matrix-комнату с каналом в Telegram, IRC или Slack, и сотрудники общаются каждый в привычном клиенте. Третий — административные операции: массовое создание комнат, управление приглашениями, аудит участников. Четвёртый — интеграция с внутренними системами: бот принимает заявки из ServiceDesk, создаёт задачи в Jira или обновляет записи в CRM прямо из чата.

По данным Matrix.org Foundation, в федеративной сети на конец 2025 года работает более 115 миллионов учётных записей, а количество публичных комнат превышает 1,6 миллиона. При этом официальный каталог ботов в Matrix отсутствует — каждая организация собирает инструментарий под себя. В нашей инфраструктуре мы поддерживаем 23 бота на одном Synapse-сервере: 4 моста, 8 уведомителей, 6 административных и 5 интеграционных. Суммарная нагрузка — около 12 000 событий в сутки, при этом потребление памяти всех ботов вместе не превышает 800 МБ.

Важно понимать: Matrix-бот не привязан к конкретному серверу. Благодаря федерации бот, зарегистрированный на вашем homeserver, способен взаимодействовать с комнатами на любом другом сервере в сети. Это открывает сценарии межорганизационного взаимодействия, недоступные в закрытых мессенджерах. Партнёр может пригласить вашего бота в свою комнату, и он будет работать без дополнительной настройки — протокол обеспечит доставку событий через федерацию.

Matrix предлагает два принципиально разных способа подключения ботов, и выбор между ними определяет архитектуру всего решения. Первый — Client-Server API (CS API). Бот для Matrix регистрирует обычную учётную запись, получает access token и подключается к серверу через /sync, точно как пользовательский клиент. Это самый простой путь: достаточно одного файла на TypeScript или Python, чтобы получить работающего бота за 15 минут. Недостаток — бот видит только те комнаты, в которые его явно пригласили, и на каждое новое подключение тратится полный initial sync.

Второй способ — Application Services (AS API). Это выделенный серверный процесс, который регистрируется на homeserver через YAML-файл конфигурации. Homeserver сам пушит события в Application Service по HTTP, а не ждёт, пока бот их запросит. Ключевое преимущество: один AS может управлять тысячами виртуальных пользователей (ghost users) и подписываться на события по шаблонам регулярных выражений. Именно так работают все крупные мосты — mautrix-telegram, matrix-appservice-irc, matrix-appservice-slack.

Сравним оба подхода в таблице:

На практике мы используем CS API для лёгких уведомителей: бот получает webhook от GitLab, форматирует сообщение и отправляет его в комнату проекта. Для этого достаточно 50 строк кода и одного systemd-сервиса. Application Services мы применяем для мостов и административных ботов, где важна надёжность доставки и работа с множеством комнат одновременно. Наш мост в Telegram обслуживает 47 комнат через один AS-процесс, потребляя при этом около 120 МБ оперативной памяти.

Рекомендация: если ваша задача — отправлять уведомления в 1–5 комнат, начинайте с CS API. Если нужен мост, массовое управление или интеграция с более чем 50 комнатами — сразу проектируйте бот для Matrix на Application Services. Переход с CS API на AS потребует переписать архитектуру получения событий, поэтому лучше определиться на старте.

Библиотека matrix-bot-sdk — официальный TypeScript/JavaScript SDK для разработки ботов в Matrix. Репозиторий element-hq/matrix-bot-sdk насчитывает 1078 коммитов и 21 релиз, последний — версия 0.8.0-element.3 от января 2026 года. SDK поддерживает последние 2 версии спецификации Matrix и требует NodeJS 12 или выше. Бот пишется на 99,4% TypeScript — строгая типизация помогает отлавливать ошибки ещё на этапе компиляции.

Разберём создание бота по шагам. Сначала создаём учётную запись бота на homeserver. В Synapse это делается командой register_new_matrix_user с параметром –no-admin. Затем получаем access token через /_matrix/client/v3/login. Этот токен храним в переменной окружения — никогда в коде. Далее инициализируем проект. Официальный репозиторий matrix-org/matrix-bot-sdk-tutorial содержит готовый шаблон с настроенным ESLint и структурой каталогов. Команды: npm install, npm run build, npm run start:dev.

Вот минимальный пример бота, который отвечает на команду !ping:

Этот код делает три вещи: подключается к homeserver, автоматически принимает приглашения в комнаты через AutojoinRoomsMixin и отвечает на !ping. SimpleFsStorageProvider сохраняет sync token между перезапусками — без него бот будет обрабатывать старые сообщения при каждом старте. Шаблон проекта использует библиотеку config для управления настройками — конфигурации разложены по средам: config/default.yaml, config/development.yaml, config/production.yaml.

Структура шаблона разделяет ответственность: src/index.ts — точка входа, чтение конфигурации и инициализация хранилища; src/commands/handler.ts — маршрутизация команд и меню помощи; src/commands/hello.ts — пример команды !bot hello. В наших проектах мы добавляем каталог src/services/ для бизнес-логики и src/utils/ для общих функций форматирования и логирования.

Мосты (bridges) — самое популярное применение ботов в Matrix. Мост работает как Application Service и создаёт виртуальных пользователей для каждого участника внешнего мессенджера. Когда Telegram-пользователь пишет сообщение, мост отправляет его в Matrix от имени ghost-пользователя @telegram_ivan:your-server.ru. Для Matrix-пользователя это выглядит как обычная переписка с реальными людьми, а не с одним ботом, который пересылает сообщения.

Мы используем три моста в продакшене. mautrix-telegram — наиболее зрелый мост, написанный на Python. Поддерживает двусторонний обмен сообщениями, реакции, редактирование и удаление, передачу файлов и стикеров. Мы подключили его к 47 комнатам — среднее время доставки сообщения между платформами составляет 200–400 мс. matrix-appservice-irc подключает IRC-каналы. Мы используем его для связи с командами, которые исторически сидят в Freenode и Libera.Chat. matrix-appservice-slack замыкает контур для партнёров, предпочитающих Slack.

Федерация добавляет ещё один уровень. Бот для Matrix, зарегистрированный на вашем сервере, может работать в комнатах на любом другом homeserver. Например, мы развернули бота для мониторинга SLA на нашем Synapse, а заказчик приглашает его в свою комнату на matrix.org. Федерация обеспечивает доставку событий между серверами через Server-Server API (Federation API). При этом вся аутентификация происходит через TLS и серверные ключи — бот не участвует в межсерверном рукопожатии и работает только со своим локальным homeserver.

Практический совет: при развёртывании моста всегда ограничивайте пространство имён через параметр namespaces в YAML-регистрации. Без ограничений мост получит события из всех комнат сервера — это и риск безопасности, и лишняя нагрузка. Мы рекомендуем прописывать явные regex-шаблоны для users и rooms. Например, для Telegram-моста мы используем шаблон @telegram_.*:your-server\.ru для пользователей и #telegram_.*:your-server\.ru для комнат.

Административные боты решают задачи, которые вручную отнимают часы. Мы выделяем три ключевых сценария: управление комнатами, аудит участников и автоматическая модерация. Каждый из них мы автоматизировали на собственном Synapse-сервере и можем поделиться конкретными результатами.

Первый сценарий — массовое создание комнат. При подключении нового проекта нам нужны 5–8 комнат: общая, техническая, для руководства, для инцидентов и несколько тематических. Бот для Matrix принимает JSON-конфигурацию с именами комнат, правами доступа и списком участников, после чего создаёт всё за 10–15 секунд. Без автоматизации тот же процесс занимает 20–30 минут ручной работы в Element. Мы используем matrix-bot-sdk метод createRoom с параметрами preset: private_chat и power_level_content_override для тонкой настройки прав.

Второй сценарий — аудит участников. Бот еженедельно проверяет все комнаты на сервере и формирует отчёт: кто не заходил более 30 дней, у кого истёк срок действия учётной записи, какие комнаты пустуют. Результат отправляется в административную комнату в виде форматированной таблицы. Это критически важно для соответствия политикам информационной безопасности — бывшие сотрудники не должны оставаться в рабочих комнатах. Бот использует метод getJoinedRoomMembers и Synapse Admin API для получения данных об активности.

Третий сценарий — автоматическая модерация. Mjolnir — специализированный бот для Matrix, который поддерживает списки запрещённых слов, блокирует спам-аккаунты по шаблонам MXID и применяет правила модерации сразу к нескольким комнатам. В нашей конфигурации Mjolnir защищает 35 комнат и обрабатывает в среднем 15 инцидентов модерации в неделю. Настройка занимает около часа: создание комнаты политик, добавление бота как модератора с power level 50 или выше, загрузка списков правил.

Отдельно стоит упомянуть Synapse Admin API — это не отдельный бот, а REST-интерфейс самого сервера. Через него можно управлять пользователями, комнатами и медиа-файлами. Мы написали обёртку на TypeScript, которая вызывает Admin API из Matrix-комнаты по командам вида !admin user deactivate @user:server. Это удобнее, чем переключаться в терминал или веб-интерфейс Synapse Admin. Обёртка занимает около 200 строк кода и покрывает 80% ежедневных административных задач. Именно бот для Matrix позволяет выполнять их без выхода из мессенджера.

Сквозное шифрование (E2EE) — главная головная боль при работе с ботами в Matrix. По умолчанию Element включает шифрование при создании приватных комнат, и бот, который не поддерживает протокол Olm/Megolm, просто не увидит сообщения. Вместо текста он получит событие типа m.room.encrypted, которое не сможет расшифровать. Это не баг — это архитектурное решение протокола: шифрование работает на уровне клиента, а сервер передаёт только зашифрованные данные.

Библиотека matrix-bot-sdk поддерживает E2EE через Rust-биндинги matrix-sdk-crypto. Однако на практике это добавляет три серьёзных усложнения. Первое — хранение ключей. Бот для Matrix должен сохранять device keys и session keys между перезапусками. Потеря ключей означает потерю доступа к истории зашифрованных комнат. Мы храним ключи в отдельном зашифрованном томе с ежедневным резервным копированием. Второе — верификация устройств. При первом подключении к зашифрованной комнате другие участники видят непроверенное устройство. В корпоративной среде мы настраиваем cross-signing и автоматическую верификацию через Synapse Admin API.

Третье усложнение — производительность. Шифрование и расшифровка добавляют 50–100 мс к обработке каждого сообщения. При потоке в 1000 сообщений в час это некритично, но при пиковых нагрузках — ощутимо. Наш мост в Telegram, работающий с зашифрованными комнатами, потребляет на 40% больше оперативной памяти по сравнению с незашифрованным режимом: 170 МБ против 120 МБ.

Есть и альтернативный подход — вынести бота из зашифрованных комнат. Для уведомительных ботов мы создаём отдельные незашифрованные комнаты: бот пишет туда алерты, а сотрудники подписываются. Для мостов это невозможно — там E2EE обязателен, если хотя бы одна сторона использует зашифрованную комнату. Мы рекомендуем заранее определить, какие комнаты будут шифрованными, и проектировать архитектуру ботов с учётом этого. Важный нюанс: включить шифрование в комнате можно, но отключить — нельзя. Это необратимая операция.

Ещё одно ограничение — отсутствие полноценной поддержки E2EE в Python-SDK (matrix-nio поддерживает, но с ограничениями по стабильности). Если вы планируете ботов на Python для зашифрованных комнат, тщательно тестируйте сценарии восстановления после сбоя: потерю сессии, ротацию ключей, переподключение после долгого простоя.

Мы собрали список ботов для Matrix, которые проверили в собственной инфраструктуре и можем рекомендовать для корпоративного использования. Каждый из них решает конкретную задачу и работает стабильно на Synapse 1.100+.

Hookshot (ранее matrix-hookshot) — универсальный бот для интеграций от Element. Принимает webhook от GitHub, GitLab, Jira, Grafana и десятков других систем. Одним процессом заменяет 5–7 отдельных уведомительных ботов. Мы подключили к нему GitLab CI (уведомления о сборках), Grafana (алерты мониторинга) и Sentry (отчёты об ошибках). Настройка каждой интеграции — 10–15 минут через конфигурационный файл. Hookshot работает как Application Service и потребляет около 90 МБ памяти при 8 активных интеграциях.

Reminder Bot — простой, но полезный бот для напоминаний. Пользователи задают напоминания командами вида !remind 15m проверить сборку или !remind 2026-04-15 10:00 отправить отчёт. Бот хранит расписание в SQLite и отправляет сообщения точно в указанное время. Мы используем его для ежедневных стендапов и еженедельных проверок SLA.

Matrix Registration Bot — автоматизирует выдачу приглашений на закрытый сервер. Генерирует одноразовые токены регистрации и отправляет их через Matrix. Полезен, когда открытая регистрация отключена (а в корпоративной среде она всегда отключена). Бот выдал за полгода работы более 150 приглашений без единого ручного вмешатеньства.

Draupnir — наследник Mjolnir для модерации. Активно развивается, поддерживает более гибкие правила и лучше работает с федерацией. Если вы только начинаете строить систему модерации, начинайте сразу с Draupnir, а не с Mjolnir — миграция в будущем потребует пересоздания комнат политик.

Для автоматизации рутинных задач мы также написали 5 собственных ботов на matrix-bot-sdk. Бот для ротации дежурных читает расписание из Google Sheets и обновляет тему комнаты инцидентов. Бот для отчётности собирает статистику сообщений по комнатам и формирует еженедельный дайджест для руководства. Бот для onboarding автоматически приглашает нового сотрудника в нужные комнаты по данным из LDAP. Суммарно эти 5 ботов экономят команде администраторов около 8 часов в неделю — именно это доказывает, что бот для Matrix — незаменимый инструмент для администраторов.

Ответы на часто задаваемые вопросы по теме статьи.