n8n-nodes-telegram-business-mode

Community node for n8n that sends Telegram messages in Business Mode.

Features

• One node: Telegram Business Mode
• Operations:
  • Connection -> Get
  • Message -> Send
  • Message -> Typing (typing indicator via sendChatAction)
• Required business_connection_id for Business Mode calls (Get, Send, Typing)

Credentials

Use existing n8n credential type Telegram API:

• Access Token from @BotFather

Node operations and parameters

Connection -> Get

• Business Connection ID - required business connection identifier

Message -> Send

• Chat ID - target chat
• Business Connection ID - required for Business Mode
• Text - message text
• Additional Fields (optional):
  • Parse Mode (MarkdownV2 or HTML)
  • Entities (JSON array of Telegram MessageEntity)
  • Message Thread ID (forum topics)
  • Direct Messages Topic ID (direct messages topics)

Message -> Typing

• Chat ID — target chat
• Business Connection ID — required for Business Mode
• Additional Fields (optional): Message Thread ID (forum topic; same meaning as for Send). Telegram sendChatAction does not support direct_messages_topic_id.

Successful run returns JSON item { "result": true } (boolean from API wrapped in an object).

API call

The node calls:

POST https://api.telegram.org/bot{token}/getBusinessConnection
POST https://api.telegram.org/bot{token}/sendMessage
POST https://api.telegram.org/bot{token}/sendChatAction

sendMessage body:

• chat_id
• text
• business_connection_id
• optional: parse_mode, entities, message_thread_id, direct_messages_topic_id

sendChatAction (Typing) body:

• chat_id
• action: typing
• business_connection_id
• optional: message_thread_id

Entities example

[
  {
    "type": "bold",
    "offset": 0,
    "length": 5
  }
]

Development

npm install
npm run build

Публикация в npm

Рабочая среда: PowerShell, корень репозитория (cd в каталог пакета).

Один раз перед первой публикацией

1. Аккаунт на npmjs.com, имя пакета в package.json (name) должно быть свободно на реестре (или scoped @scope/name с правами на scope).
2. Войти в npm с этой машины:

npm login

Проверка сессии:

npm whoami

Для CI вместо интерактивного логина используют переменную **NODE_AUTH_TOKEN** (classic token с правом Publish) и .npmrc с токеном для registry.npmjs.org — см. документацию npm.

Обычная выгрузка (patch + public)

Скрипт [scripts/publish.ps1](scripts/publish.ps1) сам проверит npm whoami, при отсутствии сессии запустит npm login, поднимет patch-версию без git-коммита/тега, соберёт пакет и выполнит npm publish --access public:

npm run publish:npm

Другой уровень версии (minor / major)

По умолчанию скрипт делает patch. Для minor или major вызови PowerShell напрямую:

powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1 -Release minor

powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1 -Release major

Допустимые значения -Release: patch, minor, major.

Доступ к пакету на реестре

По умолчанию -Access public. Для приватного пакета (платный npm):

powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1 -Access private

Вручную без скрипта

Если нужен полный контроль:

npm version patch --no-git-tag-version
npm run build
npm publish --access public

После публикации при необходимости вручную закоммить изменённый package.json/package-lock.json и поставь git-тег под версию — скрипт это намеренно не делает (--no-git-tag-version).

AI Agent (как tool)

Нода помечена usableAsTool: true и подключается к AI Agent как инструмент (Tools), если версия n8n это поддерживает. В полях можно использовать выражения с [$fromAI()](https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function/) для подстановки аргументов от модели.

Не обновляется / «The specified package could not be loaded»

1. Обнови пакет до последней версии с npm и перезапусти контейнеры/процесс n8n.
2. Логи основного n8n: docker logs n8n-n8n-1 -f --tail 300 (см. имя контейнера на своём хосте).

dbTime.getTime is not a function

Со стороны пакета это не контролируется: так бывает, когда n8n ждёт дату (Date), а из БД приходит строка (после обновления/миграции). Попробуй обновить n8n до свежего patch-релиза. Временно можно обойти UI: поставить пакет вручную в каталоге custom nodes и перезапустить n8n (как принято в вашем окружении).

Class could not be found. Please check if the class is named correctly.

n8n загружает класс по имени из файла .../TelegramBusinessMode.node.js → ожидается экспорт TelegramBusinessMode (совпадение с export class TelegramBusinessMode).

1. inputs / outputs — 'main' (стабильнее на разных версиях n8n, чем NodeConnectionTypes).
2. Если обновление через UI всё равно падает: в контейнере n8n удали кэш пакета и поставь заново, затем restart:

 docker exec -it n8n-n8n-1 sh -c 'rm -rf /home/node/.n8n/nodes/node_modules/n8n-nodes-telegram-business-mode'

(путь к данным n8n смотри в docker inspect / compose volumes.) Дальше в UI снова Install/Update или npm install в каталоге custom nodes.
3. Ошибка dbTime.getTime — баг/данные n8n, не пакета; обнови образ n8n:latest и перезапусти стек.
4. Кастомные credentials в package.json не регистрируются: в UI используется Telegram API (telegramApi).