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

​
Endpoint özeti

MetotEndpointAçıklama
GET/api/v1/conversationsGelen kutusunu (konuşma listesi) getirir
POST/api/v1/conversationsYeni 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}/messagesKonuşmanın mesaj geçmişini getirir
POST/api/v1/conversations/{id}/messagesMetin mesajı gönderir
POST/api/v1/conversations/{id}/messages/mediaMedya (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}/readMüşteri mesajlarını okundu işaretler
GET/api/v1/conversations/{id}/agentAI agent durumunu getirir
POST/api/v1/conversations/{id}/agent/disableAI agent’ı devre dışı bırakır
POST/api/v1/conversations/{id}/agent/enableAI agent’ı aktif eder
POST/api/v1/conversations/{id}/exportKonuşmayı dışa aktarır
GET/api/v1/conversations/{id}/ai-suggestionBekleyen AI önerisini getirir
POST/api/v1/conversations/{id}/ai-suggestion/sendAI önerisini gönderir
POST/api/v1/conversations/{id}/ai-suggestion/dismissAI önerisini reddeder
PUT/api/v1/conversations/{id}/ai-suggestion/ratingAI önerisini oylar (up / down)
POST/api/v1/conversations/{id}/ai-suggestion/regenerateAI ö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

EventTetiklenme
ChatLogUpdatedMesaj düzenlendiğinde
ChatLogDeletedMesaj soft delete edildiğinde
ConversationReadOkundu işlemi yapıldığında
AiSuggestionCreatedYeni 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)

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

​
Token scope’ları (Passport)

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