Без boilerplate: клонируйте бота, который уже работает
Этот гайд использует open-source бота из репозитория Whapi.Cloud на GitHub. В нём уже есть отправка и приём, медиа, контакты, товары и группы. Дальше — как это запустить.
Скрипт данного чат-бота включает в себя основные функции, которые часто используются малым и средним бизнесом и покрывает большинство задач:
- Отправка обычного сообщения;
- Отправка медиа: изображение / файл / видео;
- Отправка контакта (визитная карточка vCard);
- Отправка товара;
- Создание WhatsApp группы;
- Отправка приглашения в группу;
- Отправка сообщения в WhatsApp группу;
- Получение и обработка входящих сообщений;
- Ответ на неизвестную команду (для реализации меню, инструкций или приветственного сообщения).
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
После клонирования зайдите в папку проекта:
cd nodejs-whatsapp-chatbot
Установите пакеты из
package.json:
npm install
Так скачиваются зависимости, без которых чат-бот не стартует.
Структура проекта
- /files — примеры медиа, которые бот может отправить (картинка, PDF, видео, vCard). Меняйте, когда понадобится.
- config.js —
token,botUrl,portи опциональные IDgroup/product. - index.js — регистрирует вебхук, слушает
/hook/messagesи мапит цифры 1–9 на действия.
Подключите свой номер WhatsApp
Whapi.Cloud — HTTP-шлюз для WhatsApp, независимый от Meta*. Берёте любой свой номер, сканируете QR в панели и получаете Bearer-токен. Без проверки Meta* Business и без лимитов шаблонов или окна переписки Cloud API.
Чтобы бот работал, телефон не обязан оставаться онлайн. Привяжите номер один раз в панели и запускайте бота на любом сервере. Если нужна помощь — чат поддержки на сайте.
Отсканируйте QR-код в аккаунте
Регистрация. Первый шаг — зарегистрироваться на сайте Whapi.Cloud и создать аккаунт. Это бесплатно, карта не нужна.
Сразу после регистрации появится тестовый канал с уменьшенной квотой. Подождите, пока он поднимется (обычно около минуты). Нужно привязать телефон: с этого номера будут уходить сообщения. Плюс в том, что через пару минут вы уже в работе.
Чтобы привязать телефон, откройте QR по клику на тестовый канал в аккаунте. В WhatsApp на телефоне: Настройки -> Связанные устройства -> Привязка устройства -> Сканировать QR-код.
Экраны имени канала и вебхука в мастере можно пропустить: бот сам пропишет вебхук при старте.
Теперь у вас есть API-токен — он нужен для тестов и запросов к эндпоинтам. Сохраните его, пригодится не раз. В карточке канала скопируйте токен и вставьте в
config.js как token. Запросы к https://gate.whapi.cloud идут с Bearer.
Перед запуском бота
- Токен канала вставлен в
config.js. - Второй телефон для теста: бот игнорирует сообщения с подключённого номера.
- Публичный HTTPS-URL. Локально — ngrok; в продакшене — любой хост с HTTPS.
Дайте боту публичный HTTPS-URL
Вебхук — это сообщение, которое Whapi.Cloud шлёт вашему боту каждый раз, когда в подключённом аккаунте WhatsApp что-то происходит: новый текст, смена статуса, приглашение в группу.
Вместо того чтобы снова и снова спрашивать «есть новые сообщения?», скрипт получает POST с событием в момент, когда оно случилось.
Пример: контакт A пишет «привет» -> Whapi.Cloud делает POST с JSON на
/hook/messages вашего сервера -> бот смотрит команду и отвечает. URL в панель не вставляют; бот регистрирует его из config.js при старте.Whapi.Cloud доставляет входящие сообщения POST-запросом на ваш публичный HTTPS-URL. Эту ссылку не вставляют в панели. Пропишите её в
config.js как botUrl; при старте репозиторий регистрирует её через API настроек канала.Локальный туннель через ngrok
Порт
port по умолчанию в config.js — 80 (443 не используйте). Скачайте ngrok и выполните ngrok http 80 — или тот порт, который указали в config.js.Скопируйте forwarding-URL
https://. Задайте botUrl как этот хост плюс /hook, например botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook".
Оставьте суффикс
/hook. Сервер слушает POST на /hook/messages; botUrl — это префикс, который попадает в настройки канала.При
node index.js бот отправляет PATCH /settings с этим URL и событием messages. Сообщения WhatsApp приходят в ваш процесс. Поля вебхука в панели можно не трогать — разве что хотите посмотреть, что зарегистрировалось.Что нужно продакшену
Хост должен быть доступен из интернета по HTTPS, а процесс Node — продолжать работать, чтобы принимать POST. Если меняете
botUrl, перезапустите бота, чтобы вебхук зарегистрировался заново.Запуск бота
Проверьте
token и botUrl в config.js и из корня проекта выполните node index.js. Должен появиться лог listening. С другого телефона отправьте любой текст на подключённый номер. Бот ответит нумерованным меню.Меню команд
- Простое текстовое сообщение
- Отправить изображение
- Отправить документ
- Отправить видео
- Отправить контакт
- Отправить товар
- Создать группу
- Простой текст в группу
- Получить id трёх ваших групп
Отправьте только цифру, например 1. Всё остальное снова вернёт этот список.
Команды 6 и 8 используют
product и group в config.js. На первом тесте их можно пропустить. Когда понадобятся, ID берите через GET /groups и GET /business/products.Если что-то не работает
Бот не отвечает
Пишите с другого телефона: скрипт пропускает
from_me. Проверьте токен, что botUrl заканчивается на /hook, что ngrok (или хост) ещё жив и что процесс вывел сообщение listening.Бот уходит в цикл сообщений
Оставьте
if (message.from_me) continue. Без этой проверки бот отвечает сам себе и не останавливается.В одних чатах работает, в других нет
Sandbox ограничивает активные переписки (сейчас 5 в месяц). Шестой чат не получит ответ, пока не смените тариф или не сбросится квота.
Отправка сообщений WhatsApp из Node.js
Клонированный бот уже умеет отправлять, принимать, медиа, контакты, товары, группы и остальное. Сниппеты ниже — тот же HTTP-паттерн внутри:
fetch на https://gate.whapi.cloud с Bearer-токеном.Отправить текстовое сообщение
Отправьте обычный текст в чат или группу:
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
body: 'Hello from the cloned bot'
})
});
const data = await response.json();
console.log(data);
Отправить документ
Отправьте документ по публичному URL или в base64:
const response = await fetch('https://gate.whapi.cloud/messages/document', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
media: 'https://example.com/file.pdf',
caption: 'Document from the bot'
})
});
const data = await response.json();
console.log(data);
Полный список типов и payload — в справочнике API.
Работа с группами WhatsApp
Бот может получить список групп, в которых вы состоите, и реагировать на сообщения в группе. Эти примеры используют тот же Bearer и эндпоинт
/groups.Список ваших групп
Получите группы, видимые подключённому номеру:
const response = await fetch('https://gate.whapi.cloud/groups', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const { groups } = await response.json();
console.log(groups);
У каждого объекта группы есть имя, фото, описание и массив участников.
Посчитать участников группы
Пройдитесь по массиву и выведите имя каждой группы и число участников:
groups.forEach(group => {
console.log(`Group Name: ${group.name}`);
console.log(`Participants: ${group.participants.length}`);
});
Обработка сообщений в группе
ID групповых чатов заканчиваются на
@g.us. Входящие вебхуки используют тот же суффикс; клонированный бот уже ветвится по нему, когда команда адресована группе.
// Из клонированного бота: сообщения групп идут с chat_id, который заканчивается на @g.us
const messages = req.body.messages;
messages.forEach(message => {
if (message.chat_id.endsWith('@g.us')) {
console.log(`Group message: ${message.text?.body}`);
}
});
Создание групп, приглашения и админы — в гайде по группам в документации.
Команда 7 создаёт группу с отправителем в участниках. Команда 8 пишет в
config.group. Пропишите этот ID до того, как пользоваться этими номерами.Оставьте его онлайн
Держите
node index.js на машине с публичным HTTPS-URL и задайте botUrl как https://ваш-хост/hook. Это долгоживущий процесс Express, а не одноразовая serverless-функция: подойдёт VPS или любой Node-хост с HTTPS. После смены botUrl перезапустите, чтобы вебхук зарегистрировался снова.Для того чтобы ваш чат-бот для WhatsApp был доступен 24/7, его необходимо разместить на надежной платформе хостинга. Вы можете использовать и свой сервер, однако в этой главе мы рассмотрим три самые популярные платформы — Firebase, AWS и Heroku — и пройдемся по базовым шагам деплоя вашего бота на каждой из них.
Выбор платформы зависит от ваших предпочтений, бюджета и требований к проекту. Каждая из рассмотренных платформ предлагает свои уникальные возможности и преимущества. Firebase и AWS Lambda обеспечивают мощный бэкенд без необходимости управления сервером, в то время как Heroku предлагает простоту развертывания приложений на основе Git.
Firebase
Firebase предлагает функционал Cloud Functions, который позволяет запускать ваш бот без необходимости заботиться о серверной инфраструктуре. На наш взгляд, это самый оптимальный вариант.
- Создайте проект в Firebase Console;
- Установите Firebase CLI, следуя инструкциям;
- Инициализируйте Firebase в директории вашего проекта с помощью команды firebase init;
- Разверните вашего бота, используя команду firebase deploy --only functions.
AWS (Amazon Web Services)
AWS Lambda предоставляет возможность запуска кода в ответ на триггеры из других сервисов AWS, что делает его хорошим выбором для бота.
- Зарегистрируйтесь или войдите в AWS Management Console;
- Создайте новую функцию Lambda через консоль AWS, выбрав в качестве триггера API Gateway;
- Загрузите код вашего бота в Lambda функцию;
- Настройте API Gateway для взаимодействия вашего бота с внешним миром.
Heroku
Heroku предлагает простую в использовании платформу для размещения приложений, которая может автоматически развертывать код из вашего Git репозитория.
- Создайте аккаунт на Heroku;
- Установите Heroku CLI и войдите в систему;
- Создайте новое приложение на Heroku через консоль или используя команду heroku create;
- Свяжите ваш Git репозиторий с Heroku и выполните деплой с помощью команд git push heroku master;
- Установите URL вебхука, предоставленный Heroku.
Что дальше
Когда бот запущен, поверх него можно собирать продукт. Отправляйте файлы по публичному URL; раскладывайте входящие лиды по группам WhatsApp; подключите CRM, чтобы брони и заказы обновлялись сразу; используйте опросы вместо кнопок; публикуйте статусы и отвечайте реакциями; или проверяйте номера перед массовой рассылкой. Смотрите документацию или разделы про группы, каналы, сообщества, MCP, n8n, Make, agent skills и хаб чат-ботов.
