Telegram Bot Command Router через n8n: команды, роли и безопасные ответы ¶

Обновлено: 2026-05-30

Проблема: по мере роста Telegram-бота команды, роли, callback-кнопки и API-вызовы превращаются в хаотичный набор IF-веток, который трудно тестировать и безопасно расширять.

Решение: workflow в n8n должен сначала распознать команду, проверить роль пользователя, выбрать короткий action и только потом запускать нужную ветку или внутренний API.

Проблема: почему Telegram-бот без роутера превращается в набор if-ов ¶

Первые команды Telegram-бота обычно выглядят просто: `/start`, `/help`, `/status`. Потом появляются роли, callback-кнопки, админские операции, интеграция с CRM и внутренними API. Если всё это наращивать отдельными IF-нодами, workflow становится хрупким: одна новая команда ломает старую ветку, а служебная ошибка может уйти пользователю в чат.

Command router — это слой, который отделяет распознавание команды от бизнес-логики. Он принимает update, нормализует команду, проверяет пользователя, выбирает action и только затем передает данные дальше. Такой подход нужен для ботов поддержки, кабинетов клиентов, внутренних Telegram-панелей и автоматизации продаж.

Архитектура command router в n8n ¶

Контракт Telegram update ¶

{
  "message": {
    "message_id": 77,
    "chat": {
      "id": -1001234567890,
      "type": "supergroup"
    },
    "from": {
      "id": 501,
      "username": "manager"
    },
    "text": "/status order_1042"
  },
  "allowed_admins": [
    501,
    777
  ],
  "public_commands": [
    "/start",
    "/help",
    "/status"
  ]
}

В production список ролей лучше хранить не в самом workflow, а в таблице, Redis или CRM. Так можно менять права без деплоя n8n и вести журнал, кто запускал чувствительные команды.

Code Node для парсинга команд и ролей ¶

const update = $json.message ? $json : ($json.body ?? $json);
const msg = update.message ?? update.callback_query?.message ?? {};
const text = String(update.callback_query?.data ?? msg.text ?? '').trim();
const userId = update.callback_query?.from?.id ?? msg.from?.id;
const allowedAdmins = new Set(($json.allowed_admins ?? []).map(String));
const [commandRaw, ...args] = text.split(/\s+/);
const command = commandRaw.startsWith('/') ? commandRaw.split('@')[0].toLowerCase() : 'text';
const isAdmin = allowedAdmins.has(String(userId));

const routes = {
  '/start': { action: 'send_public_help', requires_admin: false },
  '/help': { action: 'send_public_help', requires_admin: false },
  '/status': { action: 'check_order_status', requires_admin: false },
  '/reload': { action: 'reload_cache', requires_admin: true },
  '/broadcast': { action: 'broadcast_message', requires_admin: true }
};

const route = routes[command] ?? { action: 'unknown_command', requires_admin: false };
if (route.requires_admin && !isAdmin) {
  return [{ json: { action: 'deny', reason: 'admin_required', command, user_id: userId } }];
}

return [{ json: { action: route.action, command, args, chat_id: msg.chat?.id, user_id: userId, is_admin: isAdmin } }];

Готовый workflow JSON ¶

Скачать готовый workflow JSON Скачать тестовый payload

{
  "name": "Nodbot - Telegram bot command router with roles",
  "nodes": [
    {
      "name": "Telegram Trigger",
      "type": "n8n-nodes-base.telegramTrigger",
      "purpose": "Получить message или callback_query"
    },
    {
      "name": "Route command and role",
      "type": "n8n-nodes-base.code",
      "purpose": "Распознать команду, аргументы и роль"
    },
    {
      "name": "Execute route",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Вызвать нужный API или внутренний workflow"
    },
    {
      "name": "Format safe reply",
      "type": "n8n-nodes-base.code",
      "purpose": "Собрать ответ без служебных данных"
    },
    {
      "name": "Send Telegram response",
      "type": "n8n-nodes-base.telegram",
      "purpose": "Ответить в чат или пользователю"
    }
  ],
  "connections": "Telegram Trigger → Route command → Execute route → Format reply → Send response"
}

Пошаговая настройка команд Telegram-бота ¶

1. Подключите Telegram Trigger и проверьте получение message и callback_query.
2. Опишите словарь команд: публичные, пользовательские и админские.
3. Добавьте источник ролей: список admin user_id, CRM-группа или internal API.
4. Для каждой команды верните короткий `action`, а не выполняйте всю бизнес-логику в router.
5. Добавьте fallback для неизвестных команд и безопасный текст ошибки.

Тесты перед production ¶

curl -X POST "https://YOUR-N8N-DOMAIN/webhook/telegram-bot-command-router" \
  -H "Content-Type: application/json" \
  --data @telegram-bot-command-router-payload.json

Проверьте `/start`, `/help`, `/status order_id`, неизвестную команду, админскую команду от обычного пользователя, callback query и слишком длинный ответ. Бот должен отвечать предсказуемо и не раскрывать внутренние детали.

Production-риски command router ¶

• Команда с @username не распознана. В группах Telegram команда может приходить как `/status@botname`.
• Права зашиты в код. При смене сотрудника доступ останется в workflow.
• Stack trace в чат. Пользователь не должен видеть ошибку API или SQL.
• Нет rate limit. Один пользователь может заспамить тяжелую команду.
• Смешаны router и бизнес-логика. Router должен выбирать ветку, а не превращаться в монолит.

Полезные ссылки и смежные workflow ¶

См. также Telegram AI-бот с approval, Telegram alert для ошибок, rate limits и retries. Официальные документы: Telegram Bot API, n8n Telegram Trigger и n8n Telegram message operations.

Критерии готовности ¶

1. Все команды описаны в едином словаре.
2. Админские ветки требуют проверки роли до API-вызова.
3. Неизвестная команда получает полезный fallback.
4. Ответы экранируются под выбранный parse_mode.
5. Есть лог команд, user_id, action и результата выполнения.