Desarrollo de un bot de WhatsApp en Java: Guía completa para principiantes
- Conectar la API de WhatsApp utilizando el proveedor Whapi.Cloud;
- Configurar webhooks para procesar mensajes entrantes;
- Enviar mensajes de texto y multimedia;
- Gestionar grupos y otras funciones del mensajero;
Preparación para desarrollar un bot de WhatsApp en Java
1. Instale las herramientas necesarias
2. Configure el entorno de trabajo
mvn archetype:generate -DgroupId=com.example.whatsappbot -DartifactId=whatsapp-bot -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
3. Prepare el editor de código
4. Obtenga el Token de API
Obtención del token y conexión del número de WhatsApp
1. Registro en Whapi.Cloud
2. Conexión de su número de WhatsApp
- 2) Verá el primer paso de conexión, donde le espera un código QR para conectar el número;
- 3) En su dispositivo, abra WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo;
- 4) Escanee el código QR proporcionado a través de WhatsApp;
3. Obtención del token de API
Herramientas para trabajar con la API
- Hub práctico para desarrolladores: Plataforma especializada con documentación y ejemplos que le permitirá obtener fragmentos de código para todos los endpoints en varios lenguajes de programación.
- Colección de Postman: Solicitudes preparadas para probar la API a través de Postman.
- Archivo Swagger: Descripción detallada de todos los métodos de la API, con la posibilidad de realizar pruebas directamente desde la página del canal.
¿Qué es un Webhook y cómo configurarlo?
¿Qué es un webhook?
- Notificaciones instantáneas. Todos los eventos se procesan casi en tiempo real.
- Alta capacidad. La velocidad de recepción de notificaciones está limitada únicamente por el rendimiento de su servidor.
- Flexibilidad. Puede recibir solo los eventos que realmente necesita, como: Mensajes personales; Mensajes en grupos; Cambios en el estado de los mensajes; Cambios en los participantes de los grupos; Notificaciones de llamadas perdidas; Estados de los canales y mucho más.
¿Cómo y dónde obtener una URL para el webhook?
Configuración del webhook en el canal
- Vaya a la configuración del canal. En la página del canal, haga clic en el botón de configuración (en la esquina superior derecha).
- Configure el webhook. Especifique su URL en la sección de webhooks utilizando las configuraciones preseleccionadas. Puede configurar múltiples webhooks para diferentes eventos si es necesario. También puede cambiar estas configuraciones mediante la API.
- Guarde los cambios. Después de esto, todas las notificaciones sobre eventos en WhatsApp se enviarán al servidor que especificó.
Creación de la base del bot de WhatsApp en Java
1. Configuración de las variables de entorno
- Windows - Abra la línea de comandos (cmd) y ejecute el siguiente comando: set WHAPI_TOKEN=XXXXXXXXX;
2. Compilación del proyecto con Maven
3. Ejecución del bot
Este método es conveniente si el token se ha agregado como una variable de entorno permanente;
- 2) Opción 2: Pasar el token en la línea de comandos. Si no utiliza variables de entorno, pase el token directamente al iniciar la aplicación: java -DWHAPI_TOKEN=XXXXXXXXX -jar target/whatsapp-bot-1.0.jar.
Esta opción es útil para ejecuciones de prueba o si no desea almacenar el token en las variables de entorno;
Ejemplo de envío de un mensaje de texto mediante la 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" — el texto del mensaje que se enviará al destinatario;
* YOUR_TOKEN — reemplace este valor con su token de API, que obtuvo en el Panel de Whapi.Cloud Dashboard;
Procesamiento de mensajes entrantes a través de un webhook en 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) Procesamiento de comandos de texto: help y command envían respuestas predefinidas. video, image, document y vcard manejan solicitudes para enviar archivos multimedia. Los comandos desconocidos se manejan con una respuesta predeterminada;
3) Registro: Se registra la información sobre los mensajes entrantes y las respuestas de la API;
4) Errores: Manejo de excepciones para evitar fallos al recibir mensajes;
Funciones avanzadas con Whapi.Cloud para su integración
- Envío de mensajes: Transmita mensajes de texto, imágenes, documentos, videos, ubicación, contactos y stickers;
- Interacción dinámica: Agregue reacciones (emojis) a los mensajes, cítelos, márquelos como leídos y configure el estado "escribiendo...";
- Gestión de grupos: Cree y elimine grupos automáticamente, agregue o elimine participantes, designe administradores y modifique la configuración del grupo;
- Trabajo con comunidades: Configure y gestione comunidades de WhatsApp para una comunicación grupal estructurada;
- Envío de estados (historias): Cree y envíe estados de texto o multimedia a números específicos o a todos;
- Gestión de canales: Publique anuncios de texto y multimedia en su canal, asigne administradores y reciba mensajes de otros canales;
- Funciones avanzadas: Fije diálogos, bloquee usuarios, envíe encuestas y productos, y obtenga datos sobre grupos y participantes en tiempo real;
Creación de un grupo de WhatsApp en 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();
Solución de problemas
El bot no responde a mensajes entrantes
- Asegúrate de que estás enviando mensajes al número en el que se ejecuta el bot desde otro teléfono. El bot no podrá reaccionar a los mensajes enviados desde el mismo número.
- Si el bot no reacciona a los mensajes de otros números, verifica el funcionamiento de los webhooks. Utiliza servicios para simular webhooks, por ejemplo, Webhook.site, para asegurarte de por dónde llegan las solicitudes de callback. Luego, verifica que el camino coincide con lo que configuraste. Además, asegúrate de que tu servidor responde con 200Ok.
El bot envía mensajes sin parar
El bot funciona en algunos chats, pero en otros no
Despliegue y uso de servidores
Firebase
- Crea un proyecto en Firebase Console;
- Instala Firebase CLI, siguiendo las instrucciones;
- Inicializa Firebase en el directorio de tu proyecto con el comando firebase init;
- Despliega tu bot usando el comando firebase deploy --only functions.
AWS (Amazon Web Services)
- Regístrate o inicia sesión en AWS Management Console;
- Crea una nueva función Lambda a través de la consola de AWS, eligiendo API Gateway como desencadenante;
- Sube el código de tu bot a la función Lambda;
- Configura API Gateway para que tu bot interactúe con el mundo exterior.
Heroku
- Crea una cuenta en Heroku;
- Instala Heroku CLI e inicia sesión;
- Crea una nueva aplicación en Heroku a través de la consola o usando el comando heroku create;
- Conecta tu repositorio Git con Heroku y realiza el despliegue con los comandos git push heroku master;
- Configura la URL del webhook proporcionada por Heroku.