whatsapp-web.js Nedir ve Nasıl Kullanılır?

WhatsApp otomasyonu araştıran hemen herkes eninde sonunda whatsapp-web.js ile karşılaşır. Node.js dünyasının en popüler WhatsApp kütüphanesidir; ama tam olarak ne yaptığı, neden resmi API olmadığı ve tek başına neden yeterli olmadığı çoğu zaman net değildir. Bu yazıda whatsapp-web.js'in kaputun altında nasıl çalıştığını, LocalAuth ile oturumu nasıl kalıcı tuttuğunu, hangi riskleri taşıdığını ve bizim sistemimizde ona nasıl "sürücü" rolü verdiğimizi somut olarak anlatıyoruz.

1. whatsapp-web.js tam olarak nedir?

whatsapp-web.js, WhatsApp Web'i (web.whatsapp.com) programatik olarak kontrol etmenizi sağlayan, açık kaynak bir Node.js kütüphanesidir. Kritik nokta şudur: kütüphane WhatsApp'a doğrudan bir ağ protokolüyle bağlanmaz. Bunun yerine arka planda gerçek bir Chromium tarayıcısı (Puppeteer üzerinden, çoğunlukla headless yani ekransız modda) başlatır, bu tarayıcıda WhatsApp Web sayfasını açar ve sayfanın içindeki JavaScript ile konuşarak mesaj gönderir, gelen mesajları dinler, sohbetleri okur.

Yani whatsapp-web.js aslında bir otomasyon köprüsüdür: sizin Node kodunuz ile telefonunuzdaki WhatsApp hesabının bir uzantısı olan WhatsApp Web arasında durur. Bir insan olarak WhatsApp Web'i açıp elle mesaj yazsaydınız ne oluyorsa, kütüphane de teknik olarak aynı arayüzü programatik olarak sürer.

2. Neden "gayriresmi"? Business API'den farkı

whatsapp-web.js, Meta/WhatsApp tarafından geliştirilmez, yayınlanmaz veya desteklenmez. Bağımsız bir topluluk projesidir. Bu, onu resmi WhatsApp Business API'den temelde ayırır:

Bu tabloyu ve iki yaklaşımın hangi senaryoya uyduğunu daha derinlemesine karşılaştırmak isterseniz WhatsApp Business API alternatifi yazısına göz atın. Özetle: whatsapp-web.js kolay, ücretsiz ve hızlı başlar; buna karşılık gayriresmi olduğu için sorumluluk ve risk tamamen sizdedir.

3. whatsapp-web.js nasıl çalışır? (Adım adım)

Bir gönderim döngüsü kabaca şöyle işler:

1. Client oluşturma: Kodunuzda bir Client nesnesi başlatır ve bir kimlik doğrulama stratejisi (genelde LocalAuth) verirsiniz.
2. Chromium başlatma: Kütüphane Puppeteer ile bir Chromium açar ve WhatsApp Web'i yükler.
3. QR / oturum: İlk çalıştırmada qr olayı bir QR kodu üretir; telefondan okuttuğunuzda oturum açılır. Sonraki çalıştırmalarda oturum diskten geri yüklenir.
4. Ready olayı: Bağlantı hazır olduğunda ready tetiklenir; artık gönderim yapabilirsiniz.
5. Gönderim: client.sendMessage(chatId, text) ile bir sohbete mesaj bırakırsınız. chatId genelde [email protected] biçimindedir.

Minimal bir örnek şöyle görünür:

const { Client, LocalAuth } = require('whatsapp-web.js');

const client = new Client({
  authStrategy: new LocalAuth({ dataPath: './wa-session' }),
  puppeteer: { headless: true, args: ['--no-sandbox'] }
});

client.on('qr', qr => console.log('QR okut:', qr));
client.on('ready', () => console.log('Bağlandı!'));

client.on('ready', async () => {
  await client.sendMessage('[email protected]', 'Merhaba, bu bir test mesajıdır.');
});

client.initialize();

Dikkat edin: bu kod çalışır, ama tek bir mesaj için bile herhangi bir bekleme, kuyruk veya hız kontrolü yoktur. Bin kişilik bir liste için bir döngü içine sendMessage koyarsanız kütüphane mesajları saniyeler içinde art arda fırlatır — WhatsApp'ın spam algılaması için en güçlü sinyal budur.

4. LocalAuth: oturumu kalıcı tutmak

whatsapp-web.js'in en çok işe yarayan parçalarından biri kimlik doğrulama stratejileridir. En yaygını LocalAuth'tur. LocalAuth, tarayıcı oturumunun kimlik bilgilerini (WhatsApp Web'in kendi çerez/oturum verisini) belirttiğiniz bir klasöre yazar. Böylece:

• İlk eşleşmede bir kez QR okutursunuz.
• Uygulamayı yeniden başlattığınızda kütüphane bu klasörden oturumu geri yükler; yeniden QR istemez.
• Sunucu yeniden başlasa bile oturum kalıcı olur — yeter ki o klasör korunsun.

Bu yüzden Docker ile çalışırken oturum klasörünü mutlaka bir volume'a bağlamak gerekir; aksi halde konteyner her yeniden oluşturulduğunda oturum kaybolur ve QR'ı yeniden okutmanız gerekir. Klasör silinirse ya da telefonun "Bağlı Cihazlar" ekranından oturumu kaldırırsanız yine QR'a dönersiniz.

5. Riskler ve sınırlar

whatsapp-web.js güçlüdür, ama bedava değildir — bedeli operasyonel risktir:

• Ban riski: Gayriresmi olduğu için WhatsApp'ın hizmet şartlarını zorlar. Yüksek hız, izinsiz liste veya spam benzeri davranış numaranızın kalıcı banına yol açabilir.
• Kırılganlık: WhatsApp Web arayüzü değişirse kütüphanenin belirli işlevleri geçici olarak bozulabilir; güncelleme beklemek gerekir.
• Kaynak tüketimi: Her istemci tam bir Chromium örneğidir; RAM ve CPU açısından ağırdır. Üretim için en az 2 GB RAM önerilir.
• Ölçek: Tek bir istemci tek bir numarayı sürer; birden çok numara birden çok Chromium demektir.

6. Tek başına neyi eksik? Kuyruk ve anti-ban

Bu, en çok gözden kaçan konudur. whatsapp-web.js size yalnızca "mesaj gönder" yeteneğini verir. Vermediği her şey sizin sorumluluğunuzdadır:

İşte tam da bu boşluk yüzünden "whatsapp-web.js ile bir botu 20 dakikada yazdım, sonra numaram banlandı" hikâyeleri bu kadar yaygındır. Kütüphane hız disiplinini size bırakır. Güvenli bir gönderim için kütüphaneyi bir kuyruk ve anti-ban katmanıyla sarmalamak şarttır. Hangi kuralların neden gerektiğini ban yememek için kurallar yazısında bulabilirsiniz.

7. Bu projede whatsapp-web.js'in rolü

Bizim sistemimizde whatsapp-web.js bir "sürücü" (driver) olarak konumlanır ve etrafına eksik parçalar eklenir. Mimari kabaca şöyledir:

Yani kütüphanenin ham gönderme yeteneği yalnızca en alttaki worker içinde yaşar. Oturum, bir Docker volume'una bağlı LocalAuth klasöründe kalıcıdır. Worker mesajları arasına 45–90 sn (medyada 67–135 sn) rastgele bekleme koyar, her 15 mesajda 8–12 dk mola verir, 05:00–23:00 penceresi ve aynı numaraya 4 saat cooldown uygular. Bu sayede kütüphanenin "sınırsız hızlı gönder" doğası, insan temposunu aşamayan güvenli bir akışa dönüşür.

Bu gönderme yeteneğini bir HTTP arayüzünün arkasına koyup kendi sipariş sisteminizden veya CRM'inizden tetiklemek isterseniz HTTP API entegrasyonu yazısına, kütüphaneyi kendi sunucunuzda çalıştırmanın genel resmini görmek içinse self-hosted WhatsApp mesaj sistemi yazısına bakın.

Sık sorulan sorular