Özet: Genel erişime açık bir HTTPS endpoint oluşturun, bunu Whapi.Cloud webhook'unuz olarak kaydedin; sunucunuz her WhatsApp olayını JSON POST olarak alacaktır. Mantığı yönlendirmek için type alanını kontrol edin, ardından yanıt vermek üzere to ve body ile POST /messages/text çağrısı yapın. Bu iki adımlı döngü — olayı al, tepkiyi gönder — bu kılavuzdaki her entegrasyonun temelidir. Metin mesajı yönlendirmesiyle başlayın; kullanım senaryonuz büyüdükçe koşullu dallar ekleyin.
Temel İlke: Olay → Tepki
WhatsApp API entegrasyonu, bir mesajlaşma SDK'sı değil, olay odaklı bir yapıdır. WhatsApp'ta bir şey olduğunda Whapi.Cloud webhook aracılığıyla sunucunuzu bildirir, kodunuz tepkiye karar verir ve API bunu gerçekleştirir.
Sıra sabittir. Bir kullanıcı WhatsApp numaranıza mesaj gönderir. Whapi.Cloud bu olayı yakalar ve webhook URL'nize JSON payload içeren bir HTTP POST gönderir — kim gönderdi, ne tür mesaj, içerik. Sunucunuz payload'ı okur, iş mantığını uygular ve yanıt göndermek, CRM kaydını güncellemek ya da sonraki eylemi tetiklemek için Whapi.Cloud REST API'sini çağırır. Döngü, sonraki her olay için tekrar eder.
Kodunuz hiçbir zaman polling yapmaz — Whapi.Cloud her WhatsApp olayını gerçekleştiği anda webhook'unuza iletir. İş mantığınızın yanıtladığı tek soru şudur: bu olay göz önüne alındığında, bundan sonra ne olur?
Teslim bildirimleri, emoji tepkileri, düğme tıklamaları, grup üyelik değişiklikleri ve çağrı olayları hepsi webhook tetikler — gelen metin sekiz olay türünden biridir. Tam taksonominin iş kararlarıyla eşleştirilmesi, çalışan bir entegrasyonu yarım kalmış olandan ayırır. Stripe webhook'larına veya Twilio callback'lerine aşina geliştiriciler bu deseni hemen tanıyacaktır.
Resmi API Yerine Neden Gateway Kullanılır?
Whapi.Cloud, web oturumu soketleri aracılığıyla bağlanır. Bir QR kodu tarayın ve dakikalar içinde ilk mesajınızı gönderin — Meta doğrulaması veya şablon onayı gerekmez.
Resmi WhatsApp Business Platformu, tek bir proaktif mesaj göndermeden önce iş doğrulaması, BSP entegrasyonu ve önceden onaylanmış mesaj şablonları gerektirir. Whapi.Cloud, konuşma başına ücret olmaksızın sabit abonelik ücretidir. 3.300'den fazla geliştirme ekibi onu birden fazla ülkede üretimde kullanmaktadır.
Gerçek bir dezavantaj: Whapi.Cloud, Meta tarafından resmi olarak onaylanmamıştır; bu durum, resmi uyumluluk belgesi gerektiren düzenlenmiş sektörler için önem taşır. E-ticaret, destek botları, İK araçları ve CRM senkronizasyonu için engelleyici bir kısıt değildir. Başlangıç kılavuzu, ilk API çağrınızdan önce yapmanız gerekenleri kapsar.
WhatsApp Olay Taksonomisinin Tamamı
Her olay kategorisi, yönlendirme mantığınızın ele alması gereken ayrı bir iş kararı sınıfına karşılık gelir — ve tam taksonomi, çoğu geliştiricinin ilk entegrasyondan önce beklediğinden daha geniştir.
Whapi.Cloud tarafından teslim edilen her olay aynı dış yapıyı paylaşır: webhook'unuza, olay kategorisini tanımlayan bir type alanı içeren JSON POST. İşleyiciniz önce type üzerine dallanır, ardından o kategoriye özgü alt alanları çıkarır.
| Olay Kategorisi | Spesifik Olay Türleri | Tipik İş Tepkisi |
|---|---|---|
| Gelen mesaj | text, image, audio, video, document, sticker, location, contact card | AI işleyicisine yönlendir, CRM'e ilet, otomatik yanıt ver, konuşmayı etiketle |
| Etkileşimli etkileşim | button reply, quick reply, list selection, template response | Konuşma durum makinesini ilerlet, siparişi onayla, backend eylemini tetikle |
| Emoji tepkisi | reaction added, reaction removed | Duygu puanını kaydet, takibi tetikle, memnuniyet metriğini güncelle |
| Mesaj durumu | sent, delivered, read, played (voice note) | CRM teslimat alanını güncelle, yeniden etkileşim zamanlayıcısını iptal et, takip dizisini tetikle |
| Çağrı olayı | incoming call initiated, call missed, call rejected | Cevapsız çağrıyı kaydet, otomatik geri arama talep mesajı gönder |
| Grup olayı | participant joined, participant left, admin changed, group created/archived | Üyelik listesini güncelle, hoş geldiniz mesajı gönder, İK sistemiyle senkronize et |
| Etiket olayı | label applied to chat, label removed | CRM'de kişiyi segmentle, kampanyayı tetikle, boru hattı aşamasını güncelle |
| Kanal olayı | follower joined channel, channel update published | Abone onayı gönder, analitiği senkronize et, bildirim iş akışını tetikle |
Yönlendirme kuralı her satırda tutarlıdır: type alanını okuyun, eşleşen işleyiciye dallanın, o türe özgü alt alanları çıkarın. Bir "image" mesajı, "button_reply" etkileşiminden farklı bir işleyici gerektirir — ikisi de aynı webhook URL'sine POST isteği olarak gelir, ancak payload yapısı ve iş mantığınız tamamen farklıdır.
Entegrasyon Yolları
Sunucu kodu yazsanız da görsel bir iş akışı aracı yapılandırsanız da her entegrasyon aynı olay→tepki döngüsünü izler — yalnızca araçlar değişir.
| Yaklaşım | Teknik Gereksinim | İlk Mesaja Kadar Süre | En Uygun Olduğu Durum |
|---|---|---|---|
| REST API (Python / Node.js / PHP) | HTTP istemcisi, genel URL ile herhangi bir backend | ~30 dakika | Özel iş mantığı, AI chatbot'lar, CRM bağlayıcıları |
| Make (yerel Whapi.Cloud modülü) | Yalnızca Make hesabı | ~10 dakika | Geliştirici olmayanlar, pazarlama otomasyonu ekipleri |
| n8n (kendi sunucusunda veya bulutta) | n8n örneği (Docker veya bulut) | ~15 dakika | Self-hosted iş akışı kontrolü isteyen teknik ekipler |
| cURL / Postman | Araçların kendisi dışında hiçbir şey | ~5 dakika | Endpoint testi, kavram kanıtı |
Make ve n8n kullanıcıları, özel bir backend'in alacağı JSON payload'ını alan bir webhook tetikleyici node yapılandırır. Node'lar daha sonra olay alanlarını okur ve tepki olarak Whapi.Cloud'un gönder endpoint'ini çağırır. Olay→tepki modeli değişmez; iş mantığı kod yerine görsel bir canvas'ta yaşar.
Webhook Kurulumu: Alıcı Taraf
Whapi.Cloud'da webhook kurulumu üç girdi gerektirir: endpoint URL'niz, almak istediğiniz olay türleri ve istek doğrulama için isteğe bağlı bir gizli anahtar. Endpoint, HTTPS üzerinden genel erişime açık olmalıdır.
Webhook'u Whapi.Cloud kanal ayarlarınızın içinde yapılandırın. Kaydedildikten sonra Whapi.Cloud, WhatsApp olaylarını JSON gövdeli HTTP POST istekleri olarak URL'nize iletmeye başlar. Olaylar gerçek zamanlı olarak ulaşır — genellikle WhatsApp eyleminden birkaç yüz milisaniye içinde. Yapılandırılacak bir polling aralığı yoktur ve tarafınızdan sürdürülecek kalıcı bir bağlantı yoktur. Webhook payload formatı referansının tamamı, işleyicinizin ayrıştırması gereken her alanı belgeler.
Geliştirme sırasında ngrok, yerel bir portu genel bir HTTPS URL'sine açar. Bu URL'yi geçici webhook'unuz olarak ayarlayın, işleyicinizi yerel olarak çalıştırın ve bir sunucu dağıtımına geçmeden önce canlı payload'ları inceleyin.
İşlemeden önce HTTP 200 döndürün. Bu isteğe bağlı değildir. Whapi.Cloud, endpoint'iniz zaman aşımı süresi içinde yanıt vermezse teslimatı yeniden dener. İsteği hemen onaylayın, payload'ı bir arka plan thread'ine veya görev kuyruğuna aktarın ve eş zamansız olarak işleyin. Onaylama ve işlemeyi aynı senkron yolda karıştırmak, mantığınız yavaş olduğunda yinelenen olaylara neden olur.
Webhook'tan Yanıta: Çalışan Bir Kod Örneği
HTTP istemcisi olan herhangi bir dil — Python, Node.js, PHP, Go — aynı şekilde entegre olur. Özel SDK yok, yüklenecek sarmalayıcı yok. Aşağıdaki işleyici, gelen mesajları yönlendirir ve POST /messages/text aracılığıyla yanıt gönderir.
from flask import Flask, request, jsonify
import requests
import threading
app = Flask(__name__)
WHAPI_TOKEN = "your_channel_token" # from panel.whapi.cloud/dashboard
WHAPI_URL = "https://gate.whapi.cloud/messages/text"
def send_reply(to: str, body: str) -> None:
# Calls sendMessageText — required: to (chat ID), body (message text)
requests.post(
WHAPI_URL,
headers={"Authorization": f"Bearer {WHAPI_TOKEN}"},
json={"to": to, "body": body}
)
def process_event(data: dict) -> None:
for msg in data.get("messages", []):
if msg.get("from_me"):
continue # skip outbound confirmations
sender = msg.get("chat_id") # e.g. "[email protected]"
msg_type = msg.get("type", "")
if msg_type == "text":
text = msg.get("text", {}).get("body", "").lower()
if any(w in text for w in ["hello", "hi", "hey"]):
send_reply(sender, "Hey! How can I help you today?")
elif "price" in text or "pricing" in text:
send_reply(sender, "Check our pricing: https://whapi.cloud/price")
elif "order" in text:
send_reply(sender, "Please share your order number and we'll check its status.")
else:
send_reply(sender, "Thanks! Our team will get back to you shortly.")
elif msg_type == "image":
send_reply(sender, "Got your image — our team will review it.")
elif msg_type == "button_reply":
btn_id = msg.get("button_reply", {}).get("id", "")
send_reply(sender, f"You selected: {btn_id}. Processing your request...")
elif msg_type == "reaction":
# Reactions carry sentiment data — log them, don't reply by default
emoji = msg.get("reaction", {}).get("text", "")
msg_id = msg.get("reaction", {}).get("msg_id", "")
print(f"Reaction {emoji} on message {msg_id} from {sender}")
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.get_json()
# Acknowledge immediately — never block on processing
threading.Thread(target=process_event, args=(data,)).start()
return jsonify({"status": "ok"}), 200
if __name__ == "__main__":
app.run(port=5000)Dört yönlendirme dalı görünür: selamlama anahtar kelimeleriyle karşılama, satın alma niyetinde fiyat teklifi, sipariş sorgularında açıklama isteme, duygu analizi için tepkileri kaydetme. Aynı koşullu yapı yüzlerce dala ölçeklenir — ya da tüm if/elif zincirini bir LLM çağrısıyla değiştirin. Webhook işleyicisinin kendisi aynı kalır. Celery kuyruğu ile üretim dağıtım adımları için Python WhatsApp bot kılavuzuna bakın.
Gerçek bir dağıtımda, arka plan thread'ini bir görev kuyruğuyla değiştirin (Celery, RQ veya bir bulut kuyruk hizmeti) yeniden deneme garantileri ve yatay ölçekleme için. Webhook onayı ve iş mantığı ayrı tutulmalıdır — bu sınır, her ölçekli entegrasyondaki temel mimari karardır.
Ayrı Olay Girişleri Olarak Etkileşimli Mesaj Türleri
Düğme yanıtları, liste seçimleri ve hızlı yanıtlar, ayrı payload yapılarına sahip farklı olay türleridir. Her biri, kodunuzda kendi yönlendirme dalını gerektirir.
Bir kullanıcı WhatsApp etkileşimli mesajındaki bir düğmeye dokunduğunda, Whapi.Cloud bir button_reply olayı iletir. Payload, mesajı oluştururken atadığınız düğme kimliğini içerir, görünür etiket metnini değil. Yönlendirme mantığınız kimliği kontrol eder, etkileşimli akışları deterministik hale getirir — kullanıcı ifadesinden bağımsız olarak yanlış dal yanlışlıkla tetiklenmez.
Tipik değerlendirmeler:
-
button_reply:
button_reply.id'yi çıkarın — düğme mesajını oluştururken ayarladığınız programatik kimlik. Herhangi bir metin ayrıştırması olmaksızın eşleşen işleyiciye yönlendirin. -
list_reply: Hem
list_reply.idhem delist_reply.title'ı çıkarın — kimlik mantığı yürütür, başlık kullanıcıya geri gönderilen onay mesajlarında kullanışlıdır. -
reaction:
reaction.text'i (emoji karakteri) vereaction.msg_id'yi (hangi mesaja tepki verildiği) çıkarın. Duygu kaydına eşleyin veya konuşmayı kesmeden hafif bir memnuniyet sinyali olarak kullanın. -
Durum güncellemeleri: Her durum olayı,
statuses[].status'u"sent","delivered"veya"read"olarak taşır. CRM alanınızı güncelleyin, yeniden etkileşim zamanlayıcısını iptal edin veya durum geçişlerine dayalı bir takip dizisi başlatın.
Okundu bildirimleri, yalnızca teslimat kaydı değil, davranışsal verilerdir. Fiyat mesajınızı akşam 21:00'de okuyan ancak yanıt vermeyen bir aday, CRM'inize bir şey söylüyor. Durum olaylarını veri katmanınıza yönlendirin — bunlar filtrelenecek gürültü değil, üzerine harekete geçilecek sinyallerdir.
WhatsApp'ta AI Chatbot Mimarisi
Webhook ile API yanıtı arasına yerleştirilen bir LLM, WhatsApp numarasını bir AI ajanına dönüştürür. Mimarinin üç katmanı vardır. Orta katman, çoğu ekibin chatbot'un tutarlı mı yoksa bozuk mu hissettireceğini belirleyen kararı aldığı yerdir.
Birinci katman: Whapi.Cloud gelen mesajı webhook'unuza iletir. İkinci katman: sunucunuz konuşma geçmişini kalıcı depolamadan alır, yeni mesajı ekler, tam konuşma bağlamıyla LLM API'sini çağırır ve yanıtı Whapi.Cloud aracılığıyla geri gönderir. Üçüncü katman: LLM sağlayıcısı — OpenAI, Anthropic veya Gemini — ham webhook payload'ı değil, hazırlanmış bir bağlam penceresi alır.
Çoğu ekibin küçümsediği katman depolama alanıdır. Konuşmalar durumludur — geçmişi chat_id ile anahtarlı olarak kalıcı hale getirin, her LLM çağrısından önce son 15-20 turun bağlamını sınırlayın. Kalıcı depolama olmadan, AI her mesajı konuşma yeni başlamış gibi okur.
İnsan devri ikinci kritik desendir: hiçbir AI konuşmaların %100'ünü doğru şekilde çözmez. Sohbeti bir insan ajana yönlendiren açık bir eskalasyon tetikleyicisi oluşturun — bir anahtar kelime eşleşmesi, güven puanı eşiği veya konuşma turu sınırı. Konuşmayı CRM'inizde işaretleyin, ajana bildirin ve isteğe bağlı olarak kullanıcıya bir onay mesajı gönderin. Webhook'unuz devir sırasında mesaj iletmeye devam eder; yönlendirme mantığı yalnızca işleyiciyi AI'dan insan kuyruğuna değiştirir.
Whapi.Cloud'un GitHub deposu, depolama, yönlendirme ve API çağrı mantığı önceden yazılmış olarak bu üç katmanlı deseni uygulayan Python ve Node.js bot şablonları içerir. Klonlayın, token ve LLM kimlik bilgilerinizi yapılandırın ve çalıştırın.
Farklı Sektörlerde İş Kullanım Senaryoları
Olay→tepki döngüsü, WhatsApp'ın aktif bir iletişim kanalı olduğu her sektörde aynı şekilde uygulanır — yalnızca içindeki iş mantığı değişir.
-
E-ticaret: Satın alma olayında sipariş onayı, hareketsizlik zaman aşımında terk edilen sepet hatırlatıcısı, teslimat-yanıt oranını ölçmek için okundu bilgisi takibi.
-
Sağlık klinikleri, kabul formları için düğme yanıtı menüleri kullanır, randevu hatırlatıcılarını 24 saat ve 2 saat önce tetikler ve yanıt olmadan okundu bilgisi geldiğinde gelmeme takibi gönderir.
-
Gayrimenkul: Gelen sorgulama, düğme yanıtları aracılığıyla bütçe ve konuma göre AI kısa listesi tetikler, nitelikli adaylar aynı olay üzerinde otomatik olarak oluşturulan CRM kaydıyla ajan kuyruğuna yönlendirilir.
-
İK ve dahili operasyonlar için vardiya programları grup mesajı olarak gönderilir, çalışan onayı okundu durumu üzerinden takip edilir ve işe alım belgeleri İK sistemi tetikleyici olaylarından otomatik olarak iletilir.
Üretim Değerlendirmeleri
Dört karar, bir entegrasyonun gerçek trafik altında dayanıp dayanmayacağını belirler. İşlemeden önce onaylayın ve mesaj kimliğine göre yinelenenleri kaldırın — bunlardan birini atlarsanız bazı olayları iki kez işlersiniz.
-
İşlemeden önce onaylayın. Hemen HTTP 200 döndürün. İş mantığını bir arka plan thread'ine veya görev kuyruğuna taşıyın. Whapi.Cloud zaman aşımında yeniden dener — onaylama ve işlemeyi aynı senkron yolda karıştırmak yinelenen olaylar üretir.
-
Mesaj kimlikleri, yinelenenleri kaldırma anahtarınızdır. İşlenen her kimliği kısa TTL ile saklayın (Redis iyi çalışır) ve aynı olay iki kez geldiğinde yeniden işlemeyi atlayın. Ağ koşulları, güvenilir altyapıdan bile zaman zaman yinelemeler iletir.
-
Yeni numaralarda giden gönderimlerin hızını kontrol edin. Whapi.Cloud üretim kanallarının sabit API hız limitleri yoktur. Risk, WhatsApp'ın sunucu taraflı spam algılamasıdır — yakın zamanda etkinleştirilen numaralarda ani hacim artışları yaptırım çeker. Yeni bir numaradan büyük listelere gönderim yaparken mesajlar arasında makul gecikmelerle bir gönderim kuyruğu uygulayın.
-
AI chatbot oturumları, ilk günden itibaren üç ayar gerektirir:
chat_idile anahtarlı geçmiş, her LLM çağrısından önce son 15-20 tura sınırlı bağlam ve yapılandırılabilir bir hareketsizlik penceresinden sonra süresi dolan oturumların temizlenmesi. Bunlardan herhangi birini atlarsanız üretimde bağlam taşması veya eski durum hataları ayıklarsınız.
Whapi.Cloud'un altyapısı, WhatsApp protokol güncellemelerini otomatik olarak ele alır — WhatsApp yeni bir istemci sürümü yayınladığında entegrasyonunuz bozulmaz. Numara ısıtma ve güvenli gönderim desenleri hakkında rehberlik için güvenli mesajlaşma kılavuzu, WhatsApp yaptırımını gerçekten tetikleyen davranışları kapsar.
Whapi.Cloud Üzerinde Geliştirme Yapan Ekipler Ne Diyor?
"Whapi.Cloud, müşteri iletişimimizin temel bir parçası haline geldi. Meta şablonlarına veya onaylarına ihtiyaç duymadan ürün güncellemelerini, sipariş bildirimlerini ve destek mesajlarını otomatikleştirdik."
— Oscar T., CTO
"n8n kullanarak WhatsApp'ı birkaç dakika içinde iş akışlarımıza bağladık. Kod yok, komplikasyon yok — her şey ilk denemede çalıştı."
— Martin P., Geliştirici
"Her şey sade, sezgisel ve kolay kullanılır. Belgeler açık ve ihtiyacım olan tüm bilgiler ekranda."
— Roberto K., Web Geliştirici
Geliştiriciler iş mantığını yazar; Whapi.Cloud WhatsApp teslimatını yönetir. Bu ayrım, mimarinin ölçeklenebilir olmasını sağlayan şeydir — yönlendirme kodunuz, protokol karmaşıklığı gateway tarafında kaldığından 5 dolarlık bir VPS'te veya konteynerleştirilmiş bir kümede aynı şekilde çalışır. Her iş olayını bir WhatsApp tepkisiyle eşleştirin: mimari işte budur.
