Sohbetler API

Tüm isteklerde X-Tenant header’ı zorunludur. Konuşmalar, mesajlar ve kanallar sıkı bir tenant izolasyonuna tabidir.

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

Tüm parametreler, alanlar ve örnek istek/yanıtlar için API Referansı sekmesine bakın.

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

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

address alanı otomatik olarak temizlenir ve uluslararası formata (normalize) çevrilir.

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

Mesaj gönderme

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:

{
  "status": "queued",
  "message_id": "...",
  "conversation_id": 1
}

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.

Kanalın maxMessageLength ve supportedMediaTypes kısıtlamaları gönderim öncesinde kontrol edilir. Bu limitleri aşan mesajlar reddedilir.

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

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.

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

Mesaj düzenleme ve silme

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.

Mesaj geçmişi

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

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

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

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

AI Agent kontrolü

Agent durum yanıtı: GET .../agent endpoint’i aşağıdaki yapıda yanıt döner:

{
  "agent_disabled": true,
  "agent_expires_at": "...",
  "agent_disabled_by_user_name": "...",
  "remaining_minutes": 25
}

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.

Export

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

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

AI Suggestion (Yarı-Otonom AI)

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

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.

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.

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

Tüm “Conversation” işlemleri uygulama içinde tek bir ortak izne (permission) bağlanmıştır.

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`

Başlarken

Kimlik Doğrulama

Multi-Tenancy

İstekler

Hesap & Yetki

Kullanıcılar

Hasta Yönetimi

Randevu & Tedavi

Mesajlaşma

Operasyon & Loglar

Satış & Finans

Ürün Yönetimi

Stok Yönetimi

Ayarlar

AI

Realtime

Entegrasyonlar

Rehberler

Kaynaklar

Endpoint özeti

Konuşma ve mesaj kavramı

İş kuralları

Konuşma başlatma

Mesaj gönderme

Mesaj düzenleme ve silme

Mesaj geçmişi

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

AI Agent kontrolü

Export

AI Suggestion (Yarı-Otonom AI)

Gerçek zamanlı event’ler

Yetkilendirme

Uygulama izinleri (permissions)

Token scope’ları (Passport)

​Endpoint özeti

​Konuşma ve mesaj kavramı

​İş kuralları

​Konuşma başlatma

​Mesaj gönderme

​Mesaj düzenleme ve silme

​Mesaj geçmişi

​Okundu işlemi (POST .../read)

​AI Agent kontrolü

​Export

​AI Suggestion (Yarı-Otonom AI)

​Gerçek zamanlı event’ler

​Yetkilendirme

​Uygulama izinleri (permissions)

​Token scope’ları (Passport)

Endpoint özeti

Konuşma ve mesaj kavramı

İş kuralları

Konuşma başlatma

Mesaj gönderme

Mesaj düzenleme ve silme

Mesaj geçmişi

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

AI Agent kontrolü

Export

AI Suggestion (Yarı-Otonom AI)

Gerçek zamanlı event’ler

Yetkilendirme

Uygulama izinleri (permissions)

Token scope’ları (Passport)