Desenvolvimento de um bot do WhatsApp em Java: Guia completo para iniciantes
- Conectar a API do WhatsApp usando o provedor Whapi.Cloud;
- Configurar webhooks para processar mensagens recebidas;
- Enviar mensagens de texto e mídia;
- Gerenciar grupos e outras funções do mensageiro;
Preparação para o desenvolvimento do bot do WhatsApp em Java
1. Instale as ferramentas necessárias
2. Configure o ambiente de trabalho
mvn archetype:generate -DgroupId=com.example.whatsappbot -DartifactId=whatsapp-bot -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
3. Prepare o editor de código
4. Obtenha o Token da API
Obtendo o token e conectando o número do WhatsApp
1. Registro no Whapi.Cloud
2. Conectando seu número do WhatsApp
- 2) Você verá a primeira etapa de conexão, onde um QR Code para conexão do número estará disponível;
- 3) No seu dispositivo, abra o WhatsApp → Configurações → Dispositivos conectados → Conectar um dispositivo;
- 4) Escaneie o QR Code fornecido usando o WhatsApp;
3. Obtendo o token da API
Ferramentas para trabalhar com a API
- Hub amigável para desenvolvedores: Plataforma especializada com documentação e exemplos que fornecem trechos de código para todos os endpoints em diferentes linguagens de programação.
- Coleção Postman: Solicitações prontas para testar a API usando o Postman.
- Arquivo Swagger: Descrição detalhada de todos os métodos da API, com a possibilidade de testar diretamente na página do canal.
O que é um Webhook e como configurá-lo?
O que é um webhook?
- Notificações instantâneas. Todos os eventos são processados praticamente em tempo real.
- Alta capacidade. A velocidade de recebimento das notificações é limitada apenas pelo desempenho do seu servidor.
- Flexibilidade. Você pode receber apenas os eventos que realmente precisa, como: Mensagens privadas; Mensagens em grupos; Mudanças nos status das mensagens; Alterações de participantes em grupos; Notificações de chamadas perdidas; Status de canais e muito mais.
Como e onde obter o URL para o webhook?
Configuração do webhook no canal
- Vá para as configurações do canal. Na página do canal, clique no botão de configurações (no canto superior direito).
- Configure o webhook. Insira seu URL na seção de webhooks, usando as configurações pré-selecionadas. Você pode configurar vários webhooks para eventos diferentes, se necessário. Além disso, essas configurações podem ser alteradas via API.
- Salve as alterações. Após isso, todas as notificações de eventos do WhatsApp serão enviadas para o servidor especificado.
Criação da estrutura básica do bot do WhatsApp em Java
1. Configuração de variáveis de ambiente
- Windows - Abra o prompt de comando (cmd) e execute o comando: set WHAPI_TOKEN=XXXXXXXXX;
2. Compilação do projeto com o Maven
3. Iniciando o bot
Este método é conveniente se o token foi adicionado como uma variável de ambiente permanente;
- 2) Opção 2: Passar o token na linha de comando. Se você não usa variáveis de ambiente, passe o token diretamente ao iniciar o aplicativo: java -DWHAPI_TOKEN=XXXXXXXXX -jar target/whatsapp-bot-1.0.jar.
Esta opção é útil para execuções de teste ou se você não deseja armazenar o token em variáveis de ambiente;
Exemplo de envio de mensagem de texto pela 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" — o texto da mensagem que será enviada ao destinatário;
* YOUR_TOKEN — substitua este valor pelo seu token da API, que você obteve no painel do Whapi.Cloud Dashboard;
Processamento de mensagens recebidas via webhook em 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) Processamento de comandos de texto: help e command enviam respostas pré-preparadas. Os comandos video, image, document e vcard processam solicitações para envio de arquivos de mídia. Comandos desconhecidos são tratados com uma resposta padrão;
3) Registro: Informações sobre mensagens recebidas e respostas da API são registradas;
4) Erros: Tratamento de exceções para evitar falhas no recebimento de mensagens;
Recursos avançados do Whapi.Cloud para sua integração
- Envio de mensagens: Envie mensagens de texto, imagens, documentos, vídeos, localização, contatos e figurinhas;
- Interação dinâmica: Adicione reações (emojis) às mensagens, cite-as, marque como lidas e configure o status "digitando...";
- Gerenciamento de grupos: Crie e exclua grupos automaticamente, adicione ou remova participantes, atribua administradores e altere as configurações do grupo;
- Trabalhe com comunidades: Configure e gerencie comunidades do WhatsApp para uma comunicação estruturada em grupo;
- Envio de status (stories): Crie e envie status de texto ou mídia para números específicos ou para todos os contatos;
- Gerenciamento de canais: Publique anúncios de texto e mídia no seu canal, atribua administradores e receba mensagens de outros canais;
- Recursos avançados: Fixe diálogos, bloqueie usuários, envie enquetes e produtos, além de obter dados de grupos e participantes em tempo real;
Criação de um grupo do WhatsApp em 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();
Resolução de problemas
Bot não responde a mensagens recebidas
- Certifique-se de que você está enviando mensagens para o número em que o bot está ativo, de outro telefone. O bot não poderá responder mensagens enviadas do mesmo número.
- Se o bot não responder a mensagens de outros números, verifique o funcionamento dos webhooks. Use serviços de simulação de webhooks, como o Webhook.site, para confirmar como as solicitações de callback estão chegando. Depois, verifique se o caminho corresponde ao configurado por você. Além disso, certifique-se de que seu servidor responde com 200Ok.
Bot envia mensagens sem parar
Bot funciona em alguns chats, mas não em outros
Deploy e uso de servidores
Firebase
- Crie um projeto no Firebase Console;
- Instale o Firebase CLI, seguindo as instruções;
- Initialize o Firebase no diretório do seu projeto usando o comando firebase init;
- Implante seu bot usando o comando firebase deploy --only functions.
AWS (Amazon Web Services)
- Registre-se ou entre no Console de Gerenciamento da AWS;
- Crie uma nova função Lambda através do console da AWS, escolhendo o API Gateway como gatilho;
- Carregue o código do seu bot na função Lambda;
- Configure o API Gateway para interação do seu bot com o mundo externo.
Heroku
- Crie uma conta no Heroku;
- Instale o Heroku CLI e faça login;
- Crie um novo aplicativo no Heroku através do console ou usando o comando heroku create;
- Associe seu repositório Git ao Heroku e faça o deploy usando os comandos git push heroku master;
- Configure o URL do webhook fornecido pelo Heroku.