WABA & WhatsApp Cloud API (langkah demi langkah)

Business Suite, WhatsApp Manager, aplikasi developer, dan integrasi Convord

Terakhir diperbarui: Terakhir diperbarui: 13 Juli 2026

WhatsApp Business hesabı (WABA) ve Cloud API kurulum rehberi (Convord)

Bu doküman sırasıyla şunları anlatır:

  1. Hangi hesabın ne işe yaradığı (Convord ürünü vs müşteri; işletme portföyü).
  2. Meta Business güvenliği: passkey, Gmail/iCloud uyarıları, Excel dışa aktarma.
  3. Davet ve giriş sorunları (ör. “zaten portföydesiniz”).
  4. WABA, numara, geliştirici uygulaması, webhook ve Convord .env.

Depo dışı okuyorsanız: Kaynak dosya docs/WHATSAPP_WABA_VE_CLOUD_API_KURULUM.md. Convord kurulumunda aynı metin tarayıcıda /dokumanlar/whatsapp-waba-kurulum adresinden de sunulur.

Meta arayüzleri sık güncellenir; menü adları (Türkçe/İngilizce) değişebilir. Akış mantığı aynı kalır: iş portföyü → kullanıcı güvenliği → WABA → Developers → token/webhook → Convord.

Convord panelinde üç bağlantı yolu (önerilen sıra)

  1. Mevcut numara (önerilen) — Panel → WhatsApp hattını bağla → Mevcut numaram var. Yeni numara alınmaz; WhatsApp Business uygulamasındaki hattınız Meta Embedded Signup ile Cloud API’ye bağlanır. Sunucu kurulumu: docs/META_EMBEDDED_SIGNUP_KURULUM.md (php artisan whatsapp:check-meta-config).
  2. Concierge (kurulum desteği) — Aynı sayfada Sizin kurun: müşteri telefon bırakır; Convord ekibi Meta tarafını müşteriyle birlikte tamamlar. Müşteri yalnızca Meta’da onay verir.
  3. Manuel / gelişmiş — Phone Number ID + Access Token (+ isteğe bağlı WABA ID) yapıştırma; ajans veya Developers deneyimi olanlar için.

Önemli: Çoğu müşteri için sıfırdan WABA + yeni numara gerekmez. Bölüm 8–9 yalnızca gerçekten yeni hat açılacaksa kullanılır.

İçindekiler

  1. Terimler
  2. Convord için doğru model: kimin işletme portföyü?
  3. İşletme portföyünde kullanıcılar ve roller
  4. Güvenlik Merkezi ve Passkey (adım adım)
  5. Güvenlik Merkezi: Kurumsal e-posta ve Gmail / iCloud uyarısı
  6. Güvenlik raporu Excel’i nasıl okunur?
  7. Davet kabulü: “Zaten İşletme Portföyündesiniz” hatası
  8. Sıfırdan WABA oluşturma (iş hesabı tarafı)
  9. Telefon numarası: test ve canlı
  10. Meta for Developers: uygulama ve WhatsApp ürünü
  11. Convord ile webhook ve .env
  12. Kurulum sonrası doğrulama
  13. Sık sorunlar (özet tablo)
  14. Resmi kaynaklar

1. Terimler

Terim Açıklama
İşletme portföyü (Business Portfolio / BM) Reklam, sayfalar, WhatsApp varlıkları ve ekip üyelerinin toplandığı Meta iş hesabı.
WABA WhatsApp Business Account — Cloud API’nin bağlı olduğu WhatsApp Business hesabı.
WhatsApp Yöneticisi Business Suite içinde WABA ve numara yönetimi.
Cloud API Meta’nın WhatsApp HTTP API’si; Convord gelen mesajları buradan işler.
Phone Number ID Graph çağrılarında kullanılan sayısal kimlik (telefon numarasının kendisi değil).
Access token Graph isteklerinde kullanılan jeton (testte geçici; üretimde süre/yenileme planı gerekir).
Webhook Meta’nın gelen olayları sunucunuza POST ettiği HTTPS uç nokta.
Passkey (geçiş anahtarı) Şifre yerine veya şifreyle birlikte kullanılan, cihaz/tabana dayalı güçlü kimlik doğrulama (Meta bunu “en güvenli” yöntem olarak önerir).
Güvenlik Merkezi business.facebook.com içinde iş portföyü için risk ve önerileri gösteren bölüm.

2. Convord için doğru model: kimin işletme portföyü?

2.1. Tipik SaaS senaryosu (çoğu kurulum)

2.2. Sizin (Convord / ajans) portföyünüz

2.3. Özet cümle

“Her müşteriyi kendi işletme portföyümüze almalıyım” genelde yanlış varsayımdır. Her müşteri kendi portföyünde WABA açar; Convord entegrasyon değerlerini okur.

3. İşletme portföyünde kullanıcılar ve roller

  1. business.facebook.com → işletme portföyünüzü seçin.
  2. Ayarlar (Settings) veya İşletme ayarları → Kullanıcılar / People (veya Kişiler) bölümüne gidin.
  3. Burada kimlerin portföyde olduğunu, rolleri (ör. tam kontrol, geliştirici, temel erişim) görürsünüz.
  4. Yeni kişi eklerken:
    • E-posta daveti gönderebilirsiniz; kabul sırasında hangi Facebook/Meta hesabıyla giriş yapıldığı önemlidir (Bkz. Bölüm 7).
    • Alternatif: Davet linki yerine, aynı ekrandan doğrudan e-posta ile ekleme bazen daha az hata verir (Meta arayüzüne göre değişir).
  5. Minimum güvenlik ilkesi: Portföyde gerçekten Meta’da iş yapacak kişi sayısını az tutun; gereksiz admin eklemeyin.

4. Güvenlik Merkezi ve Passkey (adım adım)

Meta Güvenlik Merkezi’nde “passkey etkin olmayan kullanıcılar” uyarısı görülebilir. Metin bazen “passkey olmayanları portföyden çıkarın” gibi agresif görünür; pratik çözüm çoğu zaman kullanıcıları silmek değil, passkey eklemektir.

4.1. Passkey nedir (kısa)?

4.2. Kim passkey eklemeli?

4.3. Adımlar (genel — mobil veya masaüstü)

Menü isimleri TR/EN değişebilir; arama kutusuna “passkey”, “geçiş anahtarı”, “security” yazarak bulun.

Yol A — Facebook / Meta Hesap Merkezi (önerilen):

  1. accountscenter.facebook.com adresine gidin (veya Facebook uygulamasında Ayarlar → Hesap Merkezi).
  2. Şifre ve güvenlik / Password and security (veya Güvenlik) bölümünü açın.
  3. Passkeys / Geçiş anahtarları / benzeri seçeneği bulun.
  4. Passkey ekle → Meta size uygun seçenekleri gösterir:
    • iPhone / iPad: genelde cihaz üzerinde Touch ID / Face ID ile kayıt.
    • Android: cihaz ekran kilidi veya Google hesabı ile uyumlu akış.
    • Windows: Windows Hello (PIN, yüz, parmak izi) veya harici güvenlik anahtarı.
  5. İşlemi tamamlayın; mümkünse yedek bir yöntem (ikinci cihaz veya güvenlik anahtarı) da ekleyin.

Yol B — facebook.com masaüstü:

  1. Sağ üst profil → Ayarlar ve gizlilik → Ayarlar.
  2. Güvenlik ve giriş bilgileri / Security and login.
  3. Geçiş anahtarları / Passkeys bölümünden ekleyin.

4.4. Passkey sonrası ne olur?

4.5. Passkey ekleyemiyorum

5. Güvenlik Merkezi: Kurumsal e-posta ve Gmail / iCloud uyarısı

5.1. Uyarının anlamı

Meta şunu söyler: Bir veya daha fazla portföy kullanıcısı ücretsiz/halka açık e-posta alan adı (ör. @gmail.com, @hotmail.com, @icloud.com) kullanıyor; kimlik avı riski için kurumsal alan adlı e-posta öneriyoruz.

Bu genelde politika / güvenlik önerisidır; WhatsApp API’yi tek başına otomatik kapatmaz. Yine de itibar ve uzun vadeli uyum için kurumsal e-posta iyidir.

5.2. Ne yapılabilir?

Seçenek Açıklama
A — Kurumsal e-posta ad@convord.com gibi bir adres; Google Workspace, Microsoft 365 veya kendi mail sunucunuz. Telefonda Gmail uygulamasına iş hesabı ekleyerek de okunabilir.
B — Portföyü sadeleştir Sadece gerçekten admin olması gereken kişiler kalsın; diğerleri çıkarılsın (dikkat: kendinizi kilitlemeyin).
C — Uyarıyı bilerek tolere et Risk raporu “sarı” kalabilir; iş kritik değilse ilerlenebilir.

5.3. Müşteri çalışanları Gmail kullanıyorsa?

6. Güvenlik raporu Excel’i nasıl okunur?

Meta’dan indirilen SecurityData_….xlsx dosyasında birden fazla sayfa (sheet) olabilir. Tipik içerik:

6.1. “Passkey yok” listesi

Örnek sütunlar: Name, ID, Roles

6.2. “Kurumsal olmayan e-posta” listesi

Örnek sütunlar: Name, ID, Email

6.3. Aynı kişi için farklı ID’ler

7. Davet kabulü: “Zaten İşletme Portföyündesiniz” hatası

Tam metin genelde şöyledir: Görünüşe göre zaten bir İşletme Portföyündesiniz; bu daveti kabul etmek için başka bir kullanıcı adı ve şifreyle giriş yapın.

7.1. Ne anlama gelir?

7.2. Ne denemelisiniz? (sırayla)

  1. Gizli / özel pencere açın; yalnızca daveti kabul etmesi gereken Facebook hesabıyla giriş yapın.
  2. Önce tüm Meta oturumlarını kapatın (facebook.com ve business.facebook.com), sonra tek hesapla tekrar deneyin.
  3. business.facebook.com → Kullanıcılar’dan bakın: davet edilen e-posta zaten üye mi? Öyleyse davet gereksizdir.
  4. Daveti iptal edip portföy ayarlarından yeniden davet gönderin veya e-posta ile doğrudan ekleme akışını kullanın.
  5. Çifte kişilik: Aynı kişi, iki farklı Facebook hesabı kullanıyorsa — davet hangi iş e-postası / hangi FB için ise o hesapla giriş şarttır.

7.3. Convord müşterisi için not

Müşteriye “Convord’un portföyüne davet” şartı koymayın; müşteri kendi portföyünde ilerlesin (Bölüm 2).

8. Sıfırdan WABA oluşturma (iş hesabı tarafı)

8.1. İşletme portföyüne giriş

  1. business.facebook.com adresine gidin.
  2. Portföy yoksa sihirbaz işletme portföyü oluşturmanızı ister.
  3. Yönet (Manage) altında WhatsApp Yöneticisi (WhatsApp Manager) öğesini bulun.

8.2. WhatsApp Yöneticisi içinde WABA

  1. WhatsApp Yöneticisi’ni açın.
  2. Hesaplar / Accounts → Yeni hesap veya WhatsApp Business hesabı ekle.
  3. İşletme doğrulama istenirse adımları tamamlayın (canlı kullanımda daha sık).
  4. Varlıkların doğru portföye bağlı olduğundan emin olun.

8.3. WABA oluştuktan sonra

Hesap kartında WABA özeti görünür; sonraki adım telefon numarasıdır.

9. Telefon numarası: test ve canlı

9.1. Kurallar

9.2. Numara ekleme

  1. İlgili WABA’yı seçin.
  2. Telefon numaraları → Ekle.
  3. SMS veya arama ile kodu doğrulayın.
  4. Hata alırsanız mesajı not edin (numara başka hesapta, vb.).

10. Meta for Developers: uygulama ve WhatsApp ürünü

10.1. Uygulama oluşturma

  1. developers.facebook.com → Uygulama oluştur.
  2. Tür: İşletme veya WhatsApp’ı destekleyen tür.
  3. Doğru iş portföyünü bağlayın.

10.2. WhatsApp ürünü

  1. Ürün ekle → WhatsApp.
  2. API Kurulumu / Getting started sayfasında:
    • Geçici access token
    • Phone number ID
    • İstenirse WABA ID
  3. Test için test alıcı telefonu ekleyin.

10.3. Webhook

  1. WhatsApp ürün ayarlarında Webhook.
  2. Callback URL ve Verify token (token .env ile aynı olmalı).
  3. Abonelikler: messages (ve Meta’nın istediği alanlar) işaretli olsun.

11. Convord ile webhook ve .env

11.1. Webhook URL

https://SIZIN-ALAN-ADINIZ/webhook/whatsapp

Yerel test (örnek):

https://xxxx.ngrok-free.app/webhook/whatsapp

11.2. .env (özet)

WHATSAPP_VERIFY_TOKEN=guclu-rastgele-bir-dize
WHATSAPP_API_TOKEN=EAAG...
WHATSAPP_PHONE_NUMBER_ID=123456789012345
# WHATSAPP_API_URL=https://graph.facebook.com/v18.0

php artisan config:clear
# Üretimde gerekiyorsa: php artisan config:cache

11.3. Diğer dökümanlar

12. Kurulum sonrası doğrulama

  1. Meta’da webhook Verify başarılı mı?
  2. İzinli numaradan test mesajı.
  3. Convord dashboard ve log’lar.
  4. Panel → Entegrasyonlar alanında token / Phone Number ID tutarlı mı?

13. Sık sorunlar (özet tablo)

Belirti Olası neden Ne yapılabilir
Güvenlikte passkey uyarısı Listelenen kullanıcılarda passkey yok Bölüm 4; tüm ilgili kişiler
Gmail / iCloud uyarısı Portföyde halka açık alan adlı e-posta Kurumsal e-posta veya kullanıcıyı azalt; tolere etme kararı
“Zaten portföydesiniz” Yanlış FB oturumu veya zaten üye Bölüm 7
Webhook Verify başarısız Token/URL/HTTPS .env ve Meta alanını eşle; tünel/sertifika
Mesaj gelmiyor Abonelik veya token messages aboneliği; token süresi
Müşteri ölçeklenmiyor Her müşteri sizin BM’e davet Bölüm 2 — müşteri kendi portföyü

14. Resmi kaynaklar

Bu dosya Convord deposu içindir; Meta arayüzü değiştikçe menü adları güncellenebilir. Güncel resmi İngilizce dokümantasyon her zaman referans alınmalıdır.

Setup Meta & WhatsApp Cloud API — Untuk referensi .env dan webhook saja yang lebih singkat, gunakan tautan ini.