Skip to main content

​
Genel Bakış

Bu sayfa, WhatsApp Business entegrasyonunu kullanırken karşılaşabileceğiniz yaygın sorunları ve çözümlerini içerir. Her sorun için belirtiler, olası nedenler ve adım adım çözüm adımları sunulmaktadır.

​
Bağlantı Sorunları

Belirtiler:
  • Facebook Embedded Signup tamamlanamıyor
  • Hesap durumu setup_failed olarak görünüyor
  • Bağlantı süreci beklenmedik şekilde kapanıyor
Olası Nedenler:
  • Meta Business Manager’da yetki eksikliği
  • WhatsApp Business Hesabı (WABA) zaten başka bir uygulamaya bağlı
  • Facebook oturum süresi dolmuş
  • Tarayıcı pop-up engelleyicisi aktif
Çözüm:
  1. Meta Business Manager yetkilerini kontrol edin: Hesap bağlamayı yapan kullanıcının Meta Business Manager’da admin yetkisi olmalıdır
  2. Mevcut bağlantıları kontrol edin: WABA başka bir platforma bağlıysa, önce o bağlantıyı kesin
  3. Facebook oturumunu yenileyin: Facebook’tan çıkış yapın ve tekrar giriş yapın
  4. Pop-up engelleyicisini kapatın: Tarayıcınızın pop-up engelleyicisini bu site için devre dışı bırakın
  5. Farklı tarayıcı deneyin: Chrome veya Firefox’un güncel sürümünü kullanın
setup_failed durumundaki hesaplar için platform otomatik olarak yeniden deneme (setup_retry) yapar. Birkaç dakika bekleyip durumu kontrol edin.
Belirtiler:
  • Hesap uzun süredir setup_failed durumunda
  • Otomatik yeniden deneme de başarısız
Olası Nedenler:
  • Erişim anahtarı (access token) alınamadı
  • Webhook aboneliği oluşturulamadı
  • Telefon numarası kaydedilemedi
  • Meta API geçici hata
Çözüm:
  1. Hesabı tekrar bağlamayı deneyin: Mevcut bağlantı girişimini iptal edip yeniden başlatın
  2. Meta Business Manager’ı kontrol edin: WABA’nın Meta Business Manager’da görünür ve aktif olduğunu doğrulayın
  3. Telefon numarasını kontrol edin: Numara başka bir WhatsApp hesabında kayıtlı olmamalıdır
  4. Destek ekibi ile iletişime geçin: Sorun devam ederse teknik destek ekibine başvurun

​
Mesaj Gönderim Sorunları

Belirtiler:
  • Giden mesajlar failed durumuna düşüyor
  • AI yanıtı üretiliyor ama müşteriye ulaşamıyor
  • Mesaj kuyruğunda birikme var
Olası Nedenler:
  • Erişim anahtarı geçersiz veya süresi dolmuş
  • Telefon numarası engellenmiş
  • 24 saatlik müşteri penceresi kapanmış (şablonsuz gönderim)
  • Rate limit aşılmış
  • Devre kesici açık
Çözüm:Adım 1: Sağlık Durumunu Kontrol Edin
  1. WhatsApp hesap sayfasında sağlık panelini kontrol edin
  2. Tüm boyutların yeşil (Available) olduğunu doğrulayın
  3. Herhangi bir boyut kırmızı ise, hata açıklamasını okuyun
Adım 2: Erişim Anahtarını Kontrol Edin
  1. Hesap detayında erişim anahtarı durumunun geçerli olduğunu doğrulayın
  2. Geçersizse hesabı yeniden bağlayarak yeni anahtar alın
Adım 3: 24 Saat Kuralını Kontrol Edin
  1. Müşterinin son 24 saat içinde mesaj gönderip göndermediğini kontrol edin
  2. 24 saat penceresi kapalıysa, sadece onaylanmış şablon mesaj gönderilebilir
Adım 4: Devre Kesiciyi Kontrol Edin
  1. Devre kesici açıksa, mesaj gönderimi engellenmiştir
  2. Devre kesici otomatik olarak normalleşmektedir, birkaç dakika bekleyin
Erişim anahtarı geçersiz (access_token_invalid) hatası devre kesiciyi açar ve tüm mesaj gönderimlerini durdurur. Anahtarı yenilenmeden mesaj gönderilemez.
Belirtiler:
  • Mesaj sent durumunda kalıyor
  • delivered veya read durumuna geçmiyor
Olası Nedenler:
  • Müşterinin cihazı kapalı veya çekim dışı
  • Müşteri platformu WhatsApp kullanmıyor
  • Ağ sorunları
Çözüm:
  1. Mesaj durumunun sent olduğunu doğrulayın — bu, mesajın Meta sunucularına başarıyla iletildiğini gösterir
  2. delivered durumu müşterinin cihazına bağlıdır, platform tarafından kontrol edilemez
  3. Müşteri cihazı aktif olduğunda teslimat gerçekleşir
Belirtiler:
  • Mesajlar gönderilemeden devre kesici açılıyor
  • Kısa sürede çok sayıda başarısız gönderim
Olası Nedenler:
  • Erişim anahtarı geçersiz (en yaygın neden)
  • Rate limit sürekli aşılmış
  • Ağ bağlantı sorunları
  • Meta API geçici kesinti
Çözüm:
  1. Erişim anahtarını yenileyin: Hesabı yeniden bağlayarak geçerli bir anahtar alın
  2. Gönderim hacmini azaltın: Rate limit aşılıyorsa, gönderim hızını düşürün
  3. Meta API durumunu kontrol edin: Meta Platform Status sayfasını kontrol edin
  4. Devre kesici normalleşme: Platform, süresi dolan devre kesicileri otomatik normalleştirir (periyodik kontrol, en fazla 200 kayıt/tur)

​
Webhook Sorunları

Belirtiler:
  • Müşteri mesaj gönderiyor ama platformda görmüyor
  • Webhook olayları işleniyor
Olası Nedenler:
  • Webhook aboneliği kurulamamış
  • Webhook doğrulama anahtarı uyuşmuyor
  • Meta API geçici sorunu
Çözüm:
  1. Webhook aboneliğini kontrol edin: WhatsApp hesap detayında webhook durumunun aktif olduğunu doğrulayın
  2. Hesabı yeniden bağlayın: Bağlantı kesip yeniden bağlama, webhook aboneliğini yeniden kurar
  3. Meta App Dashboard’u kontrol edin: Meta Developers panelinde webhook konfigürasyonunu doğrulayın

​
AI Yanıt Sorunları

Belirtiler:
  • Müşteri mesaj gönderiyor ama AI yanıt vermiyor
  • Konuşmada sadece gelen mesajlar görünüyor
Olası Nedenler:
  • Agent WhatsApp kanalına bağlanmamış
  • whatsapp_messaging_channel yetkisi yok
  • Kredi bakiyesi yetersiz (< 0.2 kredi)
  • Devre kesici açık (AI turn başlatılmıyor)
  • Müşteri kara listede
  • AI turn taşma koruması tetiklendi (60 saniyede 5+ iptal)
Çözüm:Adım 1: Agent Yapılandırmasını Kontrol Edin
  1. Agent’ın WhatsApp kanalının etkin olduğunu doğrulayın
  2. Doğru WhatsApp hesabının seçili olduğunu kontrol edin
Adım 2: Yetkiyi Kontrol Edin
  1. Organizasyonun Enterprise planında olduğunu doğrulayın
  2. whatsapp_messaging_channel yetkisinin aktif olduğunu kontrol edin
Adım 3: Kredi Bakiyesini Kontrol Edin
  1. Kontrol Paneli’ndeki kredi kartını kontrol edin
  2. Bakiye 0.2’nin üzerinde olmalıdır
  3. Yetersizse kredi yükleyin
Adım 4: Devre Kesiciyi Kontrol Edin
  1. Sağlık panelinde devre kesici durumunu kontrol edin
  2. Açıksa otomatik normalleştirmeyi bekleyin
Belirtiler:
  • AI yanıtı üretimi uzun sürüyor
  • Müşteri yanıt beklerken sabırsızlanıyor
Olası Nedenler:
  • Çok uzun konuşma geçmişi (kontekst penceresi)
  • Karmaşık araç çağırıları
  • Debounce süresi yüksek ayarlanmış
  • LLM API gecikme
Çözüm:
  1. Debounce süresini ayarlayın: Çok yüksek debounce süresi AI yanıtının tetiklenmesini geciktirir (3-5 saniye önerilir)
  2. Sistem talimatlarını optimize edin: Gereksiz uzun talimatları kısaltın
  3. Araç sayısını sınırlayın: Çok sayıda araç tanımlı olması yanıt süresini artırabilir

​
Şablon Sorunları

Belirtiler:
  • Meta’da oluşturulan şablonlar platformda görünmüyor
  • Senkronizasyon butonu hata veriyor
Olası Nedenler:
  • Erişim anahtarı geçersiz
  • Meta API geçici hatası
  • WABA’da şablon bulunamıyor
Çözüm:
  1. Manuel senkronizasyon butonuna tıklayın
  2. Erişim anahtarının geçerli olduğunu doğrulayın
  3. Meta Business Manager’da şablonların görünür olduğunu kontrol edin
  4. Birkaç dakika bekleyip tekrar deneyin

​
Engellenmiş Telefon Numarası

Belirtiler:
  • Sağlık panelinde telefon numarası kırmızı (Blocked)
  • can_send_message durumu BLOCKED
  • Mesaj gönderilemiyor
Olası Nedenler:
  • Çok sayıda müşteri raporu (spam ihbarları)
  • WhatsApp politika ihlali
  • Kalite puanı çok düşük (Red)
Çözüm:
  1. Meta Business Manager’da engellemeleri kontrol edin
  2. Meta Business Destek ile iletişime geçin: Engellenmiş numaraların çözümü Meta tarafından yapılır
  3. Kalite puanını iyileştirin: Engelleme kaldırıldıktan sonra yaygın haberları önleyin
  4. Alternatif numara kullanın: Acil iletişim için farklı bir numarayı devreye alın
Engellenmiş telefon numaralarının çözümü Meta Business Destek üzerinden yapılır. Platform üzerinden doğrudan engellemeleri kaldırmak mümkün değildir.
WhatsApp engellenmiş telefon numarası sağlık görünümü

​
Hata Sınıflandırması

Platform, WhatsApp mesaj gönderim hatalarını otomatik olarak sınıflandırır:

​
Yeniden Denenebilir Hatalar

Hata KoduAçıklamaPlatform Davranışı
rate_limit_exceededMeta API hız sınırı aşıldıMesaj yeniden kuyruğa alınır
temporary_send_failureGeçici gönderim hatasıMesaj yeniden kuyruğa alınır
network_errorAğ bağlantı hatasıMesaj yeniden kuyruğa alınır

​
Kalıcı Hatalar

Hata KoduAçıklamaPlatform Davranışı
access_token_invalidErişim anahtarı geçersizMesaj başarısız, devre kesici açılır
auth_failureKimlik doğrulama hatasıMesaj başarısız, devre kesici açılır
permanent_send_failureKalıcı gönderim hatasıMesaj başarısız
send_failedGenel gönderim hatasıMesaj başarısız

​
Belirsiz Hatalar

Hata KoduAçıklamaPlatform Davranışı
network_timeoutAğ zaman aşımıBelirsiz — mesaj gönderilmiş olabilir
context_deadline_exceededİstek zaman aşımıBelirsiz — mesaj gönderilmiş olabilir

​
Meta Graph API Hata Kodları

Meta API’den dönen yaygın hata kodları:
HTTP DurumMeta KoduAçıklama
401—Kimlik doğrulama başarısız
403—Yetki yetersiz
429—Rate limit aşıldı
500+—Meta sunucu hatası (geçici)
—2Geçici API hatası (yeniden denenebilir)
—190Erişim anahtarı geçersiz veya süresi dolmuş
408, 409, 502, 503, 504—Geçici hatalar (yeniden denenebilir)

​
İpuçları ve En İyi Uygulamalar

  • ✅ Sağlık panelini düzenli olarak kontrol edin
  • ✅ Kalite puanını yeşilde tutmak için spam göndermekten kaçının
  • ✅ Mesaj şablonlarınızı düzenli olarak senkronize edin
  • ✅ Yetersiz kredi uyarısını yapılandırın
  • ✅ Devre kesici açıldığında hemen erişim anahtarını kontrol edin
  • ✅ Test ortamında yapılandırmaları doğruladıktan sonra üretime alın

​
İlgili Makaleler

Telefon Numarası Sağlığı

Sağlık izleme ve limit yönetimi

AI Mesajlaşma

Mesajlaşma akışı ve devre kesici detayları

Hesap Bağlama

Hesap durumları ve bağlantı sorunları

Genel Sorunlar

Platform geneli sorun giderme