WhatsApp Cloud API Nedir? Meta Cloud API Kurulum ve Entegrasyon Rehberi
Meta tarafından barındırılan resmî WhatsApp arayüzü. Sunucu kurulumu olmadan mesaj gönderin, webhook ile alın; şablon ve limit yönetimini doğru kurgulayın.
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "905551112233",
"type": "template",
"template": {
"name": "siparis_bilgilendirme",
"language": { "code": "tr" }
}
}
// Cloud API, Meta tarafından barındırılır — sunucu kurulumu gerekmez
WhatsApp Cloud API, Meta'nın kendi sunucularında barındırdığı resmî WhatsApp Business Platform arayüzüdür; işletmeler sunucu kurulumu yapmadan HTTP istekleriyle mesaj gönderip webhook üzerinden mesaj alabilir. Kullanımdan kaldırılmakta olan On-Premises kurulumun yerini almıştır.
WhatsApp Cloud API nedir?
WhatsApp Cloud API, Meta'nın kendi sunucularında barındırdığı resmî WhatsApp Business Platform arayüzüdür. İşletmeler ve geliştiriciler, kendi altyapılarına herhangi bir WhatsApp sunucusu kurmadan, doğrudan Meta'nın uç noktalarına HTTP istekleri göndererek mesaj gönderip alabilir.
Adındaki "Cloud" tam olarak bunu anlatır: barındırma yükü Meta'dadır. Daha önce yaygın olan On-Premises (şirket içi) kurulumda işletmenin kendi sunucusuna bir WhatsApp Business API istemcisi kurulur, güncellemeler ve ölçekleme kendi ekibinin sorumluluğunda olurdu. Meta bu modeli kullanımdan kaldırma yönünde ilerledi ve Cloud API'yi standart yol olarak konumlandırdı.
Geliştirici açısından pratik anlamı şudur: bir erişim jetonu (access token), bir telefon numarası kimliği (phone number ID) ve HTTPS isteği atabilen herhangi bir dil yeterlidir. Kurulum, sunucu bakımı, sertifika yönetimi gibi başlıklar ortadan kalkar.
Cloud API, Business API, WaMessage API — hangisi ne?
Bu üç kavram sıkça karıştırılır. Ayrım şöyledir:
| Kavram | Nedir? | Kim kullanır? |
|---|---|---|
| WhatsApp Business Platform | Meta'nın kurumsal WhatsApp altyapısının genel adı | İşletmeler (ürün olarak) |
| WhatsApp Cloud API | Bu altyapıya Meta'nın bulutu üzerinden erişilen teknik arayüz | Geliştiriciler, entegratörler |
| WaMessage Geliştirici API'si | WaMessage panelinin kendi API'si; WhatsApp ve SMS'i tek arayüzden yönetir | WaMessage müşterisi geliştiriciler |
Kısaca: Cloud API Meta'nın teknik kapısıdır; WhatsApp Business API sayfası işletme tarafındaki ürün ve süreci anlatır; WaMessage Geliştirici API'si ise WaMessage üzerinden gönderim yapmak isteyen yazılımcılar içindir.
Cloud API ile On-Premises farkı
| Ölçüt | Cloud API | On-Premises API |
|---|---|---|
| Barındırma | Meta'nın sunucularında | İşletmenin kendi sunucusunda |
| Kurulum | Sunucu kurulumu yok | Docker/sunucu kurulumu gerekir |
| Güncelleme | Meta tarafından otomatik | Ekip tarafından manuel |
| Ölçekleme | Meta yönetir | Kapasite planlaması gerekir |
| Yeni özellikler | Önce burada yayınlanır | Gecikmeli veya hiç |
| Güncel durum | Standart yol | Kullanımdan kaldırılma yönünde |
Yeni bir proje planlıyorsanız tercih nettir: Cloud API. On-Premises kurulumu olan işletmelerin ise geçiş planını ertelememesi, yeni özelliklere erişim ve destek sürekliliği açısından önemlidir.
Cloud API nasıl çalışır?
Cloud API, REST mantığıyla çalışır. Temel kavramlar şunlardır:
Kimlik ve yetkilendirme
- Access token: İsteklerin kimliğini doğrular. Kalıcı jetonlar sistem kullanıcıları üzerinden üretilir; süreli jetonlar yalnız test için uygundur.
- Phone Number ID: Mesajın hangi işletme numarasından gideceğini belirler.
- WABA ID: WhatsApp Business Account kimliği; şablonlar ve numaralar bu hesaba bağlıdır.
Mesaj gönderimi
Gönderim, ilgili uç noktaya JSON gövdeli bir POST isteğiyle yapılır. Mesaj türüne göre gövde değişir: metin, medya (görsel, video, belge), etkileşimli düğmeler, liste veya şablon. İşletme konuşmayı başlatıyorsa şablon mesaj kullanılması zorunludur; şablonun önceden Meta onayından geçmiş olması gerekir. Yandaki örnek, onaylı bir şablonun Türkçe diliyle gönderimini gösterir.
Webhook ile mesaj alma
Gelen mesajlar ve durum bildirimleri (gönderildi, iletildi, okundu, hata) webhook üzerinden sisteminize iletilir. Bunun için herkese açık bir HTTPS uç noktası tanımlanır, doğrulama jetonuyla eşleşme sağlanır ve gelen olaylar işlenir. Webhook'un hızlı yanıt vermesi önemlidir; ağır işlemler kuyruğa alınmalı, uç nokta hemen 200 dönmelidir.
Şablonlar
Şablonlar; kategori (pazarlama, hizmet, kimlik doğrulama), dil ve değişken alanlarıyla tanımlanır. Onay süreci ve kategori seçimi hem gönderim iznini hem maliyeti etkiler. Ayrıntı için şablon mesajlar sayfasına bakabilirsiniz.
Cloud API kurulumu: adım adım
Doğrudan Cloud API mi, sağlayıcı üzerinden mi?
Cloud API'yi doğrudan kullanmak teknik olarak mümkündür ve küçük projelerde makuldür. Ancak üretim ortamında birkaç başlık, sanılandan çok daha fazla iş çıkarır:
| Konu | Doğrudan Cloud API | WaMessage üzerinden |
|---|---|---|
| Kurulum ve doğrulama | Kendiniz yürütürsünüz | Tech Provider olarak WaMessage yürütür |
| Ekip kullanımı | Kendi panelinizi yazmanız gerekir | Hazır ortak gelen kutusu |
| Şablon yönetimi | API üzerinden manuel | Panelden yönetim ve takip |
| Kampanya ve liste | Kendi altyapınız | Hazır toplu gönderim ve raporlama |
| Chatbot / CRM | Ayrı geliştirme | Panel içinde hazır |
| Hata ve limit yönetimi | Kendi izleme sisteminiz | İzleme ve destek dahil |
Karar kuralı basittir: mesajlaşma sizin ürününüzün çekirdek özelliğiyse ve özel bir deneyim kuruyorsanız doğrudan Cloud API mantıklıdır. Amacınız satış, destek ve bilgilendirme süreçlerini yürütmekse, hazır panel ve ekip araçlarıyla gelen bir platform üzerinden ilerlemek hem hızlı hem toplam maliyeti düşük olur. WaMessage her iki yaklaşımı da destekler: panelden yönetin ya da geliştirici API'miz üzerinden kendi yazılımınızdan tetikleyin.
Üretim ortamı için dikkat edilecekler
- Jeton güvenliği: Erişim jetonunu sunucu tarafında saklayın; mobil uygulama veya tarayıcı koduna gömmeyin. Sızan jeton, numaranız adına mesaj gönderilmesine yol açar.
- Webhook dayanıklılığı: Uç noktanız kısa sürede yanıt vermeli; işlemleri kuyruğa alın. Yanıt gecikirse Meta tekrar deneme yapar ve mükerrer işlem riski doğar.
- Yeniden deneme ve idempotans: Aynı olayın iki kez gelebileceğini varsayın; mesaj kimliğine göre tekilleştirme yapın.
- Limit yönetimi: Gönderim limitleri hesabın kalite puanına ve doğrulama durumuna göre değişir. Ani hacim artışlarında kademeli ilerleyin.
- Kalite puanı: Şikâyet ve engelleme oranı arttığında limitler düşer. İzinli liste ve doğru kategori seçimi bu nedenle teknik bir konu kadar önemlidir.
- Hata yönetimi: Hata kodlarını sınıflandırın; geçici hatalarda tekrar deneyin, kalıcı hatalarda kaydı işaretleyip ekip bildirimine düşürün.
- Ücretlendirme takibi: Meta 1 Temmuz 2025'ten itibaren mesaj başına ücretlendirme uygular. Kategori bazında adet takibi yapmadan maliyet öngörüsü sağlıklı olmaz; hesaplayıcıyı kullanabilirsiniz.
Entegrasyonda en sık karşılaşılan sorunlar
Cloud API entegrasyonunda karşılaşılan sorunların büyük kısmı birkaç başlıkta toplanır. Aşağıdaki liste, geliştirme sırasında zaman kaybettiren tipik durumları ve nedenlerini özetler.
Mesaj gitmiyor ama hata da dönmüyor
İstek 200 dönüyor fakat mesaj ulaşmıyorsa ilk bakılacak yer webhook'tan gelen durum bildirimleridir. Mesajın "sent" olup "delivered" olmaması, alıcı tarafındaki bir engellemeye veya numaranın WhatsApp'ta kayıtlı olmamasına işaret eder. Durum olaylarını kaydetmeyen sistemlerde bu ayrım görülemez; bu nedenle gönderim kaydı kadar durum kaydı da tutulmalıdır.
24 saat kuralı ve şablon zorunluluğu
Müşteri size yazdıktan sonra belirli bir süre serbest metinle yanıt verebilirsiniz. Bu süre dışında serbest metin gönderimi reddedilir; onaylı şablon kullanmanız gerekir. "Neden bazı mesajlarım gidiyor, bazıları hata veriyor" sorusunun en yaygın cevabı budur. Uygulamanızda bu ayrımı otomatik yapan bir kontrol bulunması, hem hata sayısını hem gereksiz şablon maliyetini azaltır.
Şablon onayı reddediliyor
Reddin en sık nedenleri: yanlış kategori seçimi (pazarlama içeriğinin utility olarak gönderilmesi), değişken alanların bağlamsız bırakılması ve promosyon dilinin hizmet şablonunda kullanılmasıdır. Şablon metnini müşteriye gerçekten gönderilecek hâliyle yazmak ve örnek değerleri eksiksiz doldurmak onay şansını belirgin biçimde artırır.
Kalite puanı düşüyor, limitler daralıyor
Engellenme ve şikâyet oranı arttığında Meta gönderim limitinizi düşürür. Bu teknik bir sorun gibi görünse de kaynağı içerikseldir: izinsiz listeye gönderim, alakasız kampanya ve aşırı sıklık. Limit düşüşü yaşandığında çözüm istek sayısını artırmak değil, gönderim listesini ve içerik stratejisini gözden geçirmektir.
Jeton süresi doldu
Geliştirme sırasında üretilen geçici jetonlar kısa sürede geçersiz olur ve üretimde ani kesintiye yol açar. Üretim ortamında sistem kullanıcısı üzerinden kalıcı jeton kullanılmalı, jeton bir sır yönetimi çözümünde saklanmalı ve kod deposuna hiçbir koşulda yazılmamalıdır.
Webhook doğrulaması başarısız
Uç noktanızın HTTPS olması, geçerli bir sertifika sunması ve doğrulama isteğine beklenen değeri döndürmesi gerekir. Yerel geliştirmede tünel araçları kullanılabilir; ancak üretimde sabit ve erişilebilir bir adres tanımlanmalıdır. Ayrıca gelen isteklerin gerçekten Meta'dan geldiğini doğrulamak için imza kontrolü yapılması önerilir.
Merak edilenler
WhatsApp Cloud API nedir?
Meta'nın kendi sunucularında barındırdığı resmî WhatsApp Business Platform arayüzüdür. İşletmeler kendi sunucularına kurulum yapmadan, HTTP istekleriyle mesaj gönderip alabilir.
Cloud API ile On-Premises API arasındaki fark nedir?
Cloud API Meta tarafından barındırılır, kurulum ve güncelleme gerektirmez, yeni özellikler önce burada yayınlanır. On-Premises kurulum işletmenin kendi sunucusunda çalışır ve kullanımdan kaldırılma yönünde ilerlemektedir.
Cloud API ücretsiz mi?
Arayüzün kullanımı için ayrı bir lisans ücreti yoktur; ödeme, gönderilen mesajlar üzerinden Meta tarifesine göre yapılır. Meta 1 Temmuz 2025'ten itibaren mesaj başına ücretlendirme uygulamaktadır.
Cloud API kullanmak için yazılımcı gerekir mi?
Doğrudan kullanmak için evet: jeton yönetimi, webhook ve şablon süreçleri geliştirme gerektirir. WaMessage gibi bir platform üzerinden ilerlerseniz panel ve hazır araçlarla yazılım geliştirmeden kullanabilirsiniz.
WhatsApp Cloud API Türkiye'de kullanılabilir mi?
Evet. Türkiye'deki işletmeler Meta işletme doğrulamasını tamamlayarak Cloud API üzerinden gönderim yapabilir. WaMessage, Meta Tech Provider olarak bu süreci yürütür.
Cloud API ile toplu mesaj gönderebilir miyim?
Evet, ancak işletme tarafından başlatılan gönderimlerde onaylı şablon kullanımı ve izinli alıcı listesi zorunludur. Gönderim limitleri hesabınızın doğrulama durumu ve kalite puanına göre değişir.
Cloud API'yi kendiniz yönetmek yerine WaMessage üzerinden kullanın.
Kurulum, doğrulama, şablon onayı ve limit yönetimini biz yürütelim; siz panelden yönetin ya da geliştirici API'miz üzerinden kendi yazılımınızdan tetikleyin.
Not: Cloud API, Meta'nın altyapısıdır ve kuralları Meta tarafından belirlenir. WaMessage, Meta Tech Provider olarak başvuru, kurulum ve şablon süreçlerini yürütür.