n8n-nodes-max

Нода для интеграции мессенджера Max с платформой автоматизации n8n.

Установка

Для self-hosted n8n

1. Установите пакет через npm в директории n8n:

npm install n8n-nodes-max

2. Перезапустите n8n для загрузки новой ноды

Для n8n Cloud

1. Откройте настройки вашего workspace
2. Перейдите в раздел "Community nodes"
3. Нажмите "Install a community node"
4. Введите n8n-nodes-max и нажмите "Install"

Альтернативный способ (переменная окружения)

Добавьте пакет в переменную окружения:

export N8N_CUSTOM_EXTENSIONS=n8n-nodes-max

Полезные ссылки:

• Официальная документация по установке community nodes
• Руководство по self-hosted установке

Для разработки

• После npm install автоматически устанавливается Husky pre-commit hook.
• Перед коммитом запускается Prettier для staged исходников (*.{ts,js,mjs,cjs,json,md,yml,yaml}).

Релиз

1. Подготовьте изменения и закоммитьте их обычным git-коммитом.
2. Выберите semver-тип релиза и создайте commit+tag командой npm version patch, npm version minor или npm version major.
3. Запушьте ветку и теги командой git push origin master --follow-tags.
4. GitHub Actions опубликует пакет в npm по пушу тега v*.*.*.

Автопубликация использует npm Trusted Publisher через GitHub Actions OIDC, без NPM_TOKEN. В настройках пакета npm trusted publisher должен указывать:

• Organization or user: pfrankov
• Repository: n8n-nodes-max
• Workflow filename: publish-npm.yml
• Allowed actions: npm publish

Возможности

Сообщения

• Отправка текстовых сообщений с форматированием
• Автоматический fallback в plain text при ошибке Max API о неподдерживаемом Markdown
• Редактирование и удаление сообщений
• Для Edit Message нода отправляет message_id в query-параметре запроса PUT /messages?message_id=...
• В Edit Message опция Clear Attachments удаляет текущие вложения сообщения, включая inline-клавиатуру
• Отправка файлов (изображения, видео, аудио, документы)
• Для вложений в Send Message доступны три источника: Binary Data, URL и готовый Token MAX
• В Send Message текст не обязателен, если отправляются вложения
• В Send Message через Additional Fields → Reply to Message ID можно ответить на исходное сообщение, а через Forward Message ID — переслать оригинал
• Нода не ограничивает вложения по расширению файла: формат проверяется на стороне Max API
• Payload вложения зависит от типа файла: для image используются поля из JSON-ответа upload-шага (token/photos/url), для file используется token из upload-ответа, а для video/audio нода также поддерживает токен из POST /uploads, если upload endpoint возвращает retval
• Если у вас уже есть payload.token из Max API, выберите Attachment Source = Token: нода отправит вложение без повторного скачивания и upload
• Автоматический ретрай отправки с медиа-вложением при временной ошибке attachment.not.ready
• Явная валидация ID получателя: 0 отклоняется с подсказкой по полям из Max Trigger
• Интерактивные клавиатуры с кнопками

Чаты

• Получение информации о чате
• Выход из групповых чатов

Триггер

• Получение событий в реальном времени:
  • Новые сообщения в личных диалогах (message_created) и чатах (message_chat_created)
  • Нажатия на кнопки
  • События чатов
• Поддержка webhook URL с интернационализированными доменами (IDN/Punycode) для корректной TLS-валидации

Настройка

1. Создайте бота через @PrimeBot в Max мессенджере
2. Получите токен доступа
3. Добавьте токен в настройки ноды в n8n

Быстрый старт

Отправка сообщения

1. Добавьте ноду Max в workflow
2. Выберите операцию "Send Message"
3. Укажите ID получателя; при необходимости добавьте текст
4. Чтобы отправить только файл/медиа, оставьте Message Text пустым и добавьте вложение в Additional Fields → Attachments
5. Чтобы переиспользовать уже загруженный файл, выберите Additional Fields → Attachments → Attachment Source = Token и вставьте File Token
6. Запустите workflow

Пересылка входящего сообщения

1. Добавьте Max Trigger и подпишитесь на message_created или message_chat_created
2. Добавьте Max → Send Message
3. В Send To выберите Chat и укажите ID группы поддержки
4. Оставьте Message Text пустым
5. В Additional Fields добавьте Forward Message ID и передайте ={{$json.event_context.message_id}}
6. Оставьте остальные additional fields по необходимости, например Notify

Удаление inline-кнопок при редактировании

1. Выберите операцию Edit Message
2. Укажите Message ID и новый текст
3. Включите Clear Attachments, чтобы Max API получил attachments: [] и удалил текущую inline-клавиатуру

Получение сообщений

1. Добавьте ноду Max Trigger
2. Настройте webhook
3. Выберите типы событий для отслеживания

Ресурсы

• Документация Max Bot API
• GitHub репозиторий

Лицензия

MIT