Разработка WhatsApp бота на Java: Полное руководство для начинающих
- Подключить WhatsApp API с помощью провайдера Whapi.Cloud;
- Настроить вебхуки для обработки входящих сообщений;
- Отправлять текстовые и медиа-сообщения;
- Управлять группами и другими функциями мессенджера;
Подготовка к разработке WhatsApp бота на Java
1. Установите необходимые инструменты
2. Настройте рабочее окружение
mvn archetype:generate -DgroupId=com.example.whatsappbot -DartifactId=whatsapp-bot -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
3. Подготовьте редактор кода
4. Получите API Token
Получение токена и подключение WhatsApp-номера
1. Регистрация в Whapi.Cloud
2. Подключение вашего WhatsApp-номера
- 2) Вы увидите первый шаг подключения, на котором вас будет ожидать QR-код для подключения номера;
- 3) На вашем устройстве откройте WhatsApp → Настройки → Связанные устройства → Подключить устройство;
- 4) Сканируйте предоставленный QR-код через WhatsApp;
3. Получение API-токена
Инструменты для работы с API
- Удобный Хаб для разработчика: Специализированная платформа с документацией и примерами, позволит получить на все эндпоинты фрагменты кода на разных языках программирования.
- Postman-коллекция: Готовые запросы для тестирования API через Постман.
- Swagger-файл: Подробное описание всех методов API, с возможностью тестирования прямо на странице канала.
Что такое Webhook и как его настроить?
Что такое вебхук?
- Мгновенные уведомления. Все события обрабатываются практически в реальном времени.
- Высокая пропускная способность. Скорость получения уведомлений ограничена только производительностью вашего сервера.
- Гибкость. Вы можете получать только те события, которые вам действительно нужны, например: Личные сообщения; Сообщения в группах; Изменения статусов сообщений; Изменения участников групп; Уведомления о пропущенных вызовах; Статусы каналов и многое другое.
Как и где получить URL для вебхука?
Установка вебхука на канал
- Перейдите в настройки канала. На странице канала нажмите кнопку настроек (в правом верхнем углу).
- Настройте вебхук. Укажите ваш URL в разделе вебхуков, используя предвыбранные настройки. Вы можете настроить несколько вебхуков для разных событий, если это необходимо. Так же, вы сможете менять эти настройки через API.
- Сохраните изменения. После этого все уведомления о событиях в WhatsApp будут отправляться на указанный вами сервер.
Создание основы WhatsApp-бота на Java
1. Настройка переменных окружения
- Windows - Откройте командную строку (cmd) и выполните команду: set WHAPI_TOKEN=XXXXXXXXX;
2. Сборка проекта с помощью Maven
3. Запуск бота
Этот метод удобен, если токен был добавлен как постоянная переменная окружения;
- 2) Опция 2: Передача токена в командной строке. Если вы не используете переменные окружения, передайте токен непосредственно при запуске приложения: java -DWHAPI_TOKEN=XXXXXXXXX -jar target/whatsapp-bot-1.0.jar.
Этот вариант полезен для тестовых запусков или если вы не хотите хранить токен в переменных окружения;
Пример отправки текстового сообщения через API
// Import necessary libraries
import okhttp3.*; // OkHttp library for HTTP requests
public class SendMessageExample {
public static void main(String[] args) throws Exception {
// Step 1: Create an instance of OkHttpClient to send HTTP requests
OkHttpClient client = new OkHttpClient();
// Step 2: Define the media type for the request body (JSON in this case)
MediaType mediaType = MediaType.parse("application/json");
// Step 3: Create the JSON payload with the recipient's phone number and the message content
/*
* "to" - the recipient's WhatsApp number in international format (e.g., 919984351847)
* "body" - the text message you want to send
*/
RequestBody body = RequestBody.create(mediaType,
"{\"to\":\"919984351847\",\"body\":\"Hello, world!\"}");
// Step 4: Build the HTTP POST request
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/messages/text") // API endpoint for sending text messages
.post(body) // Attach the JSON payload in the request body
.addHeader("accept", "application/json") // Accept JSON responses
.addHeader("content-type", "application/json") // Specify JSON content type
.addHeader("authorization", "Bearer YOUR_TOKEN") // Include your API token for authentication
.build();
// Step 5: Execute the request and receive the response
Response response = client.newCall(request).execute();
// Step 6: Print the response from the API to see the result
/*
* A successful response typically returns a JSON object with message details.
* Use this information to confirm that the message was sent.
*/
System.out.println(response.body().string());
}
}
* "body" — текст сообщения, который будет отправлен получателю;
* YOUR_TOKEN — замените это значение вашим API-токеном, который вы получили в Whapi.Cloud Dashboard;
Обработка входящих сообщений через вебхук на Java
public void processMessages(List messages) {
try {
// Going through the list of all incoming messages
for (MessagePayload message : messages) {
// Ignore messages sent by the bot itself
if (message.isFromMe())
continue;
// Get chatId - identifier of the chat from which the message came
String chatId = message.getChatId();
String response;
// Handle text messages only
if (message.getType().equals("text")) {
// Retrieve the message body and convert to lower case for simplified processing
String body = ((String) message.getText().get("body")).toLowerCase();
switch (body) {
// Responding to “help” or “command” commands
case "help", "command" -> {
TextMessage txtMessage =
TextMessage.builder()
.to(chatId)
.body(responseMap.get(body)) // The message is taken from the prepared responseMap
.build();
response = postJson(txtMessage, "messages/text");
}
// Обработка мультимедиа-запросов: "video", "image", "document"
case "video", "image", "document" -> {
try (InputStream stream = getFile(body)) {
// Create the body of the request to send the file
RequestBody fileBody = RequestBody.create(
MediaType.parse(MediaTypeFactory.getMediaType(fileMap.get(body)).toString()),
stream.readAllBytes()
);
// Build a multipart request to send a media file
MultipartBody multipartBody = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("to", chatId) // Адресат
.addFormDataPart("media", fileMap.get(body), fileBody) // Сам файл
.addFormDataPart("caption", responseMap.get(body)) // Описание к медиа
.build();
response = postMultipart(multipartBody, "messages/" + body);
}
}
// Response to request to send contact card “vcard”
case "vcard" -> {
try (InputStream stream = getFile(body)) {
ContactMessage contactMessage =
ContactMessage.builder()
.name("Whapi test")
.to(chatId)
.vcard(new String(stream.readAllBytes())) // vCard file in text form
.build();
response = postJson(contactMessage, "messages/contact");
}
}
// Handling unknown commands: send default response
default -> {
TextMessage defaultMessage =
TextMessage.builder()
.to(chatId)
.body(responseMap.get("unknown"))
.build();
response = postJson(defaultMessage, "messages/text");
}
}
// Logging a successful response from the API
log.info("Response received [{}]", response);
} else {
// Logging message types that are not yet processed
log.warn("{} type not handled", message.getType());
}
}
} catch (Exception e) {
// Error handling during message processing
log.error("Could not process the message " + e.getMessage());
}
}
2) Обработка текстовых команд: help и command отправляют заранее подготовленные ответы. video, image, document и vcard обрабатывают запросы на отправку медиафайлов. Неизвестные команды обрабатываются дефолтным ответом;
3) Логирование: Логируется информация о входящих сообщениях и ответы API;
4) Ошибки: Обработка исключений для предотвращения сбоев при получении сообщений;
Расширенные возможности с Whapi.Cloud для вашей интеграции
- Отправка сообщений: Передавайте текстовые сообщения, изображения, документы, видео, геолокацию, контакты и стикеры;
- Динамическое взаимодействие: Добавляйте реакции (эмодзи) на сообщения, цитируйте их, отмечайте как прочитанные, а также устанавливайте статус «печатает...»;
- Управление группами: Автоматически создавайте и удаляйте группы, добавляйте или удаляйте участников, назначайте администраторов и изменяйте настройки группы;
- Работа с сообществами: Настраивайте и управляйте WhatsApp-сообществами для структурированной групповой коммуникации;
- Отправляйте статусы (сторисы): Создать и отправить текстовые либо медиа статусы на конкретный либо на все номера;
- Управление каналами: Постите текстовые и медиа-объявления в ваш канал, назначайте администраторов, получайте сообщения из других каналов;
- Расширенные функции: Закрепляйте диалоги, блокируйте пользователей, отправляйте опросы и товары, а также получайте данные о группах и участниках в реальном времени;
Создание WhatsApp Группы на Java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"919984351847\",\"919984351848\",\"919984351849\"],\"subject\":\"Group Subject 99\"}");
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/groups")
.post(body)
.addHeader("accept", "application/json")
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer YOUR_TOKEN")
.build();
Response response = client.newCall(request).execute();
Устранение неполадок
Бот не реагирует на входящие сообщения
- Убедитесь, что вы отправляете сообщения на номер, на котором запущен бот, с другого телефона. Бот не сможет реагировать на сообщения, отправленные с того же номера.
- Если бот не реагирует на сообщения с других номеров, проверьте работу вебхуков. Используйте сервисы для симуляции вебхуков, например, Webhook.site, чтобы удостовериться, по какому пути приходят callback запросы. После этого проверьте соответствует ли путь, указанному вами в конфигурации. Так же, убедитесь, что ваш сервер отвечает 200Ok.
Бот отправляет сообщения без остановки
Бот работает в некоторых чатах, а в других — нет
Деплой и использование серверов
Firebase
- Создайте проект в Firebase Console;
- Установите Firebase CLI, следуя инструкциям;
- Инициализируйте Firebase в директории вашего проекта с помощью команды firebase init;
- Разверните вашего бота, используя команду firebase deploy --only functions.
AWS (Amazon Web Services)
- Зарегистрируйтесь или войдите в AWS Management Console;
- Создайте новую функцию Lambda через консоль AWS, выбрав в качестве триггера API Gateway;
- Загрузите код вашего бота в Lambda функцию;
- Настройте API Gateway для взаимодействия вашего бота с внешним миром.
Heroku
- Создайте аккаунт на Heroku;
- Установите Heroku CLI и войдите в систему;
- Создайте новое приложение на Heroku через консоль или используя команду heroku create;
- Свяжите ваш Git репозиторий с Heroku и выполните деплой с помощью команд git push heroku master;
- Установите URL вебхука, предоставленный Heroku.