WhatsApp OTP Doğrulama

AnchorSpot, SMS'e alternatif olarak WhatsApp Business API üzerinden OTP gönderimini destekler. Daha yüksek iletim oranı, SMS maliyeti olmaması ve mesajın okunduğuna dair bildirim gibi avantajlar sunar.

Genel Bakış

WhatsApp OTP akışı SMS OTP ile birebir aynıdır; yalnızca iletim kanalı farklıdır. Misafir yine telefon numarasını girer, ancak kod SMS yerine WhatsApp üzerinden iletilir.

Misafir → Numara girer → WhatsApp mesajı gönderilir → Kodu girer → Bağlantı sağlanır

:::info Sağlayıcı seçenekleri WhatsApp OTP için üç sağlayıcı desteklenir; tenant başına platform konsolundan seçilir (/admin/whatsapp-providers):

Sağlayıcı	Kimlik bilgisi	Şablon
VatanSMS (toplusms.app)	tek API anahtarı + Business Device ID	toplusms şablon ID'si
Meta Cloud API (doğrudan Meta)	system-user access token + Phone Number ID	Meta şablon adı ad:dil
NetGSM	SMS ile aynı usercode:password çifti	sağlayıcıda sabit (netgsm_verify_code)

Üçü de Meta'nın WhatsApp Business altyapısına dayanır; fark faturalama ve şablon yönetiminin kimde olduğudur. :::

Ön Gereksinimler

• WhatsApp Business hesabı — aktif ve doğrulanmış olmalıdır.
• Onaylı mesaj şablonu — Meta, şablonları önceden inceleyip onaylar; genellikle 24–48 saat sürer. (NetGSM'de şablon sağlayıcı tarafında hazırdır.)
• Seçilen sağlayıcının API kimlik bilgisi ve ilişkili gönderici telefon numarası.

NetGSM ile kurulum

NetGSM diğer iki sağlayıcıdan iki noktada ayrılır: şablon sağlayıcı tarafında sabittir (netgsm_verify_code) ve kimlik bilgisi SMS API'siyle aynı usercode:password çiftidir — ayrı anahtar yoktur.

1. Meta Business doğrulamasını tamamlayın.
2. NetGSM Online İşlemler > WhatsApp OTP > Ayarlar ekranında hesabı bağlayın (Meta ile giriş yapın veya access token + Phone Number ID + App Secret'ı elle girin).
3. Hesabınızda OTP WhatsApp paketi tanımlı olmalıdır.
4. NAC_NETGSM_WHATSAPP_CREDENTIALS=usercode:password değerini ortam dosyasına yazın.
5. Konsolda provider'ı netgsm, api_key_ref alanını env://NAC_NETGSM_WHATSAPP_CREDENTIALS yapıp etkinleştirin. Business Device ID ve Default Template alanları boş bırakılır.

Gönderim POST https://whatsappapi.netgsm.com.tr/v1/otp adresine HTTP Basic kimlik doğrulamasıyla yapılır; gövde yalnız {"to": "+90…", "code": "123456"} içerir. Hata kodları: 30 kimlik/IP, 60 paket tanımsız, 70 parametre, 80 şablon bulunamadı, 100 sistem hatası.

Mesaj Şablonu

Meta politikası gereği OTP mesajları önceden onaylanmış bir şablon üzerinden gönderilmek zorundadır. Tipik bir AnchorSpot şablonu:

Sayın misafirimiz, Wi-Fi bağlantısı için doğrulama kodunuz: {{1}}
Bu kod 5 dakika geçerlidir. Lütfen kimseyle paylaşmayın.

{{1}} yerine gerçek OTP kodu otomatik olarak yerleştirilir. Şablon ID'si konsol konfigürasyonunda belirtilmelidir.

API Akışı

OTP Talebi (WhatsApp)

curl -X POST https://<portal-host>/api/v1/hotspot-portal/sms/request \
  -H "Content-Type: application/json" \
  -d '{
    "phone":   "+905321234567",
    "mac":     "aa:bb:cc:dd:ee:ff",
    "ssid":    "Misafir-WiFi",
    "channel": "whatsapp"
  }'

channel: "whatsapp" parametresi ile sistem WhatsApp kanalını seçer.

Başarılı yanıt:

{
  "status":     "sent",
  "channel":    "whatsapp",
  "expires_in": 300
}

OTP Doğrulama

Doğrulama endpoint'i SMS ile aynıdır:

curl -X POST https://<portal-host>/api/v1/hotspot-portal/sms/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+905321234567",
    "code":  "7364",
    "mac":   "aa:bb:cc:dd:ee:ff"
  }'

SMS'e Otomatik Geri Dönüş (Fallback)

WhatsApp mesajı 30 saniye içinde iletilmezse sistem otomatik olarak SMS kanalına geçer.

WhatsApp iletimi başarısız → 30 sn bekle → SMS gönder → Misafir bilgilendirilir

Portal ekranında "WhatsApp ile gönderildi" veya "SMS ile gönderildi" durumu gösterilir. Geri dönüş davranışı konsol üzerinden devre dışı bırakılabilir.

:::tip Maliyet Tasarrufu WhatsApp mesajları Türkiye'de SMS maliyetinin genellikle %80'i kadar daha ucuzdur. Yoğun kullanımlı mekânlarda (AVM, havalimanı lounge) WhatsApp kanalı tercih edilmesi önerilir. :::

Konfigürasyon

Ayarlar → Kimlik Doğrulama → WhatsApp bölümünden:

Parametre	Açıklama
WHATSAPP_API_KEY	toplusms.app API anahtarı
WHATSAPP_TEMPLATE_ID	Meta onaylı şablon ID'si
WHATSAPP_SENDER_PHONE	Gönderici iş telefonu (E.164)
WHATSAPP_FALLBACK_SMS	SMS geri dönüşü (true / false)
WHATSAPP_FALLBACK_TIMEOUT_SEC	Geri dönüş bekleme süresi (varsayılan: 30)

SMS ile Karşılaştırma

Özellik	SMS OTP	WhatsApp OTP
İletim hızı	Orta	Yüksek
Maliyet	Yüksek	Düşük
Okundu bilgisi	Yok	Var
İnternet gerektirmez	Evet	Hayır
Kurulum karmaşıklığı	Düşük	Orta

:::warning Dikkat Misafirin telefonunda WhatsApp kurulu değilse veya numara WhatsApp'a kayıtlı değilse mesaj iletilmez. Fallback etkinleştirilmediği takdirde misafir bağlanamaz. Üretim ortamında WHATSAPP_FALLBACK_SMS=true bırakılması şiddetle önerilir. :::

Sorun Giderme

Mesaj İletilmiyor

1. toplusms.app panelinde gönderim kaydını kontrol edin.
2. Şablonun Meta tarafından onaylı olduğunu doğrulayın (APPROVED durumu).
3. Gönderici numarasının aktif bir WhatsApp Business hesabına bağlı olduğunu kontrol edin.
4. Alıcı numarasının WhatsApp'a kayıtlı olduğunu doğrulayın.

Şablon Reddedildi

Meta şablon onay sürecinde içerik politikası ihlali tespit edebilir. Şablon metninin resmi ve kişisel veri içermediğinden emin olun. Gerekirse toplusms.app destek ekibinden yardım alın.