# Meta WhatsApp Business API — Sıfırdan Kurulum Rehberi
Her bir firma (sesyaz panelindeki her agent) için bu adımları **bir kez** yaparsınız.
Aynı Meta Business hesabı altında birden çok WhatsApp numarası tutabilirsiniz.
---
## ADIM 0 — Önkoşullar
- **Facebook hesabı** (kişisel; iş için Meta Business Manager kullanılır)
- **WhatsApp numarası**: Test için Meta size ücretsiz verir. Üretim için **WhatsApp uygulamasına KAYITLI OLMAYAN** bir numara gerekir (yeni SIM veya WhatsApp'tan silinmiş eski numara).
- **Web siteniz/iş bilgileriniz** (üretim doğrulaması için)
---
## ADIM 1 — Meta Business Manager hesabı aç (5 dk)
1. → **"Hesap oluştur"**
2. İşletme adı: ör. **Fasheone**
3. Kendi adınız + e-postanız
4. **Hesap oluştur**
5. E-posta doğrulamayı tamamla
---
## ADIM 2 — Meta Developer App oluştur (3 dk)
1. → **"Create App"**
2. **Use case**: "Other" → **Continue**
3. **App type**: **"Business"** → **Continue**
4. App display name: **Fasheone WhatsApp** (örnek)
5. Contact email: kendi e-postanız
6. Business Account: Adım 1'de oluşturduğunuz hesabı seçin
7. **Create App**
Şifre tekrar isteyebilir.
---
## ADIM 3 — WhatsApp ürününü ekle (1 dk)
1. App dashboard'da sol menüden **"Add products to your app"**
2. **WhatsApp** kartında **"Set up"** tıkla
3. Business portfolio'yu seç → **Continue**
4. Otomatik olarak **WhatsApp Business Account (WABA)** + **Test Phone Number** oluşturur
> 🟢 Bu noktada **ücretsiz test numarası** verilir. Üretime geçmeden önce burada her şeyi test edebilirsiniz.
---
## ADIM 4 — Önemli ID'leri al (2 dk)
Sol menü: **WhatsApp → API Setup**
Sayfada şunlar yazıyor:
| Alan | Nereden alacaksın | Sesyaz panelinde nereye |
|---|---|---|
| **Phone Number ID** | "From" altında, telefon numarasının altında numara | "Phone Number ID" |
| **WhatsApp Business Account ID** | Aynı sayfanın üstünde | "WABA ID" (opsiyonel) |
| **Test telefon numarası** | "From" altında "+1 555..." | "WhatsApp Numarası" |
Her birinin yanındaki kopyala butonuyla alın.
---
## ADIM 5 — Access Token (kalıcı) al (8 dk)
Burası en kritik adım. Üç yolu var:
### 5A — Geçici token (24 saatlik, hızlı test için)
API Setup sayfasında **"Temporary access token"** kutusunda hazır vardır.
- Yan butonuyla kopyalayın
- Panelde "Access Token" alanına yapıştırın
- ⚠️ **24 saat sonra geçersiz olur**
### 5B — Kalıcı token (System User, üretim için ŞART)
1.
2. **"Add"** → System user adı: **sesyaz-fasheone-bot**, role: **Admin** → Create
3. Oluşan user'ı seç → **"Generate new token"**
4. App'i seç (Adım 2'de oluşturduğunuz)
5. Token süresi: **"Never"** (kalıcı)
6. Permissions (izinler) - şunları işaretleyin:
- ✅ `whatsapp_business_messaging`
- ✅ `whatsapp_business_management`
7. **Generate token** → çıkan tokeni hemen kopyalayın (bir daha gösterilmez!)
8. **Sistem kullanıcısına asset ata:**
- Aynı System User sayfasında → **"Assign assets"**
- **WhatsApp Accounts** → Adım 3'te oluşan WABA'yı seç → **Full control** → Save
- **Apps** → App'inizi seç → **Develop App** → Save
Bu token panelde "Access Token" alanına gider.
---
## ADIM 6 — App Secret al (1 dk)
1. Sol menü: **App settings → Basic**
2. **App Secret** satırı → **"Show"** → şifrenizi tekrar girin
3. Çıkan değeri kopyala
4. Panelde "App Secret" alanına yapıştır
---
## ADIM 7 — Verify Token belirle (1 dk)
Bu Meta'nın istediği bir şey değil — **siz uyduracaksınız**. Webhook handshake sırasında Meta bu kelimeyi sunucumuza gönderecek; sunucumuz aynısını bekliyor, eşleşirse kabul ediyor.
- Örnek: `sesyaz_fasheone_2026_xK9`
- Sesyaz panelinde "Verify Token" alanına yaz
- Meta'da da aşağıdaki adımda **birebir aynı** yazacaksın
---
## ADIM 8 — Sesyaz panelinde kaydet (1 dk)
Önce sesyaz tarafını tamamla:
1. → fasheone agent'ını seç
2. **WhatsApp Kanalı** bölümü:
- **WhatsApp Numarası** (görünür): `+1 555 ...` (test numarası)
- **WABA ID** (opsiyonel): Adım 4'ten
- **Phone Number ID**: Adım 4'ten
- **Verify Token**: Adım 7'de uydurduğun
- **Access Token**: Adım 5'ten
- **App Secret**: Adım 6'dan
3. **Etkin** toggle ✅
4. **Kaydet**
---
## ADIM 9 — Meta'da Webhook ayarla (3 dk)
1. Meta App → sol menü: **WhatsApp → Configuration**
2. **Webhook** bölümü → **"Edit"** butonu
3. Açılan kutuya:
- **Callback URL**: `https://sesyaz.com/webhook/whatsapp`
- **Verify Token**: Adım 7'de uydurduğunuz (panel'le birebir aynı)
4. **"Verify and Save"** butonuna bas
5. ✅ Yeşil "Webhook verified" yazısı görmelisin
- Kırmızı çıkarsa: token uyuşmuyor demektir, sesyaz paneldeki ile karşılaştır
---
## ADIM 10 — "messages" alanına abone ol (1 dk)
Aynı Configuration sayfasında, Webhook'un altında **Webhook fields** listesi var.
- **messages** satırının yanındaki **"Subscribe"** butonuna bas
- Yanında **✅** işareti görmelisin
Bu yapılmazsa Meta gelen mesajları sunucumuza HİÇ göndermez.
---
## ADIM 11 — Alıcı numaraları ekle (test için)
Test numarası kullanıyorsanız, Meta yalnızca **izin verdiğiniz numaralara** mesaj gönderir.
1. **WhatsApp → API Setup**
2. "To" altında **"Manage phone number list"** veya **"Add phone number"**
3. Kendi WhatsApp numaranızı + müşteri/test edenlerin numaralarını ekle
4. Her numara için Meta WhatsApp'tan **doğrulama kodu** gönderir → telefondan kodu girin
> 🟡 Test numarasında **5 alıcı + 1000 mesaj/gün** sınırı vardır.
---
## ADIM 12 — Test mesajı gönder
1. Adım 11'de eklediğiniz bir telefondan **test numarasına** ("From" altındaki +1 555...) bir WhatsApp mesajı atın
2. Sesyaz `~3-5 saniye` içinde fasheone bilgi tabanından otomatik cevap vermeli
3. Cevap gelmezse:
- Sesyaz log'larına bakın (`https://seymata.com/dashboard` → app → Logs)
- `[whatsapp] N mesaj geldi` görünüyor mu? → ulaştı demek
- `[whatsapp] yanıt gönderildi` görünüyor mu? → gönderdi demek
- `[whatsapp] eşleşen agent yok` görünüyorsa Phone Number ID yanlış
---
## ADIM 13 — Üretim numarası (gerçek müşteri için)
Test bittikten sonra:
### 13A — Gerçek numara ekle
1. **WhatsApp → API Setup → "Add phone number"**
2. Daha önce WhatsApp'a hiç kayıt olmamış bir numara girin
3. Doğrulama: SMS veya **arama** (Türkiye'de SMS bazen gelmez, **"Call me"** seçin)
4. Yeni Phone Number ID alır → sesyaz panelini güncellemeyi unutmayın
### 13B — Display Name onayı al
1. **WhatsApp → API Setup → Display Name** kısmına gidin
2. Müşterinin WhatsApp'ta göreceği işletme adı (ör. "Fasheone")
3. Onay başvurusu yapın → Meta 1-3 gün içinde inceler
### 13C — Business verification (kotaları artırmak için)
1.
2. **"Start verification"**: Vergi levhası, ticaret sicil, fatura vs.
3. Bu onay olmadan günde 1000 müşteri mesajı sınırı vardır
### 13D — Ödeme yöntemi
1.
2. Kredi kartı veya banka ekle
3. Aylık kullanıma göre Meta direkt çekiyor (ilk 1000 conversation/ay ücretsiz)
---
## Sık karşılaşılan sorunlar
| Sorun | Çözüm |
|---|---|
| "Webhook verify failed" (kırmızı) | Verify token sesyaz panel ile Meta'da **aynı değil** — birebir karşılaştır |
| "URL not accessible" | sesyaz.com'a Meta'dan ulaşılamıyor — DNS/proxy sorunu, beni çağır |
| Mesaj geliyor ama cevap dönmüyor | Log'da `[whatsapp] mesaj işlenemedi` varsa Access Token süresi dolmuş; kalıcı System User token kullan |
| "Recipient not in allowed list" | Adım 11'de alıcı eklemeyi unutmuşsun |
| 24 saat sonra çalışmamaya başlıyor | Geçici token kullanıyorsun, kalıcı System User token al (Adım 5B) |
| `[whatsapp] eşleşen agent yok` | Panelde Phone Number ID yanlış veya agent.whatsapp.enabled = false |
| `OAuthException code 190` | Token iptal edilmiş / yenilenmiş, yeniden al |
---
## Özet — sırasıyla yapılacaklar
```
1. business.facebook.com → Hesap aç
2. developers.facebook.com/apps → App oluştur
3. App → WhatsApp ürünü ekle → Otomatik test no + WABA
4. WhatsApp → API Setup → Phone Number ID, WABA ID kopyala
5. Business Manager → System Users → KALICI access token oluştur
6. App Settings → Basic → App Secret kopyala
7. Bir verify token uydur → "sesyaz_fashene_xyz"
8. Sesyaz panel → 6 alanı doldur + Etkin + Kaydet
9. WhatsApp → Configuration → Webhook URL + verify token + "Verify and Save"
10. Webhook fields → messages ✅ Subscribe
11. API Setup → To list → Test alıcılarını ekle
12. Test mesajı at → Cevabı bekle
13. Üretim için: gerçek no + display name + business verify + ödeme
```
İlk kurulum **yaklaşık 20-30 dakika** sürer. En çok zaman alan adımlar:
- System User token (Adım 5B) — ilk seferinde kafa karıştırıcı
- Webhook verify (Adım 9) — token tutarsızlığı en yaygın hata