Boilerplate’i atlayın: çalışan bir botu klonlayın
Bu rehber Whapi.Cloud GitHub deposundaki açık kaynak botu kullanır. Gönderme, alma, medya, kişiler, ürünler ve gruplar zaten var. Yazının geri kalanı nasıl ayağa kaldıracağınızı anlatır.
Bu chatbotun scripti, küçük ve orta ölçekli işletmeler tarafından sıkça kullanılan temel fonksiyonları içerir ve çoğu görevi kapsar:
- Normal mesaj gönderme;
- Medya gönderme: resim / dosya / video;
- Kontak gönderme (vCard ziyaret kartı);
- Ürün gönderme;
- WhatsApp grubu oluşturma;
- Gruba davet gönderme;
- WhatsApp grubuna mesaj gönderme;
- Gelen mesajları alıp işleme;
- Bilinmeyen bir komut için yanıt verme (menüler, talimatlar veya karşılama mesajları için).
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
Klonladıktan sonra proje klasörüne girin:
cd nodejs-whatsapp-chatbot
package.json içindeki paketleri kurun:
npm install
Chatbot’un çalışması için gereken bağımlılıklar böyle iner.
Proje yapısı
- /files — botun gönderebileceği örnek medya (görsel, PDF, video, vCard). İsteyince değiştirin.
- config.js —
token,botUrl,portve isteğe bağlıgroup/productID’leri. - index.js — webhook’u kaydeder,
/hook/messagesdinler, 1–9 sayılarını eylemlere map’ler.
WhatsApp numaranızı bağlayın
Whapi.Cloud, Meta’dan bağımsız bir WhatsApp HTTP ağ geçididir. Elinizdeki herhangi bir numarayı kullanır, panelde QR tarar ve Bearer token alırsınız. Meta Business doğrulaması yok; Cloud API şablon veya mesaj penceresi limitleri de yok.
Botun çalışması için telefonun çevrimiçi kalması gerekmez. Numarayı panelde bir kez bağlayın, botu herhangi bir sunucuda çalıştırın. Yardım için sitedeki destek sohbetini kullanın.
Hesabınızdaki QR kodu tarayın
Kayıt. İlk adım Whapi.Cloud sitesinde hesap açmak. Ücretsizdir, kart istemez.
Kayıttan hemen sonra düşük kotalı bir deneme kanalınız olur. Açılmasını bekleyin (genelde bir dakika). Telefonu bağlamanız gerekir: mesajlar bu numaradan çıkar. Avantajı birkaç dakikada işe koyulmanız.
Telefonu bağlamak için hesabınızdaki deneme kanalına tıklayınca çıkan QR’ı kullanın. Telefondaki WhatsApp’ta: Ayarlar -> Bağlı cihazlar -> Cihaz bağla -> QR kodu tarayın.
Sihirbazdaki kanal adı ve webhook ekranlarını atlayabilirsiniz — bot webhook’u başlangıçta kendi ayarlar.
Artık test ve endpoint çağrıları için API token’ınız var. Saklayın, birden fazla kez kullanacaksınız. Kanal kartından kopyalayıp
config.js içine token olarak yapıştırın. https://gate.whapi.cloud istekleri Bearer gider.
Botu başlatmadan önce
- Kanal token’ı
config.jsiçine yapıştırıldı. - Test için ikinci bir telefon: bot bağlı numaradan gelen mesajları yok sayar.
- Genel HTTPS URL. Yerelde ngrok; üretimde HTTPS’li herhangi bir host.
Bota genel bir HTTPS URL verin
Webhook, bağlı WhatsApp hesabında bir şey olduğunda Whapi.Cloud’un botunuza gönderdiği mesajdır: yeni metin, durum değişikliği, grup daveti.
«Yeni mesaj var mı?» diye tekrar tekrar sormak yerine betiğiniz olay olur olmaz POST alır.
Örnek: A kişisi «merhaba» yazar -> Whapi.Cloud sunucunuzdaki
/hook/messages adresine JSON POST eder -> bot komutu okur ve yanıtlar. URL’yi panele yapıştırmazsınız; bot açılışta config.js’ten kaydeder.Whapi.Cloud gelen mesajları genel HTTPS URL’inize POST atarak iletir. Bu URL’yi panele yapıştırmazsınız.
config.js içinde botUrl olarak yazın; repo ayağa kalkınca kanal ayarları API’siyle kaydeder.ngrok ile yerel tünel
config.js içindeki varsayılan port 80’dir (443 kullanmayın). ngrok’u indirin ve ngrok http 80 çalıştırın — ya da config.js’te verdiğiniz portu.https:// yönlendirme URL’sini kopyalayın. botUrl’i o host artı /hook yapın, örneğin botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook".
/hook sonekini koruyun. Sunucu POST’ları /hook/messages üzerinde dinler; botUrl kanal ayarlarına yazılan önektir.node index.js çalışınca bot bu URL ve messages olayıyla PATCH /settings gönderir. WhatsApp mesajları sürecinize gelir. Kayıt edileni görmek istemiyorsanız paneldeki webhook alanlarını yok sayabilirsiniz.Üretimde ne gerekir
Host internetten HTTPS ile ulaşılabilir olmalı, Node süreci POST kabul etmek için ayakta kalmalıdır.
botUrl değişirse webhook’u yeniden kaydetmek için botu yeniden başlatın.Botu başlatın
config.js içinde token ve botUrl’i doğrulayın, proje kökünden node index.js çalıştırın. Listening log’unu görmelisiniz. Başka bir telefondan bağlı numaraya herhangi bir metin gönderin. Bot numaralı menüyle cevaplar.Komut menüsü
- Basit metin mesajı
- Görsel gönder
- Belge gönder
- Video gönder
- Kişi gönder
- Ürün gönder
- Grup oluştur
- Gruba basit metin
- Üç grubunuzun id’lerini al
Sadece sayıyı gönderin, örneğin 1. Başka her şey bu listeyi tekrar döner.
6 ve 8 komutları
config.js içindeki product ve group alanlarını kullanır. İlk testte atlayın. Gerektiğinde ID’leri GET /groups ve GET /business/products ile listeleyin.Sorun giderme
Bot cevap vermiyor
Başka telefondan yazın — betik
from_me’yi atlar. Token’ı, botUrl’in /hook ile bittiğini, ngrok (veya host) hâlâ ayaktaysa ve sürecin listening mesajını yazdırdığını kontrol edin.Bot mesaj döngüsüne giriyor
if (message.from_me) continue kalsın. Olmazsa bot kendi mesajlarına cevap verir ve durmaz.Bazı sohbetlerde çalışıyor, bazılarında değil
Sandbox aktif konuşmaları sınırlar (şu an ayda 5). Altıncı sohbet, plan yükseltmeden veya kota sıfırlanmadan cevap almaz.
Node.js’ten WhatsApp mesajı gönderin
Klonlanan bot zaten gönderir, alır, medya, kişiler, ürünler, gruplar ve fazlasını yapar. Aşağıdaki parçalar içerideki aynı HTTP kalıbıdır: Bearer token ile
https://gate.whapi.cloud adresine fetch.Metin mesajı gönder
Sohbete veya gruba düz metin gönderin:
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);
Belge gönder
Genel URL veya base64 yüküyle belge gönderin:
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);
Türlerin ve payload’ların tam listesi API referansında.
WhatsApp gruplarıyla çalışmak
Bot katıldığınız grupları listeler ve grup mesajlarına tepki verir. Bu örnekler aynı Bearer’ı ve
/groups endpoint’ini yeniden kullanır.Gruplarınızı listeleyin
Bağlı numaraya görünen grupları çekin:
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);
Her grup nesnesinde ad, fotoğraf, açıklama ve katılımcı dizisi vardır.
Grup üyelerini sayın
Diziyi dönerek her grubun adını ve üye sayısını yazdırın:
groups.forEach(group => {
console.log(`Group Name: ${group.name}`);
console.log(`Participants: ${group.participants.length}`);
});
Grup mesajlarını işleyin
Grup sohbet ID’leri
@g.us ile biter. Gelen webhook’lar aynı soneki kullanır; klonlanan bot bir komut grubu hedeflediğinde zaten burada dallanır.
// Klonlanan bottan: grup mesajları @g.us ile biten chat_id kullanır
const messages = req.body.messages;
messages.forEach(message => {
if (message.chat_id.endsWith('@g.us')) {
console.log(`Group message: ${message.text?.body}`);
}
});
Grup oluşturma, davet ve yönetici işlemleri için belgelerdeki grup rehberine bakın.
Komut 7, göndereni katılımcı alan bir grup oluşturur. 8,
config.group adresine yazar. Bu numaraları kullanmadan önce o ID’yi tanımlayın.Çevrimiçi tutun
node index.js sürecini genel HTTPS URL’si olan bir makinede çalışır bırakın ve botUrl’i https://sizin-host/hook yapın. Bu bot tek atımlık serverless fonksiyon değil, uzun ömürlü bir Express sürecidir — VPS veya HTTPS’li herhangi bir Node host yeter. botUrl değişirse webhook’u yeniden kaydetmek için yeniden başlatın.WhatsApp chat-bot'unuzun 24/7 kullanılabilir olması için güvenilir bir hosting platformunda barındırılması gerekir. Kendi sunucunuzu kullanabilirsiniz, ancak bu bölümde, botunuzu her birinde nasıl dağıtacağınıza dair temel adımlarla birlikte en popüler üç platform olan Firebase, AWS ve Heroku'yu ele alacağız.
Platform seçimi, tercihlerinize, bütçenize ve projenizin gereksinimlerine bağlıdır. İncelenen her platform, Firebase ve AWS Lambda'nın sunucu yönetimi gerektirmeyen güçlü bir backend sağlaması, Heroku'nun ise Git tabanlı uygulama dağıtımlarının kolaylığını sunması gibi kendi benzersiz olanaklarını ve avantajlarını sunar.
Firebase
Firebase, sunucu altyapısıyla ilgilenmenize gerek kalmadan botunuzu çalıştırmanıza olanak tanıyan Cloud Functions özelliğini sunar. Bize göre, bu en iyi seçenektir.
- Firebase Console'da bir proje oluşturun;
- talimatları takip ederek Firebase CLI yükleyin;
- Proje dizininizde firebase init komutu ile Firebase'i başlatın;
- Botunuzu firebase deploy --only functions komutu kullanarak dağıtın.
AWS (Amazon Web Services)
AWS Lambda, AWS'nin diğer hizmetlerinden tetiklemelerle kod çalıştırma olanağı sağladığı için botlar için iyi bir seçenektir.
- AWS Yönetim Konsolu'na kaydolun veya giriş yapın;
- AWS konsolu üzerinden API Gateway tetikleyici olarak seçilerek yeni bir Lambda fonksiyonu oluşturun;
- Botunuzun kodunu Lambda fonksiyonuna yükleyin;
- Botunuzun dış dünya ile etkileşimde bulunması için API Gateway'i yapılandırın.
Heroku
Heroku, uygulamalarınızı barındırmak için kullanıcı dostu bir platform sunar ve Git reposundan kodunuzu otomatik olarak dağıtabilir.
- Heroku'da bir hesap oluşturun;
- Heroku CLI yükleyin ve sisteme giriş yapın;
- Konsol üzerinden veya heroku create komutunu kullanarak Heroku'da yeni bir uygulama oluşturun;
- Git reposunu Heroku ile ilişkilendirin ve git push heroku master komutları ile dağıtım yapın;
- Heroku tarafından sağlanan web kancası URL'sini ayarlayın.
Sonraki adımlar
Bot ayaktayken üzerine inşa edebilirsiniz. Genel URL ile dosya gönderin; gelen lead’leri WhatsApp gruplarına dağıtın; rezervasyon ve siparişlerin anında güncellenmesi için CRM bağlayın; buton yerine anket kullanın; durum yayınlayıp mesajlara tepki verin; veya toplu gönderimden önce numaraları doğrulayın. Belgelere bakın ya da gruplar, kanallar, topluluklar, MCP, n8n, Make, agent skills ve chatbot hub’ını gezin.
