WhatsApp Toplu Mesaj Gönderme Rehberi: Otomatik, Zamanlanmış ve Ban'sız — Baştan Sona Her Detay
Müşterilerinize, üyelerinize veya bağışçılarınıza WhatsApp üzerinden toplu, otomatik ve zamanlanmış mesaj göndermek istiyorsunuz. Karşınızda dört yol var; her birinin maliyeti, limiti ve riski farklı. Bu rehberde önce tüm yöntemleri karşılaştırıyor, yasal çerçeveyi (KVKK, ticari ileti, GDPR) netleştiriyor, hazır mesaj şablonları ve zamanlama stratejileri veriyoruz; ardından QR kod ile bağlanan, numaranızı banlanmaktan koruyan ve tamamen kendi sunucunuzda çalışan açık kaynak bir sistemi mimarisinden sorun gidermesine kadar her detayıyla anlatıyoruz.
1. Bu sistem nedir, kimin için?
Bu sistem; WhatsApp üzerinden otomatik, toplu ve zamanlanmış mesaj gönderimini tek bir panelden yönetmenizi sağlayan, kendi sunucunuzda çalışan (self-hosted) açık kaynak bir uygulamadır. Teknik temeli dört bileşene dayanır: tarayıcı otomasyonu için whatsapp-web.js, iş kuyruğu için BullMQ + Redis, veri katmanı için Supabase (PostgreSQL) ve yönetim paneli için React. Tamamı Docker Compose ile tek komutla ayağa kalkar.
Kimler için uygun?
- Dernekler ve vakıflar: bağışçılara makbuz bildirimi, kampanya duyurusu, kurban/ramazan dönem bilgilendirmeleri.
- Küçük ve orta ölçekli işletmeler: sipariş durumu, randevu hatırlatması, kargo bildirimi, kampanya duyurusu.
- Topluluk ve site yöneticileri: üyelere duyuru, aidat hatırlatması, etkinlik bildirimi.
- Eğitim kurumları ve kurslar: ders programı, veli bilgilendirme, kayıt hatırlatması.
- Geliştiriciler: kendi uygulamalarından HTTP API ile WhatsApp bildirimi tetiklemek isteyenler.
Önemli etik ve hukuki not: Bu sistem, sizinle iletişim kurmayı kabul etmiş kişilere bildirim göndermek için tasarlanmıştır. Satın alınmış numara listelerine istenmeyen mesaj göndermek hem WhatsApp Kullanım Şartları'nı hem de KVKK/GDPR gibi veri koruma mevzuatını ihlal eder ve numaranızın kalıcı olarak engellenmesiyle sonuçlanır. Detaylar için yasal çerçeve bölümüne bakın.
2. WhatsApp'ta toplu mesaj göndermenin 4 yolu
Piyasadaki çoğu yazı size tek bir ürünü anlatır; oysa doğru karar, dört yöntemin sınırlarını bilerek verilir:
Yöntem 1 — WhatsApp'ın yerleşik "Toplu Mesaj" (Broadcast) listesi
Normal WhatsApp ve WhatsApp Business uygulamalarında ücretsiz gelen özellik. En büyük iki kısıtı vardır: liste başına en fazla 256 alıcı ve mesajın yalnızca sizi rehberine kaydetmiş kişilere ulaşması. Küçük ve sadık bir kitle için yeterlidir; zamanlanmış gönderim, raporlama ve otomasyon yoktur.
Yöntem 2 — WhatsApp Business uygulaması
Ücretsiz Business uygulaması katalog, hızlı yanıt ve etiketleme ekler; ama toplu gönderim tarafında yine 256'lık broadcast sınırına ve rehber şartına tabidir. Otomasyon API'si yoktur; her şey elle yapılır.
Yöntem 3 — Resmi WhatsApp Business API (Cloud API)
Meta'nın kurumsal çözümü. Günde on binlerce mesaja ölçeklenir, ban riski yoktur, resmi destek vardır. Karşılığında: Meta Business doğrulaması, çoğu zaman bir BSP (çözüm ortağı) aracılığı, pazarlama mesajları için önceden onaylı şablon zorunluluğu ve konuşma başına ücretlendirme. Türkiye'de aracı firmaların paket fiyatları da eklenince orta hacimli kullanımda aylık maliyet ciddi rakamlara ulaşır.
Yöntem 4 — QR tabanlı otomasyon (bu sistem)
Telefonunuzdaki hesabı WhatsApp Web protokolüyle eşleştirip gönderimi otomatikleştirir. Başvuru yok, şablon onayı yok, mesaj ücreti yok, 256 sınırı yok, rehber şartı yok. Bedeli: WhatsApp'ın resmi desteklemediği bir gri alandır ve hız disiplini uygulanmazsa ban riski gerçektir — bu yüzden sistemin kalbi anti-ban rejimidir.
| Kriter | Broadcast listesi | Business uygulaması | Resmi API | QR tabanlı (bu sistem) |
|---|---|---|---|---|
| Alıcı sınırı | 256 / liste | 256 / liste | Yok (katmanlı limit) | Yok (hız sınırlı) |
| Rehber şartı | Var | Var | Yok | Yok |
| Mesaj ücreti | Yok | Yok | Konuşma başına | Yok |
| Zamanlanmış gönderim | Yok | Yok | BSP paneline bağlı | Var, yerleşik |
| Serbest metin | Var | Var | Şablon onayı gerekli | Var |
| Otomasyon / API | Yok | Yok | Var | Var (HTTP API) |
| Raporlama | Yok | Kısıtlı | Var | Var (panel + DB) |
| Günlük kapasite | Elle sınırlı | Elle sınırlı | 10.000+ | ~450–500 (insan hızı) |
| Ban riski | Düşük | Düşük | Yok | Var; disiplinle yönetilir |
| Veri kontrolü | — | — | BSP/Meta'da | Tamamen sizde (self-host) |
Özet karar rehberi: Günde 50'den az mesaj ve sadık kitle → broadcast yeter. Günde binlerce mesaj, kurumsal SLA → resmi API. Günde birkaç yüz bildirim, serbest içerik, sıfır mesaj maliyeti ve verinin sizde kalması → bu rehberin konusu olan QR tabanlı sistem.
3. Maliyet analizi: resmi API'ye karşı self-host
Resmi API'de iki maliyet kalemi vardır: Meta'nın konuşma başına ücreti (kategori ve ülkeye göre değişir; pazarlama konuşmaları en pahalı kalemdir) ve aracı BSP firmasının aylık panel/paket ücreti. Aylık 5.000–10.000 pazarlama mesajı gönderen bir işletme için toplam fatura kolayca üç-dört basamaklı dolar rakamlarına ulaşır.
Bu sistemin maliyet tablosu ise sabittir ve hacimden bağımsızdır:
| Kalem | Maliyet | Not |
|---|---|---|
| Yazılım | 0 ₺ | Açık kaynak |
| Sunucu (2 GB RAM VPS) | ~5–10 USD/ay | Chromium için 2 GB önerilir |
| Supabase | 0 ₺ | Ücretsiz katman bu hacme fazlasıyla yeter |
| Mesaj başına ücret | 0 ₺ | Hacim ne olursa olsun |
| Şablon onayı / başvuru | 0 ₺ / yok | Serbest içerik |
Ayda 10.000 bildirim gönderseniz bile toplam maliyetiniz sunucu kirasından ibarettir. Karşılığında ölçek tavanınız insan hızıdır (~450–500 mesaj/gün) ve ban riskini disiplinle yönetme sorumluluğu sizdedir.
4. Yasal çerçeve: KVKK, ticari elektronik ileti ve GDPR
Bu bölüm hukuki danışmanlık değildir; ancak toplu mesajlaşmaya başlamadan önce bilmeniz gereken çerçeve nettir:
4.1 Açık rıza (KVKK)
Türkiye'de kişisel veri niteliğindeki telefon numarasına pazarlama amaçlı mesaj göndermek, 6698 sayılı KVKK kapsamında açık rıza gerektirir. Rıza; özgür iradeyle, bilgilendirilmiş olarak ve belirli bir amaç için alınmalıdır. "Üyelik formunda gizli onay kutusu" geçerli rıza sayılmaz. Rızayı ne zaman, nasıl ve hangi metinle aldığınızı ispatlayabilir durumda olun.
4.2 Ticari elektronik ileti (6563 sayılı kanun)
Tanıtım, kampanya ve kutlama içerikli mesajlar "ticari elektronik ileti"dir ve alıcının önceden onayı olmadan gönderilemez. Onaylar Türkiye'de İleti Yönetim Sistemi (İYS) altyapısıyla yönetilir. İki önemli istisna: hizmet gereği bilgilendirmeler (sipariş durumu, randevu hatırlatması, teslimat bildirimi gibi) onay istisnasına girebilir ve mevcut müşteriye kendi iletişim bilgisini verdiği kanaldan yapılan bildirimlerde durum farklıdır. Kampanya mesajı ile hizmet bildirimi arasındaki bu ayrımı doğru kurun.
4.3 Çıkış hakkı (opt-out)
Her ticari mesajda alıcıya kolay bir vazgeçme yolu sunmak zorundasınız. WhatsApp'ta pratik karşılığı, mesajın sonuna tek satır eklemektir: "Bu bildirimleri almak istemiyorsanız İPTAL yazmanız yeterlidir." Gelen iptal taleplerini listenizden derhal çıkarın — hem yasa hem de ban riski açısından: sizi engelleyen ve şikâyet eden alıcı oranı, WhatsApp'ın ban kararındaki en ağır sinyaldir.
4.4 GDPR (AB alıcıları için)
Listenizde AB'de yerleşik kişiler varsa GDPR devreye girer: geçerli hukuki dayanak (çoğu pazarlama senaryosunda yine rıza), silme talebine uyma ve veri işleme kayıtları. Bu sistemin self-host olması burada avantajdır: veriler üçüncü taraf bir mesaj aracısına değil, kendi sunucunuza ve kendi Supabase projenize yazılır; veri işleyen zinciriniz kısadır.
Pratik özet: (1) Listenize yalnızca rızasını aldığınız kişileri ekleyin ve rızayı belgelendirin. (2) Kampanya ile hizmet bildirimini ayırın. (3) Her kampanya mesajına çıkış satırı ekleyin. (4) İptal isteyeni aynı gün listeden çıkarın. Bu dört kurala uyan bir gönderici hem yasal tarafta hem de ban tarafında en güvenli bölgededir.
5. Sistem mimarisi: web, server, worker, Redis, Supabase
Sistem dört Docker servisi ve bir bulut veritabanından oluşur. Görev dağılımı bilinçli olarak katıdır — her bileşen tek bir işi yapar:
web (React/nginx :8080) ──► server (Express :3200) ──► Redis (BullMQ 'whatsapp')
│ │
│ HTTP kontrol (:3100) ▼
└──────────────► whatsapp-worker (Node 20 + Chromium)
│
Supabase (notification_messages, whatsapp_web_sessions)
5.1 Web paneli (React + nginx)
Kullanıcının gördüğü tek yüzey. Dört ana ekranı vardır: Dashboard (günlük istatistikler), Yeni Gönderim (toplu/zamanlanmış mesaj oluşturma), Mesajlar (durum takibi ve iptal) ve Bağlantı (QR okutma, oturum durumu). nginx hem statik dosyaları servis eder hem de /api/ isteklerini iç ağdaki server'a proxy'ler; dışarıya açılan tek port budur.
5.2 Server (Express)
API katmanıdır ve asla kendisi mesaj göndermez. Görevleri: gelen gönderim isteğini doğrulamak, her alıcı için veritabanına queued durumunda kayıt açmak, işleri round-robin öncelikle BullMQ kuyruğuna eklemek ve QR/oturum işlemleri için worker'ın kontrol API'sine köprü olmak. Round-robin öncelik sayesinde 500 kişilik bir toplu gönderim, arkasından gelen tekil acil mesajı saatlerce bekletmez.
5.3 Worker (Node 20 + Chromium)
Sistemin tek gönderim yetkilisi. Headless Chromium içinde gerçek bir WhatsApp Web oturumu çalıştırır, kuyruğu tek tek (concurrency 1) tüketir ve tüm anti-ban zamanlamasını — bekleme, mola, saat penceresi, cooldown — kendi içinde uygular. Oturum kimliği LocalAuth ile /sessions volume'unda saklanır; container yeniden başlasa bile QR'ı tekrar okutmanız gerekmez. Kontrol API'si (port 3100) yalnızca iç ağdan, WA_CONTROL_SECRET ile erişilebilir.
5.4 Redis (BullMQ)
İş kuyruğunun yaşadığı yer. AOF (Append-Only File) kalıcılığı açık kurulur; böylece zamanlanmış işler Redis yeniden başlatıldığında kaybolmaz. Zamanlanmış mesajlar burada delay'li job olarak bekler.
5.5 Supabase (PostgreSQL)
Kalıcı kayıt defteri. notification_messages tablosu her mesajın yaşam döngüsünü tutar, whatsapp_web_sessions tablosu oturum durumunu izler. Panel tüm listelerini ve istatistiklerini buradan okur. Erişim service-role key ile sunucu tarafından yapılır; tarayıcıya asla veritabanı anahtarı inmez.
Neden bu ayrım önemli? "Kuyruğa ekleyen" (server) ile "gönderen" (worker) birbirinden tamamen ayrıldığı için hız sınırlaması tek bir noktada, worker'da yaşar. API'ye saniyede 100 istek de gelse, WhatsApp'a giden trafik hiçbir koşulda insan hızını aşamaz. Bu, anti-ban garantisinin mimari temelidir.
6. Anti-ban rejimi: numaranızı koruyan kurallar
WhatsApp, QR ile bağlanmış hesaplarda spam tespitini üç ana sinyal üzerinden yapar: hız (insanüstü tempoda gönderim), zamanlama (gece yarısı toplu mesaj) ve tekrar (aynı kişiye kısa aralıkla seri mesaj). Buna dördüncü bir sinyal eklenir: şikâyet oranı — alıcıların sizi engelleme/bildirme sıklığı. İlk üçünü sistem yönetir; dördüncüsü sizin liste kalitenize bağlıdır.
Sistemin anti-ban rejimi ve — kritik detay — tüm değerlerin koda sabit olması:
| Kural | Değer (metin) | Değer (medya) | Neyi engeller? |
|---|---|---|---|
| Mesajlar arası rastgele bekleme | 45–90 sn | 67–135 sn | Makinemsi, sabit tempolu gönderim imzası |
| Burst molası | Her 15 mesajda 8–12 dk | Her 15 mesajda 16–24 dk | Kesintisiz uzun gönderim oturumları |
| Saat penceresi | 05:00–23:00 (yerel saat) | Gece gönderimi = en güçlü spam sinyali | |
| Alıcı cooldown'u | Aynı numaraya 4 saat tekrar engeli | Aynı kişiye seri mesaj bombardımanı | |
| Efektif hız | ~25–30 mesaj/saat | Toplam hacmin insan sınırını aşması | |
Bu değerler neden ayarlanabilir değil?
Çünkü ayarlanabilir olduğu an biri onları gevşetir. Bu rejim teorik değil, yaşanmış bir ban vakasından kalibre edilmiştir: gece gönderimi + ani hacim artışı + aynı alıcıya seri mesaj kombinasyonu, hesaba 7,5 saatlik geçici blok yedirmiştir. O günden beri kural nettir: değerler anti-ban.js dosyasında sabittir, veritabanına veya arayüze taşınmaz. "Bugün acele var, beklemeyi 10 saniyeye düşürelim" cazibesine mimari olarak kapı kapatılmıştır.
Rastgelelik neden şart?
İnsanlar metronom gibi mesaj atmaz. Her mesajdan önce 45–90 saniye arasında rastgele bir değer seçilir; iki gönderim arası asla aynı olmaz. Aynı mantıkla burst molasının süresi de her seferinde 8–12 dakika aralığında rastgele belirlenir. Ortaya çıkan trafik deseni, telefonun başında oturup tek tek mesaj yazan bir insanın desenine istatistiksel olarak benzer.
Saat penceresi ve zaman dilimi
Pencere hesabı container'ın yerel saatine göre yapılır; bu yüzden TZ=Europe/Istanbul ortam değişkeni kritiktir. Yanlış zaman dilimi, pencerenin kaymasına ve farkında olmadan gece 03:00'te mesaj gönderilmesine yol açar. Pencere dışında kalan işler iptal edilmez — worker pencerenin açılmasına kalan süreyi hesaplar ve işi o kadar erteler; sabah 05:00'te kaldığı yerden devam eder.
Planlama örneği: 300 kişilik bir duyuru, saatte 25–30 mesaj hızıyla yaklaşık 10–12 saat sürer (burst molaları dahil). Sabah 08:00'de başlatırsanız akşam saatlerinde biter. Zamana yayılamayan "acil" duyurular için toplu WhatsApp doğru kanal değildir — bu gerçeği baştan kabul eden gönderici, numarasını yıllarca sorunsuz kullanır.
7. Zamanlanmış gönderim nasıl çalışır?
Yeni Gönderim ekranında bir tarih ve saat seçtiğinizde olan şudur:
- Server, her alıcı için mesajı
scheduled_atdamgasıyla veritabanına yazar. - İş, BullMQ'ya hedef zamana kadar hesaplanmış bir
delayile eklenir; Redis'te uykuya dalar. - Zaman geldiğinde iş uyanır ve normal anti-ban akışına girer: önce saat penceresi kontrol edilir, sonra alıcı cooldown'u, sonra rastgele bekleme. Yani "21:00'e planladım" demek "21:00'de tam olarak gider" değil, "21:00'den itibaren güvenli tempoda sırayla gider" demektir.
- Gönderim tamamlanınca kayıt
sentdurumuna geçer ve WhatsApp mesaj ID'si saklanır.
Planlanmış mesajlar panelde Mesajlar → Planlanmış filtresinden listelenir. İptal tek tıktır ve iki iş yapar: veritabanı kaydını cancelled'a çeker (soft-delete) ve Redis'teki bekleyen job'ı siler. Zamanı geçmiş, gönderilmiş bir mesaj doğal olarak iptal edilemez.
8. Medya (resim, video, belge) gönderimi
Sistem metin dışında resim, video ve belge de gönderir; ancak medya, WhatsApp'ın spam sınıflandırıcısı için metinden çok daha "şüpheli" bir sinyaldir. Bu yüzden medya içeren gönderimlerde tempo otomatik yarılanır: mesajlar arası bekleme 1,5 katına (67–135 sn), burst molaları 2 katına (16–24 dk) çıkar. Ayrıca büyük video yüklemelerinin ağır ağ koşullarında zaman aşımına uğrayıp çift gönderime yol açtığı gerçek bir vaka sonrası, gönderim zaman aşımı 120 saniyeye ayarlanmıştır.
Pratik öneriler: görselleri 1 MB altında tutun, videoları mümkünse link olarak paylaşın, kampanya görselini her alıcıya aynı dosyadan göndermek yerine metin ağırlıklı + tek görsel kombinasyonunu tercih edin.
9. Kullanım senaryoları ve hazır mesaj şablonları
Aşağıdaki şablonlar gerçek senaryolardan derlenmiştir; köşeli parantezli alanları kendi verinizle doldurun. Hepsinin ortak özelliği: kısa, kişisel, tek amaçlı ve çıkış satırlı.
9.1 Randevu hatırlatması (hizmet bildirimi)
9.2 Sipariş / kargo bildirimi (hizmet bildirimi)
9.3 Bağış makbuzu / teşekkür (dernek-vakıf)
9.4 Etkinlik duyurusu (kampanya — rıza gerekir)
9.5 Aidat / ödeme hatırlatması
9.6 Kampanya duyurusu (rıza + çıkış satırı zorunlu)
Şablonlarda tek kural değişmez: her alıcıya birebir aynı metni göndermek yerine en azından isim alanını kişiselleştirin. Yüzlerce alıcıya karakteri karakterine aynı mesaj, içerik parmak izi üzerinden spam sinyali üretir; [Ad] alanı bile bu imzayı kırar.
10. İçerik ve zamanlama stratejisi
10.1 İçerik yazım kuralları
- İlk cümle her şeydir: Bildirim önizlemesinde yalnızca ilk satır görünür. Amacınızı ilk 8–10 kelimede söyleyin.
- Tek mesaj, tek amaç: Aynı mesajda hem kampanya hem etkinlik hem anket olmaz. Tıklanma da okunma da düşer.
- Kısa tutun: 300–500 karakter ideal aralıktır. Uzun metin gerekiyorsa linke taşıyın.
- Link disiplinli kullanın: Her mesaja link koymayın; link kısaltıcılardan (bit.ly vb.) kaçının — bilinmeyen kısa linkler hem alıcıda hem spam filtresinde güvensizlik yaratır. Kendi domain'inizi kullanın.
- Emoji ölçülü: 1–2 emoji sıcaklık katar; her satırı emojiyle doldurmak kurumsal güveni düşürür.
- Kimliğinizi söyleyin: Alıcı numaranızı kaydetmemiş olabilir; mesajın sonunda kim olduğunuzu belirtin.
10.2 Zamanlama taktikleri
- En verimli saatler: Hafta içi 10:00–12:00 ve 14:00–18:00. Sabah 08:00 öncesi ve akşam 21:00 sonrası açılma oranı düşer, şikâyet oranı yükselir.
- Pazartesi sabahı ve pazar gününden kaçının: Mesaj yoğunluğunda kaybolursunuz ya da hafta sonu huzurunu bölersiniz.
- Büyük listeleri zamana yayın: 300+ kişilik gönderimleri sabah saatlerinde başlatın ki pencere içinde bitsin (bkz. planlama örneği).
- Tekrar sıklığı: Aynı kitleye haftada 1–2 kampanya mesajından fazlası şikâyet oranını hızla yükseltir. Hizmet bildirimleri (kargo, randevu) bu sayıma girmez.
- Zamanlanmış gönderimi kullanın: Duyuruyu gece hazırlayıp sabah 10:00'a planlamak, hem pencere kuralına uyar hem en verimli saatte teslim eder.
11. Adım adım kurulum
Gereksinimler: Docker + Docker Compose kurulu bir makine (2 GB RAM önerilir — Chromium çalışacak), ücretsiz bir Supabase projesi ve WhatsApp yüklü bir telefon. Toplam süre: ilk kurulumda ~20 dakika.
Adım 1 — Veritabanını hazırlayın
Supabase projenizin SQL Editor'ünü açın ve depodaki supabase/migrations/001_init.sql dosyasının içeriğini çalıştırın. Bu, mesaj ve oturum tablolarını, indeksleri ve durum enum'larını oluşturur.
Adım 2 — Ortam değişkenlerini doldurun
cp .env.example .env
Ardından .env dosyasını düzenleyin. REDIS_PASSWORD ve WA_CONTROL_SECRET için uzun, rastgele değerler üretin:
openssl rand -hex 32 # her secret için ayrı çalıştırın
Adım 3 — Sistemi başlatın
docker compose up -d --build
İlk build birkaç dakika sürer (Chromium bağımlılıkları indirilir). Dört servis ayağa kalkar: web, server, redis, whatsapp-worker.
İlk kurulum internet ister: worker, WhatsApp Web'in güncel sürüm HTML'ini GitHub'dan indirir. Tamamen kapalı (air-gapped) bir ağda ilk açılış başarısız olur.
Adım 4 — QR ile telefonunuzu eşleştirin
- Tarayıcıda
http://localhost:8080adresine gidin. - Bağlantı sayfasını açın ve Oturumu Başlat'a tıklayın.
- Telefonunuzda WhatsApp → Ayarlar → Bağlı Cihazlar → Cihaz Bağla yolunu izleyin ve ekrandaki QR kodu okutun.
- Durum
connectedolduğunda sistem gönderime hazırdır.
Oturum LocalAuth ile kalıcı volume'a yazıldığı için bu işlemi yalnızca bir kez yaparsınız; container yeniden başlatmaları oturumu bozmaz.
12. Ortam değişkenleri referansı
| Değişken | Zorunlu | Açıklama |
|---|---|---|
TZ | Evet | Saat penceresi hesabının temeli. Türkiye için Europe/Istanbul. Yanlışsa pencere kayar ve gece göndermeye başlarsınız. |
REDIS_PASSWORD | Evet | Redis parolası. Uzun ve rastgele olmalı. |
SUPABASE_URL | Evet | Supabase proje URL'iniz. |
SUPABASE_SERVICE_ROLE_KEY | Evet | Service role anahtarı (RLS bypass). Yalnızca sunucu tarafında kullanılır, asla tarayıcıya vermeyin. |
WA_CONTROL_SECRET | Evet | Worker kontrol API'sinin paylaşılan sırrı. Eksikse worker güvenlik gereği hiç başlamaz (fail-fast). |
WEB_PORT | Hayır | Panelin dışa açılan portu (varsayılan 8080). |
WA_MEDIA_REWRITE_HOST | Hayır | Geliştirme ortamında medya URL host'unu yeniden yazmak için. |
13. Üretim ortamı: Dokploy ile deploy
Sistem, Docker Compose destekleyen her platformda çalışır; üretimde Dokploy ile test edilmiştir. Üretim ortamında yedi kural hayati önem taşır:
- Session volume'unu koruyun.
whatsapp-sessionsvolume'u deploy'lar arasında yaşamalıdır. Silinirse veri kaybı olmaz ama telefonla yeniden QR okutmanız gerekir. - Redis kalıcılığını kapatmayın. Compose dosyası AOF açık kurar; zamanlanmış işler Redis'te yaşar. Kalıcılık kapalıysa her deploy planlanmış tüm mesajları uçurur.
- Port 3100'ü asla dışa açmayın. Worker kontrol API'si yalnızca iç Docker ağından erişilmelidir. Domain'i sadece web servisine (8080) bağlayın.
- Worker'ı yatay ölçeklemeyin. Tek replika kuralı mutlaktır: aynı LocalAuth klasörünü iki Chromium açarsa WhatsApp oturumu bozulur.
- Stop-then-start deploy stratejisi kullanın. Eski container tamamen kapanmadan (90 saniyelik grace süresi) yenisi
/sessionsklasörüne dokunmamalıdır. Rolling update bu sistemde oturum yarışına yol açar. TZ'yi doğrulayın. Container içindedateçıktısı yerel saatinizi göstermiyorsa saat penceresi yanlış çalışıyor demektir.- İlk açılışta internet erişimi olduğundan emin olun. Worker, WhatsApp Web sürüm dosyasını GitHub'dan çeker.
14. Operasyonel altın kurallar
- Gece göndermeyin — gönderemezsiniz. Saat penceresini kapatma seçeneği bilinçli olarak yoktur. Sistem 23:00'ten sonra otomatik bekler.
- Yeni numarayı yavaş ısıtın. Yeni bağlanan bir WhatsApp numarasıyla ilk günden yüzlerce mesaj göndermeyin. İlk hafta günde 20–50 mesajla başlayıp kademeli artırın; WhatsApp yeni hesap + ani hacim kombinasyonuna karşı özellikle hassastır. Mümkünse birkaç haftadır aktif kullanılan, karşılıklı yazışma geçmişi olan bir numara bağlayın.
- "Bağlantıyı Kes" logout değildir. Paneldeki kesme işlemi yalnızca istemciyi durdurur; telefonunuzdaki cihaz eşleşmesi korunur. Tamamen ayrılmak için telefondan Bağlı Cihazlar ekranını kullanın.
- Blok yerseniz durun. WhatsApp geçici blok uygularsa oturumu
banneddurumuna çekin ve gönderimi tamamen durdurun. Blok sürerken göndermeye zorlamak geçici bloğu kalıcıya çevirmenin en garantili yoludur. - Listelerinizi temiz tutun. Sizi engelleyen veya hiç yanıt vermeyen alıcılara ısrar etmeyin; şikâyet oranı ban sinyalinin en ağır bileşenidir. İPTAL yazan herkesi aynı gün çıkarın.
- Çift yönlü kullanın. Yalnızca gönderen, hiç almayan numaralar şüphelidir. Bağladığınız numarayı normal yazışmalar için de kullanmaya devam edin.
15. Ölçümleme ve raporlama
Her mesaj veritabanında bir yaşam döngüsü izler; panel bu veriyi üç düzeyde sunar:
| Durum | Anlamı | Nerede görülür |
|---|---|---|
queued | Kuyruğa alındı, sırasını/saatini bekliyor | Mesajlar → Bekleyen |
scheduled | İleri tarihli; zamanı gelince kuyruğa düşecek | Mesajlar → Planlanmış |
sent | WhatsApp'a teslim edildi, mesaj ID'si kayıtlı | Mesajlar → Gönderilen + Dashboard |
failed | Gönderilemedi; hata nedeni kayıtlı | Mesajlar → Başarısız |
cancelled | Kullanıcı tarafından iptal edildi | Mesajlar → İptal |
Takip etmeniz gereken üç metrik: başarısızlık oranı (sürekli %5 üzerindeyse liste kaliteniz düşüktür — geçersiz numaraları temizleyin), yanıt oranı (kampanyalarınızın gerçek etkisi; telefondan takip edilir) ve iptal/engelleme geri bildirimi (yükseliyorsa içerik veya sıklık yanlış). Tüm veri kendi Supabase projenizde olduğu için SQL ile istediğiniz raporu türetebilir, BI araçlarına bağlayabilirsiniz — üçüncü taraf panellerin veri kısıtlarına mahkûm değilsiniz.
16. Sorun giderme
QR kodu görünmüyor
İlk açılışta worker, WhatsApp Web sürüm dosyasını indirir; yavaş bağlantıda QR'ın üretilmesi 30–60 saniye sürebilir. Hâlâ yoksa: docker compose logs whatsapp-worker ile logları kontrol edin — internet erişimi ve WA_CONTROL_SECRET tanımlı mı?
Durum sürekli "connecting"te kalıyor
En sık neden: iki worker replikasının aynı oturum klasörünü açması (bkz. tek replika kuralı) veya yarım kalmış eski bir Chromium kilidi. Worker'ı durdurun, tek replika çalıştığından emin olun, yeniden başlatın.
Mesajlar "queued"da bekliyor, gitmiyor
Üç olası neden, sırasıyla kontrol edin: (1) Saat penceresi — 23:00–05:00 arasındaysanız sistem bilinçli bekliyordur. (2) TZ yanlış — container içinde date komutuyla saati doğrulayın. (3) Oturum kopuk — Bağlantı sayfasından durumu kontrol edin.
Oturum kendiliğinden düştü
Telefondan Bağlı Cihazlar ekranını kontrol edin; eşleşme silinmişse yeniden QR okutun. Telefon ~14 gün internete bağlanmazsa WhatsApp bağlı cihazları düşürür. Session volume'unun deploy sırasında silinmediğini de doğrulayın.
Aynı mesaj iki kez gitti
Tarihsel neden: büyük medya yüklemelerinde zaman aşımı. Güncel sürümde gönderim zaman aşımı 120 saniyedir ve bu vaka kapatılmıştır. Hâlâ görüyorsanız iki worker replikası çalışıyor olabilir — tek replikaya düşürün.
WhatsApp geçici blok uyguladı
Gönderimi tamamen durdurun, oturumu banned işaretleyin ve blok süresi bitene kadar bekleyin. Blok kalktıktan sonra ilk günler düşük hacimle (20–30/gün) yeniden ısıtın. Bloğa neyin yol açtığını düşünün: liste kalitesi mi, içerik tekrarı mı, hacim sıçraması mı?
17. API referansı: sistemi programatik kullanmak
Panel tüm işlerini şu HTTP API üzerinden yapar; kendi uygulamanızdan da aynı uçları çağırabilirsiniz:
| Uç | Metot | İşlev |
|---|---|---|
/api/dispatch | POST | Toplu veya zamanlanmış gönderim oluşturur (alıcılar, metin, medya, opsiyonel tarih). |
/api/messages | GET | Mesajları durum filtresiyle listeler. |
/api/messages/:id/cancel | POST | Bekleyen/planlanmış mesajı iptal eder. |
/api/dispatches | GET | Gönderim gruplarını listeler. |
/api/stats | GET | Günlük gönderim istatistikleri. |
/api/session/status | GET | WhatsApp oturum durumu. |
/api/session/qr | GET | Eşleştirme için güncel QR kodu. |
/api/session/start | POST | Oturumu başlatır. |
/api/session/disconnect | POST | İstemciyi durdurur (telefon eşleşmesi korunur). |
/api/health | GET | Sağlık kontrolü. |
Telefon numaraları Türkiye odaklı normalize edilir: 05xx…, 5xx… ve 905xx… biçimlerinin tümü otomatik olarak uluslararası formata çevrilir; geçersiz numaralar gönderim öncesi elenir ve failed olarak işaretlenir.
18. Sık sorulan sorular
WhatsApp'tan toplu mesaj göndermek yasal mı?
Alıcının açık rızası varsa evet. Türkiye'de ticari elektronik iletiler 6563 sayılı kanun ve KVKK kapsamındadır; alıcıdan önceden onay almanız ve her mesajda çıkış (opt-out) imkânı sunmanız gerekir. Hizmet gereği bilgilendirmeler (kargo, randevu vb.) istisna kapsamına girebilir. Detaylar için yasal çerçeve bölümüne bakın.
Bu sistem WhatsApp Business API kullanıyor mu?
Hayır. Sistem, telefonunuzdaki WhatsApp hesabını QR kod ile eşleştirerek çalışır (whatsapp-web.js). Resmi Business API başvurusu, onaylı şablon veya mesaj başına ücret gerekmez.
WhatsApp'ın kendi toplu mesaj (broadcast) özelliğinden farkı ne?
Broadcast listesi 256 kişiyle sınırlıdır ve mesaj yalnızca sizi rehberine kaydetmiş kişilere ulaşır. Bu sistemde rehber şartı ve 256 sınırı yoktur; mesajlar normal birebir sohbet olarak gider, zamanlanabilir ve panelden takip edilir.
Numaramın banlanmasını nasıl engelliyor?
Anti-ban rejimi koda sabitlenmiştir: mesajlar arası 45–90 saniye rastgele bekleme, her 15 mesajda 8–12 dakika mola, sadece 05:00–23:00 arası gönderim, aynı alıcıya 4 saat tekrar engeli ve saatte ~25–30 mesajlık gerçekçi hız. Bu değerler bilinçli olarak kullanıcı ayarı yapılmamıştır; kimse "hızlandırayım" diyerek numarayı riske atamaz.
Günde en fazla kaç mesaj gönderebilirim?
Saatte ~25–30 mesaj × 18 saatlik pencere = teorik üst sınır günde 450–500 mesaj. Pratikte yeni numaralarda ilk hafta 20–50/gün ile başlayıp kademeli artırın.
Alıcılar mesajın toplu gönderildiğini anlar mı?
Hayır. Her mesaj normal bir birebir sohbet mesajı olarak ulaşır; "toplu gönderim" etiketi yoktur. İsim kişiselleştirmesi kullanırsanız deneyim tamamen doğaldır.
Zamanlanmış (ileri tarihli) mesaj gönderebilir miyim?
Evet. Yeni Gönderim ekranında tarih ve saat seçtiğinizde iş, BullMQ'nun delay özelliğiyle ileri tarihe kurulur. Zamanı geldiğinde normal anti-ban akışıyla gönderilir; Mesajlar → Planlanmış filtresinden tek tıkla iptal edilebilir.
Telefonum kapalıyken sistem mesaj gönderebilir mi?
Evet. WhatsApp'ın çoklu cihaz mimarisi sayesinde bağlı cihazlar telefondan bağımsız çalışır. Ancak hesabın aktif kalması için telefonun yaklaşık 14 günde bir internete bağlanması gerekir.
Kurulum için neye ihtiyacım var, maliyeti ne?
Docker kurulu bir sunucu (aylık ~5–10 USD), ücretsiz bir Supabase projesi ve WhatsApp yüklü bir telefon. Yazılım açık kaynaktır; mesaj başına hiçbir ücret yoktur. Kurulum üç adımdır: SQL migrasyonunu çalıştırın, .env dosyasını doldurun, docker compose up -d --build komutunu verin.
Resim, video veya belge gönderebilir miyim?
Evet. Medya, metinden daha riskli sayıldığı için sistem tempoyu otomatik düşürür: bekleme 67–135 saniyeye çıkar, burst molası 16–24 dakikaya uzar.
Sunucu yeniden başlarsa oturum ve kuyruk kaybolur mu?
Hayır. Oturum LocalAuth ile kalıcı volume'da saklanır; yeniden QR okutmak gerekmez. Redis AOF kalıcılığı sayesinde zamanlanmış işler de yeniden başlatmadan sağ çıkar.
Mesaj gönderilemezse ne olur?
Kayıt failed durumuna geçer ve hata nedeniyle birlikte Mesajlar sayfasında görünür. Geçersiz numaralar gönderim öncesi normalize edilip elenir.
Birden fazla WhatsApp numarası bağlayabilir miyim?
Sistem tek worker + tek oturum üzerine tasarlanmıştır. Aynı oturum klasörünü iki Chromium'un açması oturumu bozar; bu yüzden worker yatay ölçeklenmez.
Bu sistemle spam göndermek güvenli mi?
Hayır ve amaç bu değildir. Sistem, kendi kitlenize (izinli listelere) insan hızında bildirim göndermek için tasarlanmıştır. İstenmeyen toplu mesaj hem WhatsApp kullanım şartlarını hem de KVKK/GDPR'ı ihlal eder ve numaranızın kalıcı olarak engellenmesine yol açar.
Sonuç
WhatsApp'ta toplu mesajın dört yolu var; doğru seçim hacminize, bütçenize ve içerik özgürlüğü ihtiyacınıza bağlı. Günde birkaç yüz bildirimlik meşru trafik için bu rehberdeki QR tabanlı sistem en pratik dengeyi sunar: React panelden yönettiğiniz, BullMQ ile kuyruklanan, tek bir disiplinli worker'ın insan hızında gönderdiği ve Supabase'de eksiksiz iz bırakan bir bildirim hattı. Kurulum üç komuttur, oturum kalıcıdır, veri tamamen sizde kalır ve anti-ban rejimi sizin adınıza "hayır" demeyi bilir. Yasal tarafta rıza + çıkış satırı + temiz liste üçlüsüne, operasyonel tarafta ısıtma + pencere + tempo disiplinine uyduğunuz sürece bu sistem numaranızı yormadan yıllarca çalışır.
Tüm Rehberler
WhatsApp toplu mesajın her konusunda ayrıntılı rehberler — bir başlık seçin: