WhatsApp Business API Entegrasyonu Nasıl Yapılır?

WhatsApp Business API entegrasyonu, kendi yazılımınızın (e-ticaret siteniz, CRM’iniz, ERP’niz ya da yönetim paneliniz) WhatsApp üzerinden otomatik mesaj göndermesini ve gelen mesajları işlemesini sağlayan bağlantıdır. WhatsApp Business uygulamasından farkı şudur: API’nin arayüzü yoktur, telefona kurulmaz; doğrudan sistemlerinize bağlanır, aynı numarayı sınırsız temsilci kullanabilir ve mesajlar sipariş, randevu ya da tahsilat verinizden tetiklenir. Kurulum dört adımdan oluşur: Meta Business hesabının doğrulanması, numaranın kaydı, mesaj şablonlarının onaya gönderilmesi ve gelen mesajlar için webhook bağlanması. Bu yazıda entegrasyonun teknik akışını, Cloud API–BSP tercihini, canlıda en çok kırılan 24 saat kuralını ve maliyetin gerçekte nasıl hesaplandığını anlatıyoruz.

WhatsApp Business API nedir, uygulamadan farkı ne?

Meta’nın WhatsApp için üç ayrı ürünü var ve karıştırılmaları maliyetli oluyor. WhatsApp Business uygulaması küçük işletmeler için ücretsiz bir telefon uygulamasıdır; tek cihazda çalışır, mesajları insan yazar. WhatsApp Business Platform (API) ise bir arayüz değil, bir servistir: mesajı sizin yazılımınız gönderir, gelen mesajı sizin sunucunuz alır. Üçüncüsü, API’nin üstüne oturan hazır panellerdir (BSP çözümleri) — teknik ekibi olmayan işletmeler için pratik bir kısayol.

• Kim mesajı gönderir? Uygulamada temsilci elle yazar; API’de sipariş durumu, randevu saati ya da ödeme kaydı gibi bir olay mesajı tetikler.
• Kaç kişi kullanabilir? Uygulamada bir telefon + sınırlı bağlı cihaz; API’de aynı numara üzerinden istediğiniz kadar temsilci ve otomasyon.
• Hacim: Uygulamada toplu gönderim pratikte imkânsızdır (ve numaranızı riske atar); API’de gönderim limiti kalite puanınıza bağlı olarak kademeli yükselir.
• Veri: Uygulama telefonda yaşar, veriniz orada kalır; API’de tüm konuşma geçmişi kendi veritabanınıza akar ve CRM’inizle birleşir.
• Ücret: Uygulama ücretsizdir; API’de mesaj başına Meta tarifesi (ve BSP kullanıyorsanız onun payı) ödenir.

Basit kural: müşteriyle konuşmayı hâlâ bir kişi yürütüyorsa uygulama yeter. Mesaj bir yazılımdan doğuyorsa — “kargonuz yola çıktı”, “yarın 14.00 randevunuz var”, “ödemeniz alındı” — API’ye ihtiyacınız var. Bu, API entegrasyonu nedir yazımızda anlattığımız sistemler arası konuşmanın WhatsApp’a bakan yüzüdür.

Cloud API mı, BSP mi? Doğru başlangıç kararı

Eskiden API’yi kullanmak için mutlaka bir iş ortağı (BSP) gerekiyordu; Meta’nın Cloud API’sinden sonra bu zorunluluk kalktı. Cloud API, Meta’nın kendi sunucularında barındırılan resmî uç noktadır: doğrudan Graph API üzerinden çağırırsınız, ayrı bir altyapı ücreti yoktur, yalnızca mesaj ücretini ödersiniz. BSP’ler ise API’nin üzerine temsilci paneli, kampanya arayüzü, raporlama ve destek ekler.

• Cloud API doğrudan: Yazılım ekibiniz varsa en ucuz ve en esnek yol. Mesajlar kendi sisteminizden çıkar, veriniz sizde kalır, aracı payı ödemezsiniz.
• BSP üzerinden: Teknik ekibiniz yoksa ya da çağrı merkezi tarzı bir temsilci paneline ihtiyacınız varsa mantıklı. Karşılığında mesaj başına ek pay ve platform aboneliği ödersiniz.
• Karma model: Otomatik bildirimleri (sipariş, kargo, randevu) kendi yazılımınızdan Cloud API ile gönderip, insan destek trafiğini hazır bir panele bırakmak çoğu KOBİ için en dengeli kurulumdur.

Karar verirken tek soruyu netleştirin: WhatsApp sizin için bir bildirim kanalı mı, yoksa bir destek kanalı mı? Bildirimse Cloud API yeter; destekse panel gerekir. İkisi de gerekiyorsa karma modeli kurun, çünkü tek numarayı hem panele hem kendi yazılımınıza bağlamak sonradan zahmetlidir.

Kurulum adımları: hesaptan ilk mesaja

• 1. Meta Business hesabı ve işletme doğrulaması: Vergi levhası, ticaret sicil kaydı ve alan adı sahipliği ile şirketinizi doğrulatın. Doğrulama tamamlanmadan gönderim limitleri düşük kalır ve şirket adının görünmesi mümkün olmaz.
• 2. Numara seçimi ve kaydı: API’ye bağlanacak numara, hâlihazırda bir WhatsApp ya da WhatsApp Business hesabına bağlı olmamalıdır. Kullanımdaki bir numarayı taşıyacaksanız önce eski hesabı silmeniz gerekir; sabit hat numarası da (sesli doğrulama ile) kullanılabilir.
• 3. Görünen ad (display name) onayı: Müşterinin ekranında çıkacak isim Meta tarafından incelenir ve markanızla tutarlı olmalıdır. “Kampanya Merkezi” gibi genel adlar reddedilir.
• 4. Şablon mesajların onaya gönderilmesi: Müşteriye ilk siz yazacaksanız kullanacağınız her metin önceden onaylanmalıdır. Onay genelde dakikalar–saatler sürer.
• 5. Webhook bağlantısı: Gelen mesajların ve teslim durumlarının düşeceği HTTPS uç noktasını tanımlayın. Bu adım atlanırsa mesaj gönderirsiniz ama gelen cevabı asla göremezsiniz.
• 6. Kalıcı erişim anahtarı ve test: Sistem kullanıcısı üzerinden süresiz token üretin, geçici token ile canlıya çıkmayın; entegrasyon 24 saat sonra sessizce durur.

24 saat kuralı, entegrasyonların canlıda en sık kırıldığı yerdir: Müşteri size yazdıktan sonraki 24 saat boyunca serbest metinle (görsel, dosya, buton) cevap verebilirsiniz. Bu pencere kapandığında serbest metin gönderemezsiniz — yalnızca önceden onaylanmış bir şablonla konuşmayı yeniden açabilirsiniz. Test ortamında görünmeyen, canlıda ikinci gün patlayan hata tam olarak budur.

Şablon mesajları ve onay süreci

Şablon (template), içindeki değişkenler dışında sabit olan, önceden onaylanmış mesaj kalıbıdır. Meta şablonları üç kategoriye ayırır ve ücretlendirme bu kategoriye göre değişir: pazarlama (kampanya, indirim, sepet hatırlatma), hizmet/utility (sipariş, kargo, randevu, fatura gibi işlemsel bildirimler) ve kimlik doğrulama (tek kullanımlık kod). Aynı metni yanlış kategoride göndermek hem reddedilme hem de gereksiz maliyet sebebidir: işlemsel bir bildirimi pazarlama olarak işaretlemek en yaygın hatadır.

# Cloud API ile onaylı şablon gönderimi (sipariş kargo bildirimi)
curl -X POST "https://graph.facebook.com/v21.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905XXXXXXXXX",
    "type": "template",
    "template": {
      "name": "siparis_kargoda",
      "language": { "code": "tr" },
      "components": [{
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Ayşe" },
          { "type": "text", "text": "TR123456789" }
        ]
      }]
    }
  }'

Gelen mesaj tarafı ise bir webhook’tur: Meta önce uç noktanızı doğrulama isteğiyle sınar, sonra her mesajı POST olarak gönderir. Kritik nokta, isteği hemen 200 ile yanıtlayıp işi kuyruğa atmaktır; yanıtı geciktirirseniz Meta aynı mesajı tekrar tekrar gönderir ve müşteriye çift cevap gider.

// Next.js route handler — webhook doğrulama + mesaj alma
export async function GET(req: Request) {
  const url = new URL(req.url);
  const isValid =
    url.searchParams.get('hub.mode') === 'subscribe' &&
    url.searchParams.get('hub.verify_token') === process.env.WA_VERIFY_TOKEN;

  return isValid
    ? new Response(url.searchParams.get('hub.challenge'))
    : new Response('forbidden', { status: 403 });
}

export async function POST(req: Request) {
  const body = await req.json();
  const message =
    body.entry?.[0]?.changes?.[0]?.value?.messages?.[0];

  // Önce kuyruğa al, sonra işle: Meta 200 gecikirse mesajı tekrar gönderir
  if (message) await enqueueIncomingMessage(message);

  return new Response('ok', { status: 200 });
}

Maliyet nasıl hesaplanır?

API’nin kendisi için Meta’ya bir kurulum ya da abonelik ücreti ödemezsiniz; ücret mesaj başınadır. Meta 2025’te konuşma başına ücretlendirmeden mesaj başına ücretlendirmeye geçti: müşteri hizmetleri konuşmaları (yani müşterinin başlattığı ve 24 saat penceresi içinde yürüyen yazışmalar) ücretsizdir, sizin başlattığınız şablon mesajları ise kategoriye ve alıcının ülkesine göre fiyatlanır. Pazarlama şablonları en pahalı, kimlik doğrulama ve hizmet şablonları daha ucuz kalemdir. Güncel birim fiyatlar Meta’nın ülke bazlı tarifesinde yayımlanır ve değiştiği için sözleşmeye sabit rakam yazmayın.

• Meta mesaj ücreti: Gönderilen şablon sayısı × kategori/ülke tarifesi. Aylık bütçenizi buradan tahmin edin: 10.000 kargo bildirimi ile 10.000 kampanya mesajı aynı maliyette değildir.
• BSP payı (kullanıyorsanız): Mesaj başına ek ücret ve çoğu zaman aylık platform aboneliği.
• Geliştirme: Tek yönlü bildirim entegrasyonu birkaç günlük iştir; iki yönlü destek akışı, kuyruk, temsilci devri ve raporlama eklendiğinde birkaç haftaya çıkar.
• Gizli kalem: Yanlış kategori. İşlemsel bildirimlerinizi pazarlama şablonu olarak gönderirseniz aynı hacme belirgin biçimde fazla ödersiniz.

Maliyeti aşağı çeken en etkili yöntem, mesajı gerçekten değerli olan anlara saklamaktır. Sipariş ve randevu bildirimleri hem ucuz kategoridedir hem de açılma oranı yüksektir; kampanya mesajını ise segment ederek gönderin. Ödeme, kargo, e-fatura gibi diğer zincir halkalarını da planlıyorsanız web sitesine ödeme entegrasyonu yazımız aynı mantığı diğer servisler için anlatıyor.

Hangi işletmede ne işe yarar?

• E-ticaret: Sipariş onayı, kargo takip numarası, teslimat bildirimi ve terk edilen sepet hatırlatması. SMS’e göre teslim ve okunma oranı belirgin şekilde yüksektir.
• Randevulu hizmetler (klinik, güzellik, servis): Hatırlatma ve tek dokunuşla onay/iptal — gelmeyen müşteri oranını düşüren en pratik otomasyon. Online randevu sistemi kurulumuyla birlikte çalışır.
• B2B ve bayi ağı: Stok, sipariş durumu ve cari bakiye bildirimleri; bayinin panele girmesine gerek kalmadan bilgi akar.
• Destek ve chatbot: Sık sorulan soruları yapay zekâ destekli bir akışla karşılayıp gerisini temsilciye devretmek. Kurgusunu yapay zeka chatbot nasıl yapılır yazımızda adım adım anlattık.

Sık yapılan beş hata

• İzinsiz liste kullanmak: Onay vermemiş numaralara pazarlama mesajı göndermek kalite puanınızı düşürür ve numaranız kısıtlanır. Toparlanması haftalar sürer.
• Tek şablonla her işi görmeye çalışmak: Değişken sayısı fazla, amacı bulanık şablonlar hem reddedilir hem de okunmaz.
• Webhook’u senkron işlemek: Ağır işi istek içinde yapmak tekrar gönderime ve çift mesaja yol açar.
• Geçici token ile canlıya çıkmak: Entegrasyon ertesi gün sessizce durur; sistem kullanıcısı token’ı kullanın.
• KVKK tarafını atlamak: Numara, konuşma içeriği ve gönderim kaydı kişisel veridir; aydınlatma metni, açık rıza ve saklama süresi tanımlanmalıdır. Ayrıntı için KVKK uyumlu web sitesi yazımıza bakın.

Sonuç

WhatsApp Business API entegrasyonu, teknik olarak birkaç günlük bir iş; asıl belirleyici olan hangi mesajın hangi olayla tetikleneceğine dair kurguyu doğru kurmaktır. Kendi yazılım ekibiniz varsa Cloud API ile doğrudan başlayın, yoksa bildirimleri kendi sisteminizden, destek trafiğini panelden yürüten karma modeli değerlendirin; her iki durumda da 24 saat kuralını ve şablon kategorilerini baştan doğru kurgulayın. Mevcut sisteminize (e-ticaret, ERP, CRM) WhatsApp bildirim akışı eklemeyi düşünüyorsanız özel yazılım hizmetimize göz atabilir ya da süreçlerinizi anlatıp ücretsiz teklif alabilirsiniz.