WhatsApp Cloud API Kurulumu: Adım Adım Rehber
1 Kasım 2026 · 8 dk okuma · Read in English
WhatsApp Cloud API, Meta'nın kendi sunucularında barındırdığı ve kendi yazılımınızdan WhatsApp mesajı gönderip almanızı sağlayan resmi API'dir. Meta, On-Premises API'yi kapattığından beri (son istemci sürümünün süresi 23 Ekim 2025'te doldu) tüm entegrasyonlar Cloud API üzerinden yapılıyor. Kurulum zor değil ama üç ayrı Meta ekranına dağılmış durumda. Tek bir adımı atlamak (genellikle webhook alan aboneliği) mesaj gönderebilen ama hiç mesaj alamayan bir numarayla baş başa kalmanıza yol açar.
Bu rehber tüm akışı sırasıyla anlatıyor. Meta panel menülerinin adlarını zaman zaman değiştiriyor. Aşağıdaki etiketler Kasım 2026 itibarıyla geçerli; farklı görünen bir şey olursa resmi Get Started rehberine bakın.
Başlamadan önce gerekenler
- Bir Meta business portfolio (eski adıyla Business Manager). Uygulama kurulumu sırasında da oluşturabilirsiniz.
- Size ait, doğrulama için SMS veya sesli arama alabilen bir telefon numarası. Ülke kodu içermeli; kısa numaralar desteklenmiyor.
- Bu numara WhatsApp ya da WhatsApp Business uygulamasında kullanılıyor olmamalı. Kullanılıyorsa önce o hesabı silmeniz gerekir.
- Webhook için geçerli TLS sertifikasına sahip, internetten erişilebilen bir HTTPS adresi. Meta, self-signed sertifikaları kabul etmiyor.
1. Adım: Meta uygulamasını oluşturun
- developers.facebook.com/apps adresine gidip Create App'e tıklayın.
- Uygulama adını ve iletişim e-postasını girin.
- Connect with customers through WhatsApp kullanım senaryosunu seçip Next'e tıklayın. (Eski panellerde önce Business uygulama türü seçilir, ardından WhatsApp ürünü eklenirdi. Sonuç aynı.)
- Business portfolio'nuzu seçin ya da yenisini oluşturun, gereksinimleri gözden geçirip Create app'e tıklayın.
WhatsApp quickstart ekranına yönlendirilirsiniz. Start using the API ile API Setup sayfasını açın.
2. Adım: Phone number ID ve WABA ID'yi not alın
API Setup sayfasında uygulamayı bir WhatsApp Business Account'a bağlayın (ya da Meta'nın yeni bir tane oluşturmasına izin verin). Meta size ücretsiz bir test numarası da verir.
Bu panelden iki kimliği not alın:
| Kimlik | Ne işe yarar |
|---|---|
| Phone number ID | Gönderen numara. Her gönderim isteği /<PHONE_NUMBER_ID>/messages adresine gider. |
| WhatsApp Business Account ID (WABA ID) | Template'lerin ve faturalandırmanın bağlı olduğu hesap. Template yönetimi bu ID ile yapılır. |
Meta, dokümanlarının ve panelinin bazı bölümlerinde WABA için Messaging account adını kullanmaya başladı. Meta'ya göre mevcut WABA ID'niz artık Messaging account'u tanımlıyor ve ID değeri değişmiyor. Yani mevcut entegrasyonlar çalışmaya devam ediyor.
3. Adım: Test mesajı gönderin
API Setup'taki Generate access token düğmesi geçici bir token üretir. Bu token birkaç saat içinde geçersiz olur; yalnızca ilk test için kullanın. From alanında test numarasını seçin, To alanına kendi cep numaranızı yazın ve hello_world template'ini gönderin.
Aynı işlemi komut satırından şöyle yapabilirsiniz (panelinizde görünen güncel Graph API sürümünü kullanın):
curl "https://graph.facebook.com/v23.0/<PHONE_NUMBER_ID>/messages" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "<CEP_NUMARANIZ>",
"type": "template",
"template": { "name": "hello_world", "language": { "code": "en_US" } }
}'
Telefonunuzdan mesaja cevap verin. Bu, 24 saatlik müşteri hizmetleri penceresini açar. Serbest metinli (template olmayan) mesajları yalnızca bu pencere açıkken gönderebilirsiniz. Ayrıntılar için 24 saat penceresi ve fiyatlandırma yazımıza bakabilirsiniz.
4. Adım: Gerçek numaranızı ekleyip kaydedin
API Setup'ta Add phone number'ı kullanın ya da WhatsApp Manager → Account tools → Phone numbers bölümüne gidin. Bir görünen ad (display name) girin, ardından numarayı SMS veya sesli aramayla gelen kodla doğrulayın.
Cloud API'de bir numaranın mesaj gönderebilmesi için ayrıca kaydedilmesi (register) gerekir. Meta bunu yalnızca API üzerinden yapmaya izin veriyor:
curl -X POST "https://graph.facebook.com/v23.0/<PHONE_NUMBER_ID>/register" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "pin": "123456" }'
pin, numaranın altı haneli iki adımlı doğrulama PIN'idir. İki adımlı doğrulama zaten açıksa mevcut PIN'i girin; kapalıysa gönderdiğiniz PIN numaranın yeni PIN'i olur. Meta, numara başına 72 saatlik kayan pencerede 10 kayıt isteğine izin veriyor. Sınırı aşarsanız 133016 hatasını alır ve 72 saat boyunca engellenirsiniz. Bu yüzden bu çağrıyı otomatik yeniden deneme döngüsüne koymayın.
5. Adım: Kalıcı system user token oluşturun
Kullanıcı token'larının süresi dolar. Sunucu entegrasyonu için system user token'ı kullanın:
- Business Settings → System users bölümünü açın, Add'e tıklayın, kullanıcıya bir ad verin ve Admin ya da Employee rolünü seçin. Employee rolünde her hesaba erişimi tek tek vermeniz gerekir; daha kısıtlı olan seçenek budur.
- Assign assets'e tıklayın, uygulamanızı seçin ve Manage app (tam yetki) verin.
- WhatsApp hesabını da system user'a atayın. Meta, devralınan erişime güvenmek yerine her hesabın açıkça atanmasını öneriyor.
- Generate token'a tıklayın, uygulamanızı seçin, bir süre (expiration) ayarı belirleyin ve şu izinleri işaretleyin:
whatsapp_business_messaging(mesaj gönderme ve alma)whatsapp_business_management(template'ler, numaralar, hesap bilgileri)business_management(Meta'nın güncel rehberinde yer alıyor)
- Token'ı hemen kopyalayın ve gizli bir değer olarak saklayın.
Bu sırada App settings → Basic bölümünden App secret'ı da kopyalayın. Webhook imzalarını doğrulamak için kullanacaksınız.
6. Adım: Webhook'u yapılandırın
Gelen mesajlar ve teslim durumları size webhook ile ulaşır. App Dashboard'da WhatsApp → Configuration (ya da Use cases → Customize → Configuration) bölümünü açın ve Webhook altında Edit'e tıklayın. İki değer girersiniz:
- Callback URL: herkese açık HTTPS adresiniz.
- Verify token: sizin belirlediğiniz gizli bir metin. Sunucunuzun da bu değeri bilmesi gerekir.
Verify and save'e tıkladığınızda Meta; hub.mode=subscribe, hub.verify_token ve hub.challenge parametreleriyle bir GET isteği gönderir. Sunucunuz token'ı kontrol etmeli ve yanıt gövdesinde challenge değerini geri döndürmelidir. En basit PHP örneği:
// PHP, $_GET içinde "hub.mode" adını "hub_mode" yapar
if (($_GET['hub_mode'] ?? '') === 'subscribe'
&& hash_equals(getenv('WA_VERIFY_TOKEN'), $_GET['hub_verify_token'] ?? '')) {
echo $_GET['hub_challenge'];
exit;
}
http_response_code(403);
Bundan sonra Meta'nın gönderdiği her olay, X-Hub-Signature-256 başlığı taşıyan bir POST isteğidir. Başlık sha256= ile başlar ve ham gövdenin App secret ile hesaplanmış HMAC değerini içerir. Meta doğrulamanın zorunlu olmadığını ama yapılması gerektiğini söylüyor:
$expected = 'sha256=' . hash_hmac('sha256', file_get_contents('php://input'), getenv('WA_APP_SECRET'));
$valid = hash_equals($expected, $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '');
Hızlıca HTTP 200 döndürün, ağır işleri sonra yapın. 200 dışında bir yanıt verirseniz Meta 7 güne kadar yeniden dener. Bu da aynı olayın birden fazla gelmesine yol açabilir; mesaj ID'sine göre tekrarları ayıklayın.
7. Adım: "messages" alanına abone olun
En sık atlanan adım budur. Aynı Configuration sayfasında Webhook fields bölümünü bulun ve messages alanına abone olun (Subscribe). Bu alan hem kullanıcıların size gönderdiği mesajları hem de sizin gönderdiğiniz mesajların durum güncellemelerini taşır. Abone olmazsanız doğrulama başarılı görünür ama hiçbir olay gelmez.
Ardından telefonunuzdan işletme numaranıza bir WhatsApp mesajı gönderin. Sunucunuza "object": "whatsapp_business_account" ve "field": "messages" içeren bir payload gelmesi gerekir.
Sık karşılaşılan kurulum sorunları
| Belirti | Olası neden |
|---|---|
| "Callback URL or verify token couldn't be validated" | Adres herkese açık HTTPS değil, sertifika geçersiz ya da self-signed, veya sunucu hub.challenge değerini geri döndürmüyor |
| Webhook doğrulandı ama olay gelmiyor | messages alanına abone olunmamış |
| Gönderimde 190 hatası | Access token'ın süresi dolmuş. System user token'a geçin |
| 133010 hatası | Numara kaydedilmemiş (4. adım) |
| 131047 hatası | 24 saat penceresi dışında serbest metin gönderilmiş. Template kullanın |
Tam liste için WhatsApp Cloud API hata kodları rehberimize göz atın.
Çok müşterili bir platformda bu kurulum
Birden fazla müşteri için WhatsApp mesajlaşması yönetiyorsanız her müşteri 1-5. adımları kendi business portfolio'su ve numarasıyla yapar. Böylece Meta ücretleri doğrudan müşterinin kendi hesabına yansıtır. Sizin platformunuz yalnızca ID'leri, token'ı ve App secret'ı saklar; 6. adım için müşteriye callback URL ve verify token değerlerini verir.
Mesvilo da bu şekilde çalışıyor. Müşteri, çalışma alanında WhatsApp → Connect number bölümüne Phone number ID, Business Account ID, token ve App secret değerlerini yapıştırır. Mesvilo, Meta'ya girilecek callback URL ve verify token'ı gösterir; webhook çalışmaya başladığında sağlık kontrolleri yeşile döner. Müşterilerinizle paylaşabilmeniz için aynı adımlar dokümantasyonda da yazılı.
Bağlantı ekranını ve beslediği gelen kutusunu görmek için canlı demoyu deneyebilir ya da ürün sayfasına göz atabilirsiniz.
Kaynaklar
Kendi WhatsApp platformunu işlet
Mesvilo; ortak gelen kutusu, şablonlar, kampanyalar ve abonelik faturalamasıyla kendi sunucunda çalışan bir WhatsApp Cloud API SaaS’ı.