Sari peste boilerplate: clonează un bot care deja funcționează
Ghidul folosește botul open-source din repo-ul GitHub Whapi.Cloud. Acoperă deja trimitere, primire, media, contacte, produse și grupuri. Restul articolului arată cum îl pornești.
Scriptul acestui chatbot include funcțiile de bază frecvent utilizate de afacerile mici și mijlocii și acoperă majoritatea sarcinilor:
- Trimiterea unui mesaj obișnuit;
- Trimiterea de media: imagine / fișier / video;
- Trimiterea unui contact (carte de vizită vCard);
- Trimiterea unui produs;
- Crearea unui grup WhatsApp;
- Trimiterea unei invitații în grup;
- Trimiterea unui mesaj în grupul WhatsApp;
- Primirea și procesarea mesajelor primite;
- Răspuns la o comandă necunoscută (pentru implementarea meniului, instrucțiunilor sau mesajului de bun venit).
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
După clonare, intră în folderul proiectului:
cd nodejs-whatsapp-chatbot
Instalează pachetele din
package.json:
npm install
Asta descarcă dependențele de care chatbotul are nevoie ca să pornească.
Structura proiectului
- /files — media de exemplu pe care botul o poate trimite (imagine, PDF, video, vCard). Înlocuiește-le când vrei.
- config.js —
token,botUrl,portși ID-uri opționalegroup/product. - index.js — înregistrează webhook-ul, ascultă pe
/hook/messagesși mapează numerele 1–9 pe acțiuni.
Conectează numărul tău de WhatsApp
Whapi.Cloud este un gateway HTTP pentru WhatsApp, independent de Meta. Folosești orice număr existent, scanezi un QR în dashboard și primești un token Bearer. Fără verificare Meta Business și fără limite de șabloane sau fereastră de mesaje Cloud API.
Ca botul să meargă, telefonul nu trebuie să rămână online. Leagă numărul o dată din dashboard și rulează botul pe orice server. Dacă ai nevoie de ajutor, folosește chatul de suport de pe site.
Scanează codul QR din cont
Înregistrare. Primul pas: te înregistrezi pe site-ul Whapi.Cloud și îți creezi un cont. Este gratuit și nu cere card.
După înregistrare ai imediat un canal de test cu o cotă redusă. Așteaptă să pornească (de obicei un minut). Va trebui să conectezi telefonul: de pe acel număr se trimit mesajele. Avantajul: în câteva minute ești operațional.
Ca să conectezi telefonul, folosește QR-ul când dai click pe canalul de test din cont. În WhatsApp pe mobil: Setări -> Dispozitive conectate -> Conectează un dispozitiv -> Scanează codul QR.
Poți sări ecranele de nume canal și webhook din asistent — botul setează webhook-ul la pornire.
Acum ai tokenul API, necesar la teste și apeluri. Păstrează-l, îl vei folosi de mai multe ori. Din cardul canalului copiază tokenul și lipește-l în
config.js ca token. Cererile către https://gate.whapi.cloud îl trimit ca Bearer.
Înainte să pornești botul
- Tokenul canalului lipit în
config.js. - Un al doilea telefon de test: botul ignoră mesajele numărului conectat.
- URL HTTPS publică. Local folosește ngrok; în producție, orice host cu HTTPS.
Dă-i botului o URL HTTPS publică
Un webhook e mesajul pe care Whapi.Cloud îl trimite botului tău de fiecare dată când se întâmplă ceva în contul WhatsApp conectat: un text nou, o schimbare de status, o invitație în grup.
În loc să întrebi iar și iar «sunt mesaje noi?», scriptul tău primește un POST cu evenimentul imediat ce se întâmplă.
Exemplu: contactul A îți scrie «salut» -> Whapi.Cloud face POST cu un JSON la
/hook/messages pe serverul tău -> botul verifică comanda și răspunde. Nu lipești URL-ul în dashboard; botul o înregistrează din config.js la pornire.Whapi.Cloud livrează mesajele primite cu un POST către URL-ul tău HTTPS public. Nu o lipești în dashboard. Pune-o în
config.js ca botUrl; la start repo-ul o înregistrează prin API-ul de setări al canalului.Tunel local cu ngrok
port implicit în config.js este 80 (nu folosi 443). Descarcă ngrok, apoi rulează ngrok http 80 — sau portul din config.js.Copiază URL-ul de forwarding
https://. Setează botUrl la acel host plus /hook, de exemplu botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook".
Păstrează sufixul
/hook. Serverul ascultă POST pe /hook/messages; botUrl este prefixul salvat în setările canalului.Când rulezi
node index.js, botul trimite PATCH /settings cu acea URL și evenimentul messages. Mesajele WhatsApp ajung apoi în procesul tău. Poți ignora câmpurile de webhook din dashboard, decât dacă vrei să vezi ce s-a înregistrat.Ce cere producția
Hostul trebuie să fie accesibil pe internet prin HTTPS, iar procesul Node să rămână pornit ca să accepte POST. După ce schimbi
botUrl, repornește botul ca să reînregistreze webhook-ul.Pornește botul
Confirmă
token și botUrl în config.js, apoi din rădăcina proiectului rulează node index.js. Ar trebui să vezi un log de listening. De pe un telefon diferit, trimite orice text către numărul conectat. Botul răspunde cu un meniu numerotat.Meniul de comenzi
- Mesaj text simplu
- Trimite imagine
- Trimite document
- Trimite video
- Trimite contact
- Trimite produs
- Creează grup
- Text simplu către grup
- Obține id-urile celor trei grupuri
Trimite doar numărul, de exemplu 1. Orice altceva returnează din nou lista.
Comenzile 6 și 8 folosesc
product și group în config.js. Sari-le la primul test. Când ai nevoie, listează ID-uri cu GET /groups și GET /business/products.Depanare
Botul nu răspunde
Scrie de pe alt telefon — scriptul sare
from_me. Verifică tokenul, că botUrl se termină cu /hook, că ngrok (sau hostul) încă rulează și că procesul a afișat mesajul de listening.Botul trimite mesaje în buclă
Păstrează
if (message.from_me) continue. Fără el, botul răspunde la propriile mesaje și nu se oprește.Funcționează în unele chat-uri, în altele nu
Sandbox limitează conversațiile active (acum 5 pe lună). Un al șaselea chat nu primește răspunsuri până nu treci pe un plan superior sau se resetează cota.
Trimite mesaje WhatsApp din Node.js
Botul clonat deja trimite, primește, media, contacte, produse, grupuri și altele. Snippet-urile de mai jos sunt același pattern HTTP intern: un
fetch către https://gate.whapi.cloud cu tokenul Bearer.Trimiterea unui mesaj text
Trimite un text simplu într-un chat sau grup:
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
body: 'Hello from the cloned bot'
})
});
const data = await response.json();
console.log(data);
Trimiterea unui document
Trimite un document prin URL publică sau payload base64:
const response = await fetch('https://gate.whapi.cloud/messages/document', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
media: 'https://example.com/file.pdf',
caption: 'Document from the bot'
})
});
const data = await response.json();
console.log(data);
Lista completă de tipuri și payload-uri este în referința API.
Lucrul cu grupurile WhatsApp
Botul poate lista grupurile în care ești și reacționa la mesaje de grup. Exemplele refolosesc același Bearer și endpoint-ul
/groups.Listează-ți grupurile
Preia grupurile vizibile pentru numărul conectat:
const response = await fetch('https://gate.whapi.cloud/groups', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const { groups } = await response.json();
console.log(groups);
Fiecare obiect de grup include nume, poză, descriere și un array de participanți.
Numără participanții grupului
Parcurge array-ul ca să afișezi numele fiecărui grup și numărul de membri:
groups.forEach(group => {
console.log(`Group Name: ${group.name}`);
console.log(`Participants: ${group.participants.length}`);
});
Gestionează mesajele din grup
ID-urile de chat de grup se termină cu
@g.us. Webhook-urile primite folosesc același sufix; botul clonat deja ramifică pe el când un comandă vizează un grup.
// Din botul clonat: mesajele din grupuri folosesc chat_id care se termină cu @g.us
const messages = req.body.messages;
messages.forEach(message => {
if (message.chat_id.endsWith('@g.us')) {
console.log(`Group message: ${message.text?.body}`);
}
});
Pentru creare, invitații sau administratori, vezi ghidul de grupuri din documentație.
Comanda 7 creează un grup cu expeditorul ca participant. 8 scrie către
config.group. Setează acel ID înainte să folosești numerele astea.Ține-l online
Lasă
node index.js să ruleze pe o mașină cu URL HTTPS publică și setează botUrl la https://hostul-tau/hook. Botul e un proces Express de lungă durată, nu o funcție serverless de un singur apel — un VPS sau orice host Node cu HTTPS e suficient. Repornește după ce schimbi botUrl ca webhook-ul să se înregistreze din nou.Pentru ca botul dvs. de chat pentru WhatsApp să fie disponibil 24/7, trebuie să fie găzduit pe o platformă de hosting de încredere. Puteți utiliza și propriul server, dar în acest capitol vom examina cele trei platforme cele mai populare - Firebase, AWS și Heroku - și vom trece prin pașii de bază pentru desfășurarea botului dvs. pe fiecare dintre ele.
Alegerea platformei depinde de preferințele, bugetul și cerințele proiectului dvs. Fiecare dintre platformele examinate oferă capacități și avantaje unice. Firebase și AWS Lambda asigură un backend puternic fără necesitatea de a gestiona un server, în timp ce Heroku oferă simplitatea de desfășurare a aplicațiilor bazate pe Git.
Firebase
Firebase oferă funcționalitatea Cloud Functions, care vă permite să rulați botul fără a fi nevoie să vă îngrijorați de infrastructura serverului. Considerăm că acesta este cea mai optimă opțiune.
- 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)
AWS Lambda oferă posibilitatea de a rula cod în răspuns la declanșatori din alte servicii AWS, ceea ce îl face o alegere bună pentru bot.
- Î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
Heroku oferă o platformă ușor de utilizat pentru găzduirea aplicațiilor, care poate desfășura automat codul din repoziția dvs. Git.
- 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.
Pașii următori
Cu botul pornit poți construi mai departe. Trimite fișiere prin URL publică; distribuie lead-uri în grupuri WhatsApp; leagă un CRM ca rezervările și comenzile să se actualizeze live; folosește sondaje în loc de butoane; publică statusuri și reacționează la mesaje; sau validează numere înainte de un broadcast. Vezi documentația sau explorează grupuri, canale, comunități, MCP, n8n, Make, agent skills și hub-ul de chatbot.
