n8n-nodes-appmindmax

Read this in English

Community-нода n8n для мессенджера MAX (dev.max.ru), построенная на официальном Bot API: https://dev.max.ru/docs-api

Пакет содержит два узла:

• APPMINDMAX — обычная нода-действие для вызова методов API (отправка/редактирование/удаление сообщений, работа с чатами и участниками, управление командами бота, ответы на callback от инлайн-кнопок).
• APPMINDMAX Trigger — триггер, который сам регистрирует Webhook-подписку (POST /subscriptions) при активации workflow и снимает её (DELETE /subscriptions) при деактивации, а также принимает входящие события. По умолчанию подписан на: User Joined Chat, User Left Chat, Bot Added to Chat, Bot Removed From Chat, Button Clicked — остальные типы событий доступны в списке Update Types.

Установка

Пакет не опубликован в публичном npm-реестре, поэтому встроенная кнопка Settings → Community Nodes → Install в n8n напрямую не сработает. Вместо этого нужно собрать кастомный Docker-образ n8n, который компилирует ноду и подключает её через N8N_CUSTOM_EXTENSIONS.

Docker (рекомендуемый способ)

В репозитории лежит многостадийный Dockerfile: сборочная стадия клонирует этот репозиторий и компилирует его через pnpm, финальная стадия — обычный образ docker.n8n.io/n8nio/n8n, в который копируются только собранный dist/ и package.json (без node_modules — поэтому добавка к размеру образа получается в пределах пары сотен КБ, а не ~100 МБ, как было бы при переносе всех dev-зависимостей).

Если репозиторий публичный, можно указать docker-compose.yml сразу на него как на build-контекст — исходники на сервере вообще не нужны:

services:
  n8n:
    build:
      context: https://github.com/alexbruin/appmindmax.git
      # args:
      #   APPMINDMAX_REF: v0.1.0   # зафиксировать тег/коммит вместо `main`
    environment:
      - N8N_CUSTOM_EXTENSIONS=/home/node/custom-nodes/n8n-nodes-appmindmax
    # ...остальные volumes/ports/env оставьте как есть

docker compose build --no-cache
docker compose up -d --force-recreate

Если репозиторий приватный, git clone/git-контекст Docker потребуют учётных данных на сервере (deploy key или PAT). Самый простой вариант без этой настройки — синхронизировать исходники на сервер самостоятельно и указать build-контекст на локальную копию:

rsync -avz --exclude node_modules --exclude dist ./ user@server:/opt/n8n-nodes-appmindmax/

services:
  n8n:
    build:
      context: /opt/n8n-nodes-appmindmax

Локальная сборка для разработки

npm install
npm run build

Чтобы проверить на локальном n8n:

npm link
cd ~/.n8n/custom   # или каталог, указанный в N8N_CUSTOM_EXTENSIONS
npm link n8n-nodes-appmindmax

Credentials

Тип credential APPMINDMAX API:

• Access Token — токен вашего бота из MAX: «Чат-боты» → ваш бот → «Расширенные настройки» → «Настроить».
• Base URL — по умолчанию https://platform-api2.max.ru, менять не нужно.

Особенности API MAX, учтённые в ноде

• chat_id нельзя получить напрямую — он приходит только через событие (bot_added, bot_started и т.д.) в Webhook/Long Polling. Используйте APPMINDMAX Trigger, чтобы получить chat_id из входящих событий, и сохраните его (например, в БД через отдельный workflow) для дальнейшего использования в ноде APPMINDMAX.
• Webhook и Long Polling нельзя использовать одновременно — этот пакет реализует только Webhook (способ, рекомендованный MAX для продакшена).
• Загрузка медиавложений (image/video/audio/file) — двухшаговый процесс (POST /uploads → загрузка multipart/form-data) — нода делает это автоматически, когда вы указываете Binary Property в операции Message → Send/Update.
• Rate limit: не более 2 сообщений/ответов в секунду на один диалог/чат/канал — учитывайте это при проектировании workflow (например, через Wait/Split in Batches).

Поддерживаемые ресурсы и операции

| Ресурс | Операции | |---|---| | Message | Send, Update, Delete, Get, Get Many | | Chat | Get, Update, Leave, Get My Membership, Send Action, Get/Pin/Unpin Message, Get/Add/Remove Admin | | Member | Get Many, Add, Remove | | Bot | Get, Update Commands | | Answer (Callback) | Send |

Лицензия

MIT