Evolution api n8n

Evolution API и n8n: Полное руководство по интеграции

Evolution API представляет собой программный интерфейс, который позволяет взаимодействовать с мессенджером WhatsApp через неофициальные методы, обходя официальный Business API. Он функционирует как промежуточный слой, эмулирующий действия реального пользователя в приложении WhatsApp Web. Это позволяет отправлять и получать сообщения, медиафайлы, управлять группами и контактами напрямую через HTTP-запросы. Ключевой особенностью Evolution API является необходимость самостоятельного размещения и обслуживания сервера, а также поддержания активной сессии WhatsApp путем сканирования QR-кода.

n8n — это платформа для автоматизации рабочих процессов с открытым исходным кодом (workflow automation). Она использует визуальный редактор, где пользователи создают «ноды» (узлы), соединенные между собой, для построения сложных цепочек действий без написания кода. n8n поддерживает интеграцию с сотнями сервисов через встроенные и пользовательские ноды, что делает его мощным инструментом для оркестрации бизнес-процессов, сбора данных и автоматизации коммуникаций.

Архитектура и принцип совместной работы Evolution API и n8n

Интеграция Evolution API с n8n строится на модели «клиент-сервер», где n8n выступает в роли клиента, инициирующего запросы к серверу Evolution API. Основной компонент — это пользовательская нода (custom node) для n8n, которая реализует методы Evolution API. Эта нода преобразует данные из рабочего процесса n8n в корректные HTTP-запросы к конкретному экземпляру Evolution API и возвращает ответ обратно в workflow.

Типичный процесс включает следующие шаги:

• Развертывание и настройка сервера Evolution API на собственном хостинге или VPS.
• Создание и аутентификация хотя бы одного инстанса (сессии WhatsApp) в Evolution API, получение ключа API (API Key) и токена доступа (Access Token).
• Установка в n8n пользовательской ноды «Evolution API» (часто через npm).
• Настройка учетных данных Evolution API в параметрах ноды в n8n (URL сервера, ключ API, токен инстанса).
• Построение рабочего процесса в n8n, использующего эту ноду для взаимодействия с WhatsApp.

Ключевые операции, реализуемые через интеграцию

Интеграция позволяет выполнять практически все функции мессенджера. Основные операции можно разделить на несколько категорий.

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

• Текстовые сообщения: Базовая отправка текста с поддержкой форматирования (жирный, курсив, зачеркивание).
• Медиафайлы: Отправка изображений, видео, аудио, документов (PDF, DOCX и др.) с указанием URL файла или загрузкой через multipart/form-data.
• Шаблонные сообщения (рассылки): Использование предварительно одобренных WhatsApp шаблонов для массовых коммуникаций с клиентами.
• Интерактивные сообщения: Отправка кнопок (быстрого ответа и call-to-action), списков, что повышает вовлеченность.
• Сообщения с упоминаниями (mentions): Упоминание контактов в групповых чатах.

Получение и обработка сообщений

Evolution API поддерживает два основных метода получения входящих сообщений: вебхуки (webhooks) и опрос (polling). В контексте n8n наиболее эффективно использование вебхуков.

• Сервер Evolution API настраивается на отправку уведомлений о всех событиях (сообщения, статусы доставки/прочтения, изменения в группах) на указанный URL.
• В n8n создается workflow с триггерной нодой «Webhook», который слушает этот URL.
• При получении данных вебхука, n8n запускает workflow, который может парсить входящее сообщение, проверять его тип, извлекать данные отправителя и текст, а затем запускать дальнейшую логику: сохранение в БД, отправку ответа, создание заявки в CRM.

Управление чатами и контактами

• Получение списка чатов и контактов.
• Обновление информации о профиле (имя, аватар).
• Создание, управление и выход из групп, изменение настроек группы, назначение администраторов.
• Проверка наличия номера телефона в WhatsApp.

Сравнение подходов к интеграции WhatsApp в n8n

Критерий	Evolution API + n8n (Кастомная нода)	Официальный WhatsApp Cloud API + n8n	Сервисы-посредники (Typebot, Wati и др.)
Стоимость	Низкая (затраты только на хостинг сервера Evolution API). Отсутствие платы за исходящие сообщения к пользователям, инициировавшим контакт.	Использование тарифов Meta, оплата за исходящие шаблонные сообщения и сессионные сообщения.	Высокая. Плата по подписке, часто с ограничением на количество контактов или сообщений.
Сложность настройки	Высокая. Требует технических навыков для развертывания сервера, поддержания сессии, установки кастомных нод.	Средняя. Требует создания бизнес-аккаунта в Meta, но интеграция через официальную ноду в n8n стандартизирована.	Низкая. Готовое SaaS-решение с графическим интерфейсом и часто встроенной интеграцией с n8n через API.
Надежность и риски	Риск блокировки номера WhatsApp, так как используется неофициальный API. Зависит от стабильности собственного сервера и поддержки проекта Evolution API.	Максимальная надежность и официальная поддержка от Meta. Низкий риск блокировки при соблюдении правил.	Зависит от надежности провайдера. Риск блокировки ниже, чем у Evolution API, но выше, чем у официального API.
Функциональность	Очень широкая. Практически полный доступ к функциям WhatsApp, включая личные и групповые рассылки без жестких ограничений.	Ограничена политиками Meta. Обязательное использование шаблонов для несанкционированных сообщений, строгие лимиты на частоту отправки.	Ограничена возможностями платформы-посредника. Часто фокусируется на поддержке клиентов и маркетинге.
Контроль данных	Полный. Все данные (номера, сообщения, медиа) проходят через ваш собственный сервер.	Данные обрабатываются на стороне Meta в соответствии с их политикой.	Данные хранятся у третьей стороны (провайдера сервиса).

Пошаговая инструкция по базовой настройке

1. Установка Evolution API: Разверните сервер Evolution API на машине с Docker. Основные шаги: клонирование репозитория, настройка переменных окружения в файле .env (порты, секретные ключи), запуск через docker-compose up.

2. Создание инстанса: После запуска откройте веб-интерфейс панели управления Evolution API (обычно по адресу http://ваш_сервер:8080). Создайте новый инстанс, отсканируйте QR-код с помощью телефона с WhatsApp. После успешной привязки скопируйте API Key и Access Token инстанса.

3. Установка ноды Evolution API в n8n: В директории установки n8n выполните команду npm install n8n-nodes-evolution-api. Перезапустите n8n. Нода «Evolution API» появится в списке доступных нод.

4. Настройка учетных данных в n8n: В интерфейсе n8n перейдите в раздел Settings > Credentials. Создайте новые учетные данные типа «Evolution API». Заполните поля:

• Base URL: http://ваш_сервер_evolution:8080 (или https, если настроен)
• API Key: Значение из панели управления Evolution API.
• Access Token: Токен конкретного инстанса.

5. Создание рабочего процесса: Создайте новый workflow. Добавьте ноду «Evolution API». В ее настройках выберите созданные учетные данные, укажите инстанс, выберите операцию (например, «Send Message»). Заполните обязательные параметры: номер получателя в международном формате, тип сообщения, контент. Протестируйте workflow, нажав «Execute Node».

Практические примеры использования

Пример 1: Автоматический ответ на входящие сообщения

Workflow использует ноду Webhook в качестве триггера. URL этого вебхука регистрируется в настройках инстанса Evolution API (в разделе webhook). При получении нового сообщения Evolution API отправляет POST-запрос на этот URL. Данные запроса содержат тело сообщения, номер отправителя и другую метаинформацию. Далее в workflow нода «Function» или «IF» проверяет текст сообщения. В зависимости от ключевых слов, нода Evolution API отправляет соответствующий ответ: прайс-лист, ссылку на сайт или приветственное сообщение.

Пример 2: Синхронизация заказов с WhatsApp

Workflow запускается по расписанию (нода «Schedule») или вебхуку от системы учета (например, 1C или WooCommerce). Он получает данные о новом заказе: номер телефона клиента, номер заказа, статус. Далее workflow использует ноду «Evolution API» для отправки клиенту уведомления в WhatsApp. Сообщение может быть текстовым («Ваш заказ №1234 собран») или содержать PDF-файл счета в виде документа.

Пример 3: Опросы и сбор отзывов

После отметки о выполнении услуги (триггер из CRM) workflow получает номер клиента и отправляет ему через Evolution API сообщение с интерактивными кнопками: «Оцените услугу от 1 до 5» или «Да/Нет». Ответ пользователя приходит обратно через вебхук. Последующие ноды workflow анализируют нажатие кнопки, записывают результат в базу данных (через ноду «Postgres») и, в случае низкой оценки, создают тикет в системе поддержки.

Проблемы, ограничения и лучшие практики

Технические ограничения:

• Эволюция API не поддерживает официальный протокол бизнес-аккаунтов WhatsApp (отсутствие зеленой галочки).
• Скорость отправки сообщений ограничена возможностями телефона/сервера и внутренними лимитами WhatsApp для пользовательских аккаунтов, что может привести к временной блокировке при слишком частой отправке.
• Требуется поддержание постоянной активности сессии. При перезагрузке сервера или потере связи может потребоваться повторная аутентификация по QR-коду.

Лучшие практики для минимизации рисков:

• Используйте отдельный номер телефона и устройство (симулятор или выделенный телефон) для Evolution API, не предназначенный для личного использования.
• Реализуйте задержки (нода «Wait» в n8n) между отправкой сообщений разным получателям, чтобы имитировать поведение человека.
• Настройка мониторинга состояния инстанса (например, периодические health-check запросы) и автоматические уведомления (в Telegram, email) о необходимости переподключения по QR-коду.
• Всегда получайте явное согласие пользователя на получение сообщений. Избегайте массовой рассылки неподготовленным контактам (спам).
• Регулярно обновляйте сервер Evolution API и кастомную ноду n8n для получения исправлений ошибок и новых функций.

Ответы на часто задаваемые вопросы (FAQ)

Вопрос: В чем главное отличие Evolution API от официального WhatsApp Business API?

Главное отличие — в легальности и модели использования. Официальный API предоставляется Meta для бизнесов, требует верификации, имеет четкую ценовую политику и строгие правила использования сообщений-шаблонов. Evolution API — это неофициальное обратное проектирование клиента WhatsApp, которое использует обычный аккаунт пользователя. Оно дает больше свободы в типах рассылок, но несет риск блокировки номера и не предоставляет официальной поддержки или бизнес-функций (зеленая метка, каталог).

Вопрос: Может ли WhatsApp заблокировать номер при использовании Evolution API с n8n?

Да, такая вероятность существует. WhatsApp активно борется с использованием неофициальных клиентов и автоматизацией. Блокировка может быть временной (на 24 часа, 7 дней) или постоянной. Риск повышается при агрессивном поведении: отправке большого количества идентичных сообщений неконтактам, слишком высокой скорости отправки, жалобам со стороны получателей. Соблюдение лучших практик (задержки, согласие, качественный контент) снижает, но не исключает этот риск полностью.

Вопрос: Можно ли отправлять сообщения в группы через эту связку?

Да, интеграция Evolution API с n8n позволяет отправлять сообщения в группы. Для этого необходимо указать в качестве получателя идентификатор группы (Group ID). Этот ID можно получить через API-метод получения списка чатов. Также доступны операции по созданию групп, добавлению/исключению участников, изменению названия и описания группы.

Вопрос: Как обрабатывать вложения и медиафайлы?

Evolution API поддерживает отправку медиафайлов двумя основными способами. Первый: указание публичного URL файла (параметр `mediaUrl`). Сервер сам загрузит и отправит файл. Второй: прямая загрузка через `multipart/form-data`. В n8n это можно реализовать, подготовив бинарные данные файла в предыдущих нодах (например, «Read Binary File» из FTP или «HTTP Request» для загрузки) и передав их в соответствующее поле ноды Evolution API. Для получения медиафайлов от пользователей Evolution API отправляет в вебхуке ссылку для скачивания файла, которую можно обработать в n8n нодой «HTTP Request».

Вопрос: Какие есть альтернативы кастомной ноде Evolution API для n8n?

Если не хочется устанавливать кастомную ноду, можно использовать универсальный подход:

• Нода «HTTP Request»: Позволяет напрямую вызывать любой endpoint Evolution API, вручную формируя заголовки и тело запроса. Это дает полный контроль, но требует глубокого знания API Evolution и ручного разбора ответов.
• Написание собственной ноды: Для разработчиков есть возможность создать свою специализированную ноду на TypeScript, используя шаблон n8n-node-dev, что обеспечит лучшую интеграцию и удобство для повторного использования.
• Использование промежуточного слоя: Написание небольшого микросервиса (на Node.js, Python), который выступает прокси между стандартными нодами n8n (HTTP Request) и Evolution API, упрощая формат запросов.

Вопрос: Как обеспечить безопасность и конфиденциальность данных в этой схеме?

• Используйте HTTPS для доступа к интерфейсам как Evolution API, так и n8n. Настройте SSL-сертификаты (например, через Let’s Encrypt).
• Размещайте сервер Evolution API в защищенной сети (VPS с firewall), ограничьте доступ к портам панели управления только по доверенным IP-адресам.
• Регулярно обновляйте API Key и Access Token в Evolution API.
• Храните учетные данные в зашифрованном виде в менеджере учетных данных n8n, не прописывайте их явно в workflow.
• Настройте политику хранения и удаления логов как на сервере Evolution API, так и в n8n, особенно если в них содержатся номера телефонов и текст сообщений.