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

# Sohbetler API

> Kliniğin WhatsApp vb. iletişim kanalları üzerinden hastalarla yaptığı görüşmeleri yönetmek için endpoint'ler.

<Note>
  Tüm isteklerde `X-Tenant` header'ı **zorunludur**. Konuşmalar, mesajlar ve kanallar sıkı bir **tenant izolasyonuna** tabidir.
</Note>

## Endpoint özeti

| Metot    | Endpoint                                              | Açıklama                                                   |
| -------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| `GET`    | `/api/v1/conversations`                               | Gelen kutusunu (konuşma listesi) getirir                   |
| `POST`   | `/api/v1/conversations`                               | Yeni konuşma başlatır veya mevcut konuşmaya müşteri bağlar |
| `DELETE` | `/api/v1/conversations/{id}`                          | Konuşmayı soft delete eder                                 |
| `GET`    | `/api/v1/conversations/{id}/messages`                 | Konuşmanın mesaj geçmişini getirir                         |
| `POST`   | `/api/v1/conversations/{id}/messages`                 | Metin mesajı gönderir                                      |
| `POST`   | `/api/v1/conversations/{id}/messages/media`           | Medya (dosya / görsel) mesajı gönderir                     |
| `PUT`    | `/api/v1/conversations/{id}/messages/{messageId}`     | Mesajı düzenler                                            |
| `DELETE` | `/api/v1/conversations/{id}/messages/{messageId}`     | Mesajı soft delete eder                                    |
| `POST`   | `/api/v1/conversations/{id}/read`                     | Müşteri mesajlarını okundu işaretler                       |
| `GET`    | `/api/v1/conversations/{id}/agent`                    | AI agent durumunu getirir                                  |
| `POST`   | `/api/v1/conversations/{id}/agent/disable`            | AI agent'ı devre dışı bırakır                              |
| `POST`   | `/api/v1/conversations/{id}/agent/enable`             | AI agent'ı aktif eder                                      |
| `POST`   | `/api/v1/conversations/{id}/export`                   | Konuşmayı dışa aktarır                                     |
| `GET`    | `/api/v1/conversations/{id}/ai-suggestion`            | Bekleyen AI önerisini getirir                              |
| `POST`   | `/api/v1/conversations/{id}/ai-suggestion/send`       | AI önerisini gönderir                                      |
| `POST`   | `/api/v1/conversations/{id}/ai-suggestion/dismiss`    | AI önerisini reddeder                                      |
| `PUT`    | `/api/v1/conversations/{id}/ai-suggestion/rating`     | AI önerisini oylar (`up` / `down`)                         |
| `POST`   | `/api/v1/conversations/{id}/ai-suggestion/regenerate` | AI önerisini yeniden üretir                                |

<Tip>
  Tüm parametreler, alanlar ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Konuşma ve mesaj kavramı

Sohbetler API'si, kliniğin **WhatsApp vb. iletişim kanalları** üzerinden hastalarla (müşterilerle) yaptığı görüşmeleri yönetir.

Bir **konuşma (conversation)**; ilgili iletişim kanalı (`channel`), normalize edilmiş bir telefon numarası (`address`) ve kayıtlı bir müşteri (`customer`) ile ilişkilidir.

## İş kuralları

### Konuşma başlatma

<Tip>
  **Konuşma başlatma idempotent çalışır:** Aynı numara ve kanal için tekrar istek atılırsa mevcut konuşmayı döner.
</Tip>

<Note>
  `address` alanı otomatik olarak temizlenir ve uluslararası formata (normalize) çevrilir.
</Note>

<Note>
  Konuşma başlatırken sistemde bu numarayla eşleşen **soft-delete** edilmiş bir hasta varsa sistem onu geri getirir (`restore`).
</Note>

### Mesaj gönderme

<Warning>
  **Asenkron gönderim (`202 Queued`):** Mesaj gönderme istekleri (`POST .../messages` ve `.../messages/media`) API tarafından **anında işlenip karşı tarafa iletilmez**. İstek alındığında `OutboundMessageDispatcher` üzerinden arka plan kuyruğuna eklenir ve API `202 Accepted` durum koduyla yanıt döner:

  ```json theme={null}
  {
    "status": "queued",
    "message_id": "...",
    "conversation_id": 1
  }
  ```
</Warning>

<Info>
  **AI Agent duraklatma:** API üzerinden manuel bir mesaj (metin veya medya) gönderildiğinde, aktif bir yapay zeka asistanı (bot) **o konuşma için 30 dakika boyunca otomatik olarak devre dışı bırakılır**.
</Info>

<Warning>
  Kanalın **`maxMessageLength`** ve **`supportedMediaTypes`** kısıtlamaları gönderim öncesinde kontrol edilir. Bu limitleri aşan mesajlar reddedilir.
</Warning>

<Note>
  Metin mesajlarında (`POST .../messages`) isteğe bağlı `quoted_message_id` alanı gönderilerek başka bir mesaj alıntılanabilir.
</Note>

<Warning>
  **Medya mesajı formatı:** Bu istek JSON olarak yapılamaz. Body formatı kesinlikle **`multipart/form-data`** olmalıdır. Maksimum dosya boyutu **50 MB**'dır.
</Warning>

<Tip>
  **MIME tipi otomatik tespiti:** Sistem yüklenen dosyanın MIME tipini otomatik analiz eder ve mesaj tipini (`image`, `video`, `audio`, `document`) kendisi belirler.
</Tip>

### Mesaj düzenleme ve silme

<Note>
  Mesaj silme (`DELETE .../messages/{messageId}`) gerçek bir veritabanı silme işlemi **değildir**; ilgili kayıt üzerinde `is_deleted=true` set edilir. Silme işlemi `ChatLogDeleted` event'i broadcast eder.
</Note>

### Mesaj geçmişi

<Info>
  **Sıralama:** Mesajlar her zaman en yenisi en üstte olacak şekilde sıralanır (tarihe göre azalan).
</Info>

### Okundu işlemi (`POST .../read`)

Konuşmadaki müşteriden gelen okunmamış mesajları okundu olarak işaretler.

<Info>
  İşlem tamamlandığında `ConversationRead` eventi broadcast edilir (gerçek zamanlı güncelleme).
</Info>

### AI Agent kontrolü

<Info>
  **Agent durum yanıtı:** `GET .../agent` endpoint'i aşağıdaki yapıda yanıt döner:

  ```json theme={null}
  {
    "agent_disabled": true,
    "agent_expires_at": "...",
    "agent_disabled_by_user_name": "...",
    "remaining_minutes": 25
  }
  ```
</Info>

<Note>
  Agent devre dışı bırakırken (`POST .../agent/disable`) `duration_minutes` alanı opsiyoneldir. Min: `1`, maks: `525600` (\~1 yıl). Gönderilmezse süresiz devre dışı kalır.
</Note>

### Export

`POST .../export` ile konuşma dışa aktarılır. Desteklenen formatlar: `json`, `csv`, `txt`, `html`.

<Note>
  `message_count` (maks. 10.000) veya `export_all=true` ile aktarılacak mesaj miktarı belirlenebilir. `include_context` parametresi bağlam verilerini dahil eder.
</Note>

### AI Suggestion (Yarı-Otonom AI)

Bu endpoint grubu, yapay zekanın oluşturduğu yanıt önerilerini yönetir.

<Note>
  **Regenerate davranışı:** `POST .../ai-suggestion/regenerate` isteği, trigger olan chat log'larını `is_processed=false` olarak işaretler ve `ProcessBufferedMessagesJob`'u AI kuyruğuna atar. Yeni öneri asenkron oluşturulur ve `AiSuggestionCreated` broadcast event'i ile gelir.
</Note>

<Note>
  **Send davranışı:** `send_source` alanı `suggestion_as_is` veya `suggestion_edited` değerini alır. `suggestion_edited` seçilirse `message` alanı zorunludur. `take_over_agent=true` gönderilirse agent manuel mesajla birlikte devreden çıkarılır.
</Note>

### Gerçek zamanlı event'ler

| Event                 | Tetiklenme                                            |
| --------------------- | ----------------------------------------------------- |
| `ChatLogUpdated`      | Mesaj düzenlendiğinde                                 |
| `ChatLogDeleted`      | Mesaj soft delete edildiğinde                         |
| `ConversationRead`    | Okundu işlemi yapıldığında                            |
| `AiSuggestionCreated` | Yeni AI önerisi oluşturulduğunda (regenerate sonrası) |

## Yetkilendirme

<Note>
  Tüm "Conversation" işlemleri uygulama içinde **tek bir ortak izne** (permission) bağlanmıştır.
</Note>

### Uygulama izinleri (permissions)

| İşlem                                                                           | Gerekli izin       |
| ------------------------------------------------------------------------------- | ------------------ |
| Tüm işlemler (okuma, yazma, silme, dosya yükleme, export, agent, AI suggestion) | `View:ChatLogPage` |

### Token scope'ları (Passport)

| İşlem                                                                                                                             | Scope                 |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Okuma (`index`, `messages`, `agent`, `ai-suggestion`, `export`)                                                                   | `conversations:read`  |
| Yazma / silme (`store`, `sendMessage`, `sendMediaMessage`, `destroy`, `read`, `agent/disable`, `agent/enable`, `ai-suggestion/*`) | `conversations:write` |