Ana içeriğe geç

📱 WhatsApp Cloud API

WhatsApp, Meta'nın Cloud API'si ile bağlanır — kendi sunucunuzdan WhatsApp mesajları gönderip almanızı sağlayan resmi, ücretsiz katmanlı API. Üçüncü taraf BSP (Business Solution Provider) gerekmez.

Ön Koşullar​

  1. developers.facebook.com adresinde bir Meta Geliştirici hesabı
  2. Bir Meta Business Hesabı (Business Manager olarak da bilinir)
  3. WhatsApp için kişisel WhatsApp'ta kayıtlı olmayan bir telefon numarası (SIM, sanal numara veya sabit hat kullanabilirsiniz)

Kurulum Adımları​

1. Meta Uygulaması Oluşturun​

  1. developers.facebook.com/apps adresine gidin
  2. Create App tıklayın
  3. Business türünü seçin
  4. Bir ad girin ve Business Hesabınızı bağlayın

2. WhatsApp Ürününü Ekleyin​

  1. Uygulamanızın panelinde Add Products to Your App bölümüne kaydırın
  2. WhatsApp üzerinde Set Up tıklayın
  3. Business Hesabınızı seçin

3. Kimlik Bilgilerinizi Alın​

Uygulama panelinizde WhatsApp → API Setup bölümüne gidin:

Kimlik BilgisiNerede Bulunur
Phone Number ID"From" bölümünde listelenir — 123456789012345 gibi sayısal bir ID
Access TokenBu sayfada gösterilen geçici jeton. Üretim için System Users aracılığıyla kalıcı jeton oluşturun.
App SecretUygulama Paneli → Settings → Basic → App Secret
Verify TokenKendinizin belirlediği bir dize — herhangi bir rastgele dize, ör. my_secret_verify_token_2024

4. PulseHub'da Kanal Ekleyin​

  1. Kanallar → Kanal Ekle bölümüne gidin
  2. WhatsApp seçin
  3. Dört alanı doldurun
  4. Kanalı Kaydet tıklayın
  5. Kanal kartında gösterilen Webhook URL'sini kopyalayın

5. Meta'da Webhook'u Yapılandırın​

  1. Meta uygulamanızda WhatsApp → Configuration bölümüne gidin
  2. Webhook bölümünün yanındaki Edit tıklayın
  3. Callback URL: PulseHub webhook URL'nizi yapıştırın
  4. Verify Token: PulseHub'a girdiğiniz aynı dizeyi girin
  5. Verify and Save tıklayın

Meta, webhook URL'nize ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=... ile bir GET isteği gönderir. PulseHub jetonu doğrular ve challenge'ı geri gönderir.

  1. Webhook Fields altında şuna abone olun: messages

6. Test​

İş numaranıza bir WhatsApp mesajı gönderin. Birkaç saniye içinde PulseHub'ın gelen kutusunda yeni bir görüşme olarak görünmelidir.

İmza Doğrulama​

Meta her webhook'a X-Hub-Signature-256 başlığı ekler:

X-Hub-Signature-256: sha256=abc123...

PulseHub bunu App Secret'ınız ile HMAC-SHA256 kullanarak doğrular. Doğrulama başarısız olursa, webhook 401 Signature mismatch döndürür.

Mesaj Gönderme​

Bir temsilci gelen kutusundan yanıt gönderdiğinde, PulseHub WhatsApp Cloud API'sini çağırır:

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Yanıtınız burada"}
}

Üretim Erişimi​

Varsayılan Meta uygulaması Development modundadır — yalnızca test numarası olarak eklenen numaralara mesaj gönderebilir. Canlıya geçmek için:

  1. Meta Business Manager'da İş Doğrulaması'nı tamamlayın
  2. WhatsApp kullanım senaryonuzu Meta incelemesine gönderin
  3. Onaylandıktan sonra uygulamanız tüm WhatsApp kullanıcılarına mesaj gönderme erişimi kazanır

Sık Karşılaşılan Sorunlar​

BelirtiOlası Neden
Webhook kurulumu sırasında doğrulama başarısızPulseHub'daki verify_token Meta'ya girdiğinizle eşleşmiyor
Günlüklerde imza uyumsuzluğu hatasıYanlış app_secret — App Settings → Basic'ten kopyalayın, API Setup'tan değil
Mesajlar gelmiyorMeta panelinde webhook alanı messages abone edilmemiş
Gönderirken Invalid phone numberNumara formatı + olmadan E.164 olmalı (ör. 15551234567)
Development modunda uygulama hatasıDev modunda yalnızca doğrulanmış test numaraları mesaj alabilir