> ## 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 AI Mesajlaşma — Yapay Zeka Destekli Konuşma Akışı

> WhatsApp üzerinden AI destekli mesajlaşma akışı. Gelen mesaj işleme, AI yanıt üretimi, araç/fonksiyon çağırıları, dağıtım motoru, devre kesici ve sistem mesajları.

## Genel Bakış

WhatsApp AI mesajlaşma, müşterilerinizden gelen WhatsApp mesajlarını işleyerek AI Agent'iniz aracılığıyla otomatik yanıtlar üreten, uçtan uca bir mesajlaşma çözümüdür. Tüm akış — mesaj alımı, oturum yönetimi, AI yanıt üretimi ve mesaj gönderimi — tamamen otomatik olarak gerçekleşir.

## Mesajlaşma Akışı (Uçtan Uca)

### 1. Gelen Mesaj Akışı

Müşteri WhatsApp üzerinden mesaj gönderdikten sonra aşağıdaki adımlar otomatik olarak gerçekleşir:

<Steps>
  <Step title="Webhook Alımı">
    Meta, mesajı platformun webhook endpoint'ine iletir. Platform, `X-Hub-Signature-256` başlığını kullanarak mesajın Meta'dan geldiğini doğrular
  </Step>

  <Step title="Olay İşleme">
    Webhook verisi şifrelenir, veritabanına kaydedilir ve olay türüne göre dallandırılır:

    * **Mesaj Alındı** — Yeni gelen mesaj
    * **Durum Güncellemesi** — Gönderilen mesajın teslimat durumu
    * **SMB Echo** — Başka cihazdan gönderilen mesaj yansıması
    * **Hesap Güncellemesi** — WABA hesap bilgi değişikliği
  </Step>

  <Step title="Müşteri Tanımla">
    Gelen mesajdaki WhatsApp ID ile müşteri kaydı eşleştirilir. Yeni bir müşteri ise otomatik olarak oluşturulur
  </Step>

  <Step title="Oturum Yönetimi">
    Aktif bir mesajlaşma oturumu var mı kontrol edilir. Yoksa yeni oturum başlatılır. Önceki oturum süresi dolmuşsa kapatılır ve yeni oturum oluşturulur
  </Step>

  <Step title="AI Turn Zamanlama">
    Gelen mesaj için bir AI turn (yanıt turu) zamanlanır. Birden fazla hızlı mesaj geldiğinde, debounce mekanizması ile tek bir AI turu oluşturulur
  </Step>
</Steps>

### 2. AI Yanıt Üretimi

AI turn tetiklendikten sonra:

<Steps>
  <Step title="Turn Talep Etme">
    AI turn işleme için talep edilir ve kilit alınır. Eşitlik sağlamak için aynı anda birden fazla çalışan işlem, aynı turn'u işleyemez
  </Step>

  <Step title="Ön Kontroller">
    Sırayla aşağıdaki kontroller yapılır:

    * `whatsapp_messaging_channel` yetkisi kontrol edilir
    * Çok sayıda iptal edilen AI turu tespit edildiğinde taşma koruması devreye girer
    * WhatsApp devre kesici durumu kontrol edilir
    * Organizasyonun kredi bakiyesi kontrol edilir (minimum 0.2 kredi gerekli)
  </Step>

  <Step title="Kontekst Yükleme">
    AI modeli için gerekli veriler yüklenir:

    * Agent yapılandırması ve sistem talimatları
    * Son 80 bağlam zaman çizelgesi öğesi
    * Ardından birleşik mesajlar oluşturulur (aynı yöndeki ardışık metin mesajlar birleştirilerek en fazla 20 öğeye indirgenir)
  </Step>

  <Step title="AI Yanıt Üretimi">
    LLM (büyük dil modeli) çağrılır ve yanıt üretilir. Yanıt metin içeriyorsa doğrudan kullanılır. Araç çağırısı içeriyorsa, araç çalıştırılır ve sonuç LLM'e geri beslenir (en fazla 2 adım, adım başına en fazla 5 araç çağırısı)
  </Step>

  <Step title="Sonuçlandırma">
    Üretilen yanıt şifrelenir, veritabanına kaydedilir, kredi düşülür (0.2 kredi/yanıt) ve gönderim kuyruğuna yayınlanır
  </Step>
</Steps>

### 3. Giden Mesaj Dağıtımı

<Steps>
  <Step title="Kuyruk Teslimi">
    Gönderilecek mesaj dağıtım kuyruğundan alınır ve kilit koyulur (eş zamanlı en fazla 50 işlem)
  </Step>

  <Step title="Gönderim Ön Kontrol">
    Yetki, devre kesici durumu ve gerekli alanların (erişim anahtarı, telefon numarası, müşteri numarası) tamlığını kontrol edilir
  </Step>

  <Step title="Meta API Gönderimi">
    Mesaj, mesaj türüne uygun formatta Meta WhatsApp Cloud API'ye gönderilir
  </Step>

  <Step title="Sonuç İşleme">
    Gönderim sonucuna göre:

    * **Başarılı** → Mesaj `accepted` durumuna geçilir, devre kesici başarı kaydedilir
    * **Yeniden Denenebilir Hata** → Mesaj yeniden kuyruğa alınır (en fazla 3 deneme)
    * **Kalıcı Hata** → Mesaj `failed` durumuna geçilir
    * **Belirsiz** → Mesaj `dispatch_unknown` durumuna geçilir
  </Step>
</Steps>

## Mesajlaşma Oturumları

Her WhatsApp konuşması bir **mesajlaşma oturumu** içerisinde yönetilir:

* **Oturum Başlangıcı**: Müşteriden gelen ilk mesajla otomatik başlar
* **Oturum Süresi**: Yapılandırılabilir hareketsizlik zaman aşımıyla (varsayılan değer agent ayarlarında belirlenir)
* **Oturum Sonu**: Zaman aşımı, AI aracı ile kapatma veya manuel kapatma ile sonlanır
* **Oturum Sonrası**: Analiz, yapılandırılmış çıktı oluşturma ve transkript üretimi başlatılır

<Info>
  Her AI yanıtı 0.2 kredi tüketir. Kredi bakiyeniz yetersiz olduğunda müşteriye otomatik bir sistem mesajı gönderilir (yapılandırıldıysa).
</Info>

## Araç/Fonksiyon Çağırıları

AI Agent'iniz WhatsApp üzerinden de araç (tool/function) çağırılarını kullanabilir:

### Yerleşik Araçlar

* **Oturumu Sonlandır**: Konuşmayı programatik olarak kapatır
* **Özel Aksiyon**: HTTP webhook ile dış sistemlerle entegrasyon
* **Müşteri Opt-Out**: Müşteriyi mesajlaşma listesinden çıkarır

### Araç Döngüsü Limitleri

| Parametre                          | Limit |
| ---------------------------------- | ----- |
| Maksimum araç döngüsü adımı        | 2     |
| Adım başına maksimum araç çağırısı | 5     |

<Warning>
  Araç döngüsü limiti aşıldığında AI yanıtı `tool_loop_limit_exceeded` hatasıyla sonlanır ve müşteriye yanıt gönderilmez.
</Warning>

## Teslimat Durumları

Gönderilen mesajların teslimat durumu gerçek zamanlı olarak izlenir:

| Durum         | Açıklama                                |
| ------------- | --------------------------------------- |
| **sent**      | Mesaj Meta sunucularına iletildi        |
| **delivered** | Mesaj müşterinin cihazına teslim edildi |
| **read**      | Müşteri mesajı okudu                    |
| **failed**    | Mesaj gönderilemedi                     |

Teslimat durumları, mesaj detay sayfasındaki durum loglarından takip edilebilir.

<Frame>
  <img src="https://mintcdn.com/aiagenttr/EsPj4y2_ld-gNsL8/images/whatsapp-conversation-detail.png?fit=max&auto=format&n=EsPj4y2_ld-gNsL8&q=85&s=58fbe961a683781c1d34daeef466c002" alt="WhatsApp konuşma detay sayfası — mesaj durumları ve zaman çizelgesi" width="1358" height="821" data-path="images/whatsapp-conversation-detail.png" />
</Frame>

## Devre Kesici Mekanizması

Platform, WhatsApp mesaj gönderim hatalarında otomatik devre kesici (circuit breaker) mekanizması uygular:

### Nasıl Çalışır?

1. Bir mesaj gönderimi başarısız olduğunda ve hata kodu devre kesici açmayı gerektiriyorsa, ilgili WhatsApp hesabı için devre kesici **açılır**
2. Devre kesici açık olduğunda, o hesaptan yeni mesaj gönderimi **engellenir**
3. AI yanıt üretimi de devre kesici açıkken **atlanır** (gereksiz kredi tüketimi önlenir)
4. Platform, süresi dolan devre kesicileri otomatik olarak **normalleştirir** (en fazla 200 kayıt/tur)

### Devre Kesiciyi Açan Durumlar

| Hata Türü                | Kod                      | Devre Kesici            |
| ------------------------ | ------------------------ | ----------------------- |
| Erişim anahtarı geçersiz | `access_token_invalid`   | ✅ Açılır                |
| Kimlik doğrulama hatası  | `auth_failure`           | ✅ Açılır                |
| Rate limit aşıldı        | `rate_limit_exceeded`    | ✅ Açılır                |
| Geçici gönderim hatası   | `temporary_send_failure` | ✅ Açılır                |
| Ağ zaman aşımı           | `network_timeout`        | ✅ Açılır                |
| Ağ hatası                | `network_error`          | ✅ Açılır                |
| Kalıcı gönderim hatası   | `permanent_send_failure` | Kimlik hatasıysa açılır |
| Bağlam iptal edildi      | `context_canceled`       | ❌ Açılmaz               |
| Genel gönderim hatası    | `send_failed`            | ❌ Açılmaz               |

<Note>
  Devre kesici normalleşme işlemi arka planda periyodik olarak çalışır. Acil durumlarda destek ekibi ile iletişime geçin.
</Note>

## Sistem Mesajları

Platform, belirli durumlarda müşterilere otomatik sistem mesajları gönderir:

### Oturum Zaman Aşımı Mesajı

Oturum hareketsizlik nedeniyle sonlandığında, yapılandırıldıysa müşteriye bir kapanış mesajı gönderilir.

### Yetersiz Kredi Mesajı

Organizasyonun kredi bakiyesi 0.2'nin altına düştüğünde, müşteriye otomatik bir bilgilendirme mesajı gönderilir (yapılandırıldıysa). Bu mesaj, belirli bir periyot içinde bir kez gönderilir (tekrar önleme).

**Sistem mesajı atlama nedenleri:**

* Oturum uygun değil
* Davranış `silent` olarak ayarlanmış
* Mesaj metni boş
* Aynı mesaj zaten kuyrukta
* 24 saatlik müşteri penceresi kapanmış

## İlgili Makaleler

<CardGroup cols={2}>
  <Card title="Desteklenen Mesaj Türleri" icon="messages" href="/docs/whatsapp/supported-message-types">
    Aktif ve planlanan mesaj türleri
  </Card>

  <Card title="Mesaj Şablonları" icon="file-lines" href="/docs/whatsapp/message-templates">
    24 saat penceresi ve şablon yönetimi
  </Card>

  <Card title="Ajan Yapılandırması" icon="gear" href="/docs/whatsapp/agent-configuration">
    AI Agent WhatsApp ayarları
  </Card>

  <Card title="Sorun Giderme" icon="wrench" href="/docs/whatsapp/troubleshooting">
    AI yanıt ve gönderim sorunları
  </Card>
</CardGroup>