> ## Documentation Index
> Fetch the complete documentation index at: https://aiagenttr.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Sorun Giderme — Yaygın Sorunlar ve Çözümleri

> WhatsApp Business entegrasyonunda karşılaşılan yaygın sorunlar. Hesap bağlama, mesaj gönderim, webhook, AI yanıt, şablon senkronizasyon, devre kesici ve hata kodları rehberi.

## 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ı

<AccordionGroup>
  <Accordion title="WhatsApp Hesap Bağlantısı Başarısız Oluyor">
    **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

    <Info>
      `setup_failed` durumundaki hesaplar için platform otomatik olarak yeniden deneme (`setup_retry`) yapar. Birkaç dakika bekleyip durumu kontrol edin.
    </Info>
  </Accordion>

  <Accordion title="Hesap Durumu 'setup_failed' Kalıyor">
    **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
  </Accordion>
</AccordionGroup>

## Mesaj Gönderim Sorunları

<AccordionGroup>
  <Accordion title="Mesajlar Gönderilemiyor">
    **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

    <Warning>
      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.
    </Warning>
  </Accordion>

  <Accordion title="Mesajlar Teslim Edilemiyor (delivered Durumuna Geçmiyor)">
    **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
  </Accordion>

  <Accordion title="Devre Kesici Sürekli Tetikleniyor">
    **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](https://metastatus.com/) 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)
  </Accordion>
</AccordionGroup>

## Webhook Sorunları

<AccordionGroup>
  <Accordion title="Gelen Mesajlar Alınmıyor">
    **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
  </Accordion>
</AccordionGroup>

## AI Yanıt Sorunları

<AccordionGroup>
  <Accordion title="AI Yanıtları Üretilmiyor">
    **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
  </Accordion>

  <Accordion title="AI Yanıtları Yavaş Geliyor">
    **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
  </Accordion>
</AccordionGroup>

## Şablon Sorunları

<AccordionGroup>
  <Accordion title="Şablonlar Senkronize Edilemiyor">
    **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
  </Accordion>
</AccordionGroup>

## Engellenmiş Telefon Numarası

<AccordionGroup>
  <Accordion title="Telefon Numarası Engellendi">
    **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

    <Warning>
      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.
    </Warning>

    <Frame>
      <img src="https://mintcdn.com/aiagenttr/EsPj4y2_ld-gNsL8/images/whatsapp-health-blocked.png?fit=max&auto=format&n=EsPj4y2_ld-gNsL8&q=85&s=7c3a0b65275056f88a68134a313ab376" alt="WhatsApp engellenmiş telefon numarası sağlık görünümü" width="1358" height="821" data-path="images/whatsapp-health-blocked.png" />
    </Frame>
  </Accordion>
</AccordionGroup>

## Hata Sınıflandırması

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

### Yeniden Denenebilir Hatalar

| Hata Kodu                | Açıklama                   | Platform Davranışı           |
| ------------------------ | -------------------------- | ---------------------------- |
| `rate_limit_exceeded`    | Meta API hız sınırı aşıldı | Mesaj yeniden kuyruğa alınır |
| `temporary_send_failure` | Geçici gönderim hatası     | Mesaj yeniden kuyruğa alınır |
| `network_error`          | Ağ bağlantı hatası         | Mesaj yeniden kuyruğa alınır |

### Kalıcı Hatalar

| Hata Kodu                | Açıklama                 | Platform Davranışı                   |
| ------------------------ | ------------------------ | ------------------------------------ |
| `access_token_invalid`   | Erişim anahtarı geçersiz | Mesaj başarısız, devre kesici açılır |
| `auth_failure`           | Kimlik doğrulama hatası  | Mesaj başarısız, devre kesici açılır |
| `permanent_send_failure` | Kalıcı gönderim hatası   | Mesaj başarısız                      |
| `send_failed`            | Genel gönderim hatası    | Mesaj başarısız                      |

### Belirsiz Hatalar

| Hata Kodu                   | Açıklama          | Platform Davranışı                    |
| --------------------------- | ----------------- | ------------------------------------- |
| `network_timeout`           | Ağ 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 Durum              | Meta Kodu | Açıklama                                    |
| ----------------------- | --------- | ------------------------------------------- |
| 401                     | —         | Kimlik doğrulama başarısız                  |
| 403                     | —         | Yetki yetersiz                              |
| 429                     | —         | Rate limit aşıldı                           |
| 500+                    | —         | Meta sunucu hatası (geçici)                 |
| —                       | 2         | Geçici API hatası (yeniden denenebilir)     |
| —                       | 190       | Erişim anahtarı geçersiz veya süresi dolmuş |
| 408, 409, 502, 503, 504 | —         | Geçici hatalar (yeniden denenebilir)        |

## İpuçları ve En İyi Uygulamalar

<Tip>
  * ✅ 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
</Tip>

## İlgili Makaleler

<CardGroup cols={2}>
  <Card title="Telefon Numarası Sağlığı" icon="heart-pulse" href="/docs/whatsapp/phone-number-health">
    Sağlık izleme ve limit yönetimi
  </Card>

  <Card title="AI Mesajlaşma" icon="robot" href="/docs/whatsapp/ai-messaging">
    Mesajlaşma akışı ve devre kesici detayları
  </Card>

  <Card title="Hesap Bağlama" icon="link" href="/docs/whatsapp/account-connection">
    Hesap durumları ve bağlantı sorunları
  </Card>

  <Card title="Genel Sorunlar" icon="circle-question" href="/docs/troubleshooting/general-issues">
    Platform geneli sorun giderme
  </Card>
</CardGroup>