WhatsApp API Entegrasyonu 2026 | Güncel Doküman ve Postman

WhatsApp entegrasyonu, herkese açık bir API'ye kayıt olmakla değil, doğrulanmış bir WhatsApp Business API hesabıyla başlar. Meta işletme doğrulaması ve numara bağlama tamamlandığında API anahtarınız (X-Api-Key) VatanSMS tarafından teslim edilir — anahtarın neden satın alınamadığını API key rehberinde anlattık. Hesabınız yoksa WhatsApp Business API nasıl alınır rehberiyle başlayın; kurulum sürecini Türkiye'den Meta teknik partneri olarak VatanSMS yürütür.

Müşteri son 24 saat içinde size yazdıysa gönderilebilir. Serbest metin ve medya içerir, Meta onayı gerektirmez. Uç nokta: message/send .

24 saat penceresi gerektirmez ; ilk temas ve kampanyalar için kullanılır. Şablonun önceden Meta onayından geçmesi şarttır. Uç nokta: template/send .

Pazarlama içerikli şablon gönderimlerinde alıcının opt-in vermiş olması gerekir — ayrıntılar reklam mesajı rehberinde .

WhatsApp API ile mesaj göndermenin en basit hâli: aktif oturuma düz metin. business_device_id (cihaz ID'si, int) veya phone_number_id (string) alanlarından biri zorunludur; ikisi birden gönderilirse business_device_id esas alınır.

curl ile aynı istek:

Aynı message/send uç noktası, multipart/form-data ile medya taşır: params alanına JSON metni, medya alanına dosya eklenir. Seçtiğiniz message_type ile doldurduğunuz dosya alanı eşleşmelidir.

Onaylı şablonu tek alıcıya veya listeye gönderir; 24 saat penceresi gerektirmez. Bu uç noktada business_device_id , Meta'nın phone_number_id değeridir (string). Şablon değişkenleri recipients[].params.body ile doldurulur; değişken yoksa params: {} bırakılır.

Hız kontrolü: requests_per_minute (dakika başına istek) veya complete_in_seconds (toplam tamamlanma süresi) alanlarından birini kullanın; kullanmadığınızı 0 bırakın. Başlığı medya içeren şablonlarda dosyayı multipart/form-data ile ekleyebilirsiniz; dosya eklenmezse şablonun varsayılan medyası kullanılır.

Başarılı yanıt, kampanyayı kuyruk bilgisiyle döner (alıcı sayısı kaç olursa olsun format aynıdır):

Kısmi başarı: Kara listedeki alıcılar gönderim dışında bırakılır; kampanya yine oluşur, atlananlar skipped_count ve warnings ile bildirilir:

Yeni şablon POST /template ile oluşturulur ve Meta onayına gider — onaylanana kadar gönderimde kullanılamaz. Şablon adı küçük harf ve alt çizgiden oluşur (ör. kampanya_ismi ); kategori MARKETING , UTILITY veya AUTHENTICATION olabilir.

Başarılı yanıtta şablon, PENDING (Meta onayı bekliyor) durumuyla döner:

Aynı adla ikinci şablon oluşturulamaz — 409 Conflict ve DUPLICATE_TEMPLATE hatası döner. Onay sürecinde ret yememek için şablon onay rehberindeki kurallara göz atın.

Tüm yanıtlar aynı zarf yapısını kullanır: success (true/false), status (HTTP kodu), message ve başarılı isteklerde data . Hatalarda errors dizisi hangi alanın hangi kuralı ihlal ettiğini söyler; kampanya kısmi başarıyla oluştuğunda ise warnings dizisi atlanan alıcıları listeler.

Gönderdiğiniz kampanyaları GET /campaigns ile listeler, dönen campaign_id ile GET /campaigns/:id/reports üzerinden gönderim ve teslim raporunu çekersiniz. Böylece entegrasyonunuz yalnızca göndermekle kalmaz, sonucu da kendi sisteminize işler.

Tüm uç noktaları hazır istekler hâlinde içeren koleksiyonu indirin, Postman'e aktarın ve ilk mesajınızı kod yazmadan test edin:

Üç adımda: önce WhatsApp Business API hesabınız kurulur (Meta doğrulaması ve numara bağlama), ardından API anahtarınız (X-Api-Key) teslim edilir, son olarak yazılımınız bu sayfadaki uç noktalara HTTP istekleri gönderecek şekilde bağlanır. Postman koleksiyonunu indirip ilk isteğinizi birkaç dakikada test edebilirsiniz.

Aktif bir WhatsApp Business API hesabı, API anahtarı ve alıcıyla iletişim hakkı gerekir: müşteri son 24 saat içinde size yazdıysa serbest oturum mesajı gönderilir; bu pencerenin dışında yalnızca Meta onaylı şablonla mesaj gönderilebilir. Pazarlama içerikli gönderimlerde alıcının opt-in vermiş olması şarttır.

API standart HTTPS + JSON kullandığı için HTTP isteği atabilen her dille çalışır: PHP, Python, C#, Java, JavaScript/Node.js, Go ve diğerleri. Özel bir SDK zorunluluğu yoktur; bu sayfadaki curl örneklerini kendi dilinize birebir çevirebilirsiniz.

API anahtarı, WhatsApp Business API kurulumunuz tamamlandığında VatanSMS tarafından teslim edilir. Anahtar hesabınızın imzasıdır: koda gömüp herkese açık depolara yüklemeyin, şüphe hâlinde destek ekibinden yeniletin.

Hayır, iki ayrı API'dir. SMS gönderimi XML tabanlı SMS API ile, WhatsApp gönderimi bu sayfadaki JSON tabanlı WhatsApp Business API ile yapılır. İki kanalın raporları da kendi API'lerinden alınır; panelde ise ikisi tek arayüzden yönetilir.

API hesabınız yoksa kurulumu Türkiye'den Meta teknik partneri olarak VatanSMS yürütür; anahtarınız teslim edildiğinde bu sayfadaki örneklerle dakikalar içinde ilk mesajınızı gönderirsiniz.