Dezvoltarea unui bot WhatsApp în Java: Ghid complet pentru începători
- Să conectați API-ul WhatsApp folosind furnizorul Whapi.Cloud;
- Să configurați webhook-uri pentru procesarea mesajelor primite;
- Să trimiteți mesaje text și media;
- Să gestionați grupuri și alte funcționalități ale mesageriei;
Pregătirea pentru dezvoltarea unui bot WhatsApp în Java
1. Instalați instrumentele necesare
2. Configurați mediul de lucru
mvn archetype:generate -DgroupId=com.example.whatsappbot -DartifactId=whatsapp-bot -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
3. Pregătiți editorul de cod
4. Obțineți un token API
Obținerea tokenului și conectarea numărului WhatsApp
1. Înregistrare pe Whapi.Cloud
2. Conectarea numărului dvs. de WhatsApp
- 2) Veți vedea primul pas al conectării, unde va fi disponibil un cod QR pentru conectarea numărului;
- 3) Pe dispozitivul dvs., deschideți WhatsApp → Setări → Dispozitive conectate → Conectare dispozitiv;
- 4) Scanați codul QR furnizat folosind WhatsApp;
3. Obținerea tokenului API
Instrumente pentru lucrul cu API-ul
- Hub pentru dezvoltatori: O platformă specializată cu documentație și exemple, care permite obținerea fragmentelor de cod pentru toate endpoint-urile în diverse limbaje de programare.
- Colecție Postman: Cereri gata pregătite pentru testarea API-ului prin Postman.
- Fișier Swagger: O descriere detaliată a tuturor metodelor API, cu posibilitatea de testare direct pe pagina canalului.
Ce este un Webhook și cum se configurează?
Ce este un webhook?
- Notificări instantanee. Toate evenimentele sunt procesate aproape în timp real.
- Capacitate mare de procesare. Viteza de primire a notificărilor este limitată doar de performanța serverului dvs.
- Flexibilitate. Puteți primi doar acele evenimente care vă sunt cu adevărat necesare, cum ar fi: Mesaje personale; Mesaje în grupuri; Modificări ale statusului mesajelor; Modificări ale participanților grupului; Notificări despre apeluri pierdute; Statusuri ale canalelor și multe altele.
Cum și unde obținem un URL pentru webhook?
Configurarea webhook-ului pe un canal
- Accesați setările canalului. Pe pagina canalului, apăsați butonul de setări (în colțul din dreapta sus).
- Configurați webhook-ul. Introduceți URL-ul dvs. în secțiunea webhook-urilor, folosind setările predefinite. Puteți configura mai multe webhook-uri pentru evenimente diferite, dacă este necesar. De asemenea, puteți modifica aceste setări prin API.
- Salvați modificările. După aceasta, toate notificările despre evenimentele din WhatsApp vor fi trimise către serverul specificat de dvs.
Crearea bazei unui bot WhatsApp în Java
1. Configurarea variabilelor de mediu
- Windows - Deschideți linia de comandă (cmd) și executați comanda: set WHAPI_TOKEN=XXXXXXXXX;
2. Construirea proiectului folosind Maven
3. Lansarea botului
Această metodă este convenabilă dacă tokenul a fost adăugat ca variabilă de mediu permanentă;
- 2) Opțiunea 2: Transmiterea tokenului în linia de comandă. Dacă nu utilizați variabile de mediu, transmiteți tokenul direct la lansarea aplicației: java -DWHAPI_TOKEN=XXXXXXXXX -jar target/whatsapp-bot-1.0.jar.
Această opțiune este utilă pentru lansări de testare sau dacă nu doriți să salvați tokenul în variabilele de mediu;
Exemplu de trimitere a unui mesaj text prin 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" — textul mesajului care va fi trimis destinatarului;
* YOUR_TOKEN — înlocuiți această valoare cu tokenul API pe care l-ați obținut din Dashboard-ul Whapi.Cloud;
Procesarea mesajelor primite prin webhook în 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) Procesarea comenzilor text: help și command trimit răspunsuri predefinite. video, image, document și vcard procesează cereri pentru trimiterea fișierelor media. Comenzile necunoscute sunt gestionate cu un răspuns implicit;
3) Jurnalizare: Se înregistrează informațiile despre mesajele primite și răspunsurile API;
4) Erori: Gestionarea excepțiilor pentru a preveni eșecurile la primirea mesajelor;
Funcționalități avansate cu Whapi.Cloud pentru integrarea dvs.
- Trimiterea mesajelor: Transmiteți mesaje text, imagini, documente, videoclipuri, locații, contacte și stickere;
- Interacțiune dinamică: Adăugați reacții (emoji) la mesaje, citați-le, marcați-le ca citite și setați starea „scrie...”;
- Gestionarea grupurilor: Creați și ștergeți automat grupuri, adăugați sau eliminați participanți, desemnați administratori și modificați setările grupului;
- Lucrul cu comunități: Configurați și administrați comunitățile WhatsApp pentru comunicare de grup structurată;
- Trimiterea statusurilor (story-uri): Creați și trimiteți statusuri text sau media către numere specifice sau către toate numerele;
- Gestionarea canalelor: Publicați anunțuri text și media în canalul dumneavoastră, desemnați administratori, primiți mesaje din alte canale;
- Funcționalități avansate: Fixați conversații, blocați utilizatori, trimiteți sondaje și produse, și primiți date despre grupuri și participanți în timp real;
Crearea unui grup WhatsApp în 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();
Depanarea problemelor
Botul nu răspunde la mesajele primite
- Asigurați-vă că trimiteți mesaje la numărul pe care rulează botul, de pe un alt telefon. Botul nu va putea reacționa la mesajele trimise de pe același număr.
- Dacă botul nu reacționează la mesaje de pe alte numere, verificați funcționarea webhook-urilor. Utilizați servicii pentru simularea webhook-urilor, de exemplu, Webhook.site, pentru a vă asigura că cererile de callback vin pe calea corectă. După aceea, verificați dacă calea corespunde celei configurate de dvs. De asemenea, asigurați-vă că serverul dvs. răspunde cu 200Ok.
Botul trimite mesaje fără oprire
Botul funcționează în unele chat-uri, dar în altele nu
Implementare și utilizarea serverelor
Firebase
- Creați un proiect în Consola Firebase;
- Instalați Firebase CLI, urmând instrucțiunile;
- Inițializați Firebase în directorul proiectului dvs. folosind comanda firebase init;
- Desfășurați botul folosind comanda firebase deploy --only functions.
AWS (Amazon Web Services)
- Înregistrați-vă sau autentificați-vă în Consola de Management AWS;
- Creați o nouă funcție Lambda prin consola AWS, alegând API Gateway ca declanșator;
- Încărcați codul botului dvs. în funcția Lambda;
- Configurați API Gateway pentru a interacționa cu botul dvs. în lumea externă.
Heroku
- Creați un cont pe Heroku;
- Instalați Heroku CLI și autentificați-vă;
- Creați o nouă aplicație pe Heroku folosind consola sau comanda heroku create;
- Asociați repoziția dvs. Git cu Heroku și efectuați desfășurarea folosind comenzi git push heroku master;
- Configurați URL-ul webhook furnizat de Heroku.