Введение
Чат-бот для WhatsApp позволяет автоматически реагировать на запросы, отправлять уведомления, запрашивать информацию, делая общение эффективным и доступным 24/7.
Данное руководство для программистов - это пошаговая инструкция по настройке и запуску собственного чат-бота на базе Whapi.Cloud API на Node.JS, а также демонстрация ключевых функций и возможностей шлюза и бота.
Вы сможете использовать наш исходный код в своём проекте, легко изменяя и дополняя функционал скрипта. На базе кода создадите своего чат-бота или любую интеграци. Легко интегрируйте его в существующие рабочие процессы, продолжая пользоваться WhatsApp как обычно!
Исходный код
Скрипт данного чат-бота включает в себя основные функции, которые часто используются малым и средним бизнесом и покрывает большинство задач:
- Отправка обычного сообщения;
- Отправка медиа: изображение / файл / видео;
- Отправка контакта (визитная карточка vCard);
- Отправка товара;
- Создание WhatsApp группы;
- Отправка приглашения в группу;
- Отправка сообщения в WhatsApp группу;
- Получение и обработка входящих сообщений;
- Ответ на неизвестную команду (для реализации меню, инструкций или приветственного сообщения).
Установка окружения
Подготовим рабочее окружение. Убедитесь, что у вас уже всё готово для работы с Node.js. Дальше переходим к ГитХабу.
Процесс включает в себя клонирование исходного кода из репозитория на GitHub и установку необходимых зависимостей через npm (Node Package Manager). Вы можете сразу переходить к следующей главе, если сделали это уже самостоятельно.
Итак, вот базовые шаги для быстрого старта:
1. Клонирование репозитория.
Откройте терминал или командную строку и перейдите в директорию, где вы хотите разместить проект. Используйте следующую команду для клонирования репозитория:
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
2. Установка npm пакетов.
После клонирования репозитория перейдите в папку проекта:
cd your_project_name
Затем выполните следующую команду для установки всех необходимых npm пакетов, указанных в файле package.json:
npm install
Эта команда автоматически загрузит и установит все зависимости, необходимые для работы чат-бота.
Структура проекта
- /files - в этой папке лежат исходные файлы, которые будут использоваться для отправки файлов. Тестировать можно с этими файла, а потом заменить на собственные файлы. Вы так же сможете сделать отправку файлов по ссылке (подробнее в конце статьи);
- config.js - настройки для запуска бота;
- index.js - основной скрипт чат-бота;
Провайдер WhatsApp API
Whapi.Cloud предоставляет простой в использовании API шлюз, совместимый с любым языком программирования. Это позволит вам без нервов интегрировать ваш веб-сайт, магазин, приложение или CRM с WhatsApp.
Наш Cloud API является независимой разработкой и не имеет никаких ограничений для работы с отправкой сообщений, группами, каналами, статусами, звонками и прочим функционалом вашего мессенджера.
При этом доступ к API имеет фиксированную цену, за отправленные сообщения не взимается никакая оплата. Это ключевое преимущество нашего простого и мощного API.
Как подключиться к Whapi.Cloud
Еще одним преимуществом нашего шлюза является скорость онбоардинга и старта работы. Вам не потребуется проходить верификацию вашего бизнеса или менять свой номер. Подключайте собственный номер и можете продолжать пользоваться WhatsApp, как обычно!
Итак, зарегистрируйтесь в Whapi.Cloud. Вам потребуется действующий адрес электронной почты, чтобы пройти email верификацию либо google-аккаунт.
На Дашбоарде вы найдете триал-канал, выделенный индивидуально для вас. Первые 5 дней у вас будет возможность полностью бесплатно протестировать весь функционал API.
Бесплатный доступ к API на 5 дней
Перейдите на страницу этого канала, просто кликнув по нему.
В отличие от других провайдеров, мы предоставляем вам возможность подключить ваш существующий WhatsApp или WhatsApp Business к API.
Просто отсканируйте QR-код, как это делается в WhatsApp Web, и вы будете готовы к работе через несколько секунд.
На взгляд Meta, это обычное подключение к WhatsApp Web, и если вы не используете Whapi.Cloud для рассылки спама, ваш номер будет продолжать работать в обычном режиме.
Пропускайте третий шаг “Настройки канала”, сейчас они нам не понадобятся.
Отлично, теперь вам доступен API Token, который потребуется для тестирования и дальнейшей работы с эндпоинтами. Сохраните этот токен, он вам еще ни раз пригодится.
Перейдем в config.js и заменим переменную с токеном, вставляя ваш актуальный ключ:
token: "YOUR_CHANNEL_TOKEN"
token: "YOUR_CHANNEL_TOKEN"
Настройка Вебхука
Что такое вебхук и для чего он нужен
Для того, чтобы получать входящие данные из вашего мессенджера, например входящее сообщение или входящий звонок или уведомление о том, что кто-то вступил в вашу группу, вам потребуется использовать Webhook.
Эта технология позволит вам мгновенно получать уведомления о любом событии в вашем WhatsApp и реагировать на это.
Простыми словами на примере: Вам написал контакт А -> Скрипт чат-бота получил сообщение от контакта А -> Проверил, является ли это сообщение знакомой ему командой -> Выполнил команду скрипта (например отправил приветственное сообщение или отправил товар и т.п.)
Таким образом, две системы (наш API шлюз, подключенный к WhatsApp и ваш чат-бот) обмениваются информацией без необходимости каких-либо внешних действий.
Технически, при входящем сообщении, система выполнит POST запрос с JSON телом, на настроенную ссылку вашего скрипта. JSON тело будет включать в себя всю информацию о входящем сообщении, такие как текст, номер отправителя, время отправки и т.п., что позволит вам считывать эту информацию на лету.
Перейдем к настройке этой ссылки!
Перейдем к настройке этой ссылки!
Локально или на сервере
При разработке WhatsApp бота, возможно, вы захотите протестировать его локально, прежде чем разворачивать на сервере. Самый простой способ сделать это - использовать такие инструменты, как Ngrok, который создает безопасный туннель к вашему localhost, позволяя вам предоставить доступ к локальному серверу из Интернета.
Давайте возьмем для тестирования чат-бота ссылку с Ngrok прямо сейчас. Скачайте Ngrok с официального сайта и распакуйте его. Откройте терминал и перейдите в папку, где хранится Ngrok.
Запустите ./ngrok http НОМЕР_ПОРТА, заменяя НОМЕР_ПОРТА на порт, на котором ваш сервер Express работает локально.
Теперь у вас должен быть публичный URL, который вы можете использовать как URL для вебхука.
Копируем эту ссылку в config.js файл:
botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook"
Запустите ./ngrok http НОМЕР_ПОРТА, заменяя НОМЕР_ПОРТА на порт, на котором ваш сервер Express работает локально.
Теперь у вас должен быть публичный URL, который вы можете использовать как URL для вебхука.
Копируем эту ссылку в config.js файл:
botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook"
Внимание, оставьте в конце ссылки “/hook”! Именно на такой адрес сейчас запрограммирован скрипт чат-бота!
Особенности размещения на сервере
Для получения входящих веб-хуков необходимо, чтобы публичный IP-адрес / хост был доступен из Интернета. Таким образом, сервер Whapi.Cloud сможет отправить запрос на ваш сервер по указанному адресу и доставить входящий хук.
Конфигурация сервера:
- Whapi.Cloud работает только с вебхуками, которые используют HTTPS;
- Ваш эндпоинт должен принимать POST/PUT/PATCH/DELETE;
Ниже, в главе "Деплой", мы расскажем о нескольких общедоступных сервисах, на которых вы можете разместить свой чатбот.
Настройка и разные события
Настройки канала и вебхуков в Whapi.Cloud предоставляют широкие возможности для кастомизации, которые могут быть особенно полезны в проектах с индивидуальными требованиями.
Однако, для упрощения процесса запуска, мы включили установку необходимых настроек непосредственно в код нашего чат-бота, избавив вас от необходимости вносить их вручную. Это позволяет вам сосредоточиться на разработке, не беспокоясь о дополнительной конфигурации.
Если вы захотите углубиться в возможности кастомизации или понадобится более детальная настройка вебхука, всегда можно ознакомиться с полным перечнем опций в Базе Знаний Whapi.Cloud в статье: Подробные настройки вебхука
В исходном коде с ГитХаба вебхук-ссылка автоматически присваивается вашему каналу через API метод, поэтому дополнительных действий вам совершать не потребуется.
Давайте немного углубимся в режимы вебхуков и события, о которых наш сервис может уведомлять вас.
Сейчас, для отправки вебхука выбран режим Method. Этот способ особенно подходит для детализированной обработки событий, позволяя использовать различные HTTP-методы для конкретных действий. Таким образом вебхук будет разделять отправленные запросы и отправлять их на разные адреса, к примеру https://****/hook/messages (события, связанные с сообщениями) или https://****/hook/statuses (события, связанные со статусами сообщений) или https://****/hook/groups (события, связанные с группами).
Есть еще два режима у вебхука: Body (отправляет напрямую на ссылку тело запроса) и Path (полностью указывает api url запроса).
Есть еще два режима у вебхука: Body (отправляет напрямую на ссылку тело запроса) и Path (полностью указывает api url запроса).
События и способ, которым мы уведомляем исходный чат-бот — POST Messages. Этот вебхук отслеживает любые изменения, связанные с новыми сообщениями, включая отправленные сообщения и входящие сообщения.
Узнать больше о всех возможных событиях (получать сведения о группах, каналах, звонках, статусах, изменениях сообщений и т.п.), которые поддерживает наша система, вы можете в статье: Наши вебхуки (отслеживаемые события)
Запуск и настройка бота
Уже сейчас, вы можете проверить работу чат-бота! Убедитесь, что в config.js токен и адрес вебхука указаны корректно.
Запуск чат-бота делается путем выполнения команды node index.js в терминале из корневой директории проекта.
Ваш бот теперь должен быть активен и готов к работе.
Отправив сообщение на номер, к которому привязан бот, с другого телефона, вы должны получить автоматический ответ. В случае отсутствия реакции от бота, рекомендуем обратиться к разделу "Устранение неполадок" для диагностики и решения возможных проблем.
Предустановленные параметры (группа и товар)
В файле config.js находятся предустановленные значения, включая идентификаторы группы и товара, которые ваш чат-бот использует для отправки сообщений. Чтобы бот работал корректно в контексте ваших данных, необходимо обновить эти параметры согласно вашим нуждам.
- group: '[email protected]'
- product: '6559353560856703'
Первый идентификатор отвечает за группу, в которую чат-бот отправит сообщение.
Этот идентификатор вы можете получить, создав группу в WhatsApp или используя уже существующую.
Идентификатор группы можно получить только через API.
Для этого используйте вызов API "Получить список групп" (метод: https://whapi.readme.io/reference/getgroups в Документации ). Идентификатор группы выглядит следующим образом: [email protected]
Для этого используйте вызов API "Получить список групп" (метод: https://whapi.readme.io/reference/getgroups в Документации ). Идентификатор группы выглядит следующим образом: [email protected]
Подробнее про идентификаторы чатов (chat_id), мы написали отдельно в нашей статье: ID Чата. Что это такое и как его получить?
Итак, когда вы нашли нужный вам идентификатор группы, теперь скопируйте его в config.js.
Аналогично поступаем и с товарами вашего каталога (существует только в Business версии приложения).
Определите идентификатор товара, который будет отправляться вашим чат-ботом.
Вы можете получить список товаров с помощью метода https://whapi.readme.io/reference/getproducts в Документации.
Замените предустановленные значения в config.js на свои идентификаторы группы и товара.
После внесения изменений сохраните файл и перезапустите бота. Теперь он должен функционировать с использованием новых параметров, что позволит вам полноценно тестировать его работу.
Устранение неполадок
В процессе тестирования и эксплуатации чат-бота для WhatsApp могут возникать различные проблемы. Вот несколько типичных ситуаций и рекомендации по их решению:
Бот не реагирует на входящие сообщения
- Убедитесь, что вы отправляете сообщения на номер, на котором запущен бот, с другого телефона. Бот не сможет реагировать на сообщения, отправленные с того же номера.
- Если бот не реагирует на сообщения с других номеров, проверьте работу вебхуков. Используйте сервисы для симуляции вебхуков, например, Webhook.site, чтобы удостовериться, по какому пути приходят callback запросы. После этого проверьте соответствует ли путь, указанному вами в конфигурации. Так же, убедитесь, что ваш сервер отвечает 200Ok.
При возникновении сложностей не стесняйтесь обращаться в нашу техническую поддержку за помощью. Можете написать в виджет веб чата на нашем сайте либо на почту [email protected]. Мы поможем вам и разберем, что именно не так с вебхуком.
Бот отправляет сообщения без остановки
Вернитесь к изначальной версии кода. В нашем скрипте реализована проверка, определяющая, является ли сообщение входящим или исходящим, чтобы предотвратить попадание в бесконечный цикл отправки сообщений.
Бесконечная отправка может произойти, если в коде отсутствует проверка на исходящее сообщение, из-за чего бот вызывает сам себя, или если присутствует цикличекая отправка сообщений в коде.
Бот работает в некоторых чатах, а в других — нет
Проверьте ваш тарифный план на Whapi.Cloud. Если вы используете триал режим или тариф "Песочница", взаимодействие ограничено определённым количеством чатов в месяц (на данный момент до 5 чатов). В таком случае бот не сможет обрабатывать сообщения в шестом чате и последующих.
Важно помнить, что многие проблемы можно предотвратить, тщательно проверяя конфигурацию и логику вашего чат-бота перед запуском. Регулярное обновление вашего кода и внимание к деталям настроек помогут избежать большинства типичных ошибок. А наша команда поддержки всегда на связи и готова помочь вам!
Деплой и использование серверов
Для того чтобы ваш чат-бот для 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.
Расширение функционала
После успешного запуска и тестирования вашего чат-бота для WhatsApp, есть множество способов дальнейшего расширения его функциональности, чтобы сделать бота ещё более полезным и интерактивным для пользователей. Вот некоторые частые юзеркейсы:
- Отправка файлов по ссылке.
Отправить медиа-файл по ссылке очень просто. Главное условие, чтобы сам по себе файл был доступен напрямую по ссылке (в связи с этим не подходят Облачные сервисы по типу Google Drive или Dropbox, так как они не предоставляют прямой доступ к файлу). Используйте параметр media в любом из методов, которые позволяют отправлять медиа-файлы. Более подробнее информацию читайте в нашей статье: Эндпоинт для отправки медиафайла.
- Распределение лидов по группам.
Вам потребуется функция создания группы, а так же добавление участника в группу. Добавить участника в группу не составит труда, однако здесь есть некоторые нюансы. Мы описали подробнее в статье: "Добавление нового участника в группу"
- Интеграция с CRM.
Технически интеграция с CRM не так сильно отличается от чат-бота, с разницей лишь в том, что добавляется дополнительный ресурс с собственным API, который необходимо использовать. Добавьте функции, позволяющие пользователям бронировать услуги, заказывать товары или получать актуальную информацию из внешних источников в реальном времени.
- Опросы, как аналог кнопок у ботов.
Интерактивные кнопки в WhatsApp - очень удобный инструмент для работы с клиентами. Однако большинству пользователей WhatsApp эта функция недоступна. Мы за то, чтобы облегчить общение с пользователями, поэтому предлагаем вам удобную альтернативу - использовать опросы в качестве кнопок. Подробная статья с исходным кодом на NodeJS и как этим пользоваться.
- Увеличение вовлеченности клиентов.
Используйте сторисы, меняйте статусы вашего номера, ставьте лайки и другие эмодзи на сообщения ваших клиентов, отправляйте голосовые сообщения - увеличивайте вовлечение при работе с клиентами.
- Проверка номера на наличие WhatsApp.
Проверьте, существует ли указанный номер телефона в WhatsApp или нет. Определите, какие телефонные номера активны, а какие не могут получать сообщения WhatsApp. Интегрируйте в свое приложение, прежде чем делать рассылку! Исходный код на ГитХабе и инструкция по работе здесь.
Мы предоставляем комплексную поддержку нашим клиентам! Если у вас возникнут вопросы по работе бота, настройке платформы или вы столкнетесь с техническими трудностями, вы всегда можете рассчитывать на помощь.
Мы надеемся, что это руководство поможет вам успешно запустить чат-бота для WhatsApp. Удачи в ваших начинаниях!
