> ## 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 > Sohbetleri listelemeyi, oluşturmayı, okundu işaretlemeyi, arşivlemeyi, etiketlemeyi, dışa aktarmayı ve görünürlük kurallarını anlatır. Sohbet, kliniğin bir kanalı (WhatsApp, Instagram, Telegram veya web sitesi widget'ı) ile bir kişinin adresi arasındaki yazışmadır. Her kanal ve adres çifti için tek bir sohbet vardır. Bu sayfa sohbet kaydının kendisini yönetir: listeleme, oluşturma, okundu durumu, arşiv, etiket, dışa aktarma ve silme. Mesaj göndermek, mesaj düzenlemek ve tepki eklemek için [Mesajlar](/api/kaynaklar/mesajlar) sayfasına bakın. Sohbetteki AI asistanı durdurmak veya önerileri yönetmek için [AI asistan](/api/kaynaklar/ai-asistan) sayfasına bakın. Sohbetin kanalı pasifse (kanalın **Aktif** anahtarı kapalıysa) sohbet kaydı okunabilir ve yönetilebilir kalır; ama o sohbette gönderim `422 CHANNEL_INACTIVE` ile reddedilir. Ayrıntı için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın. Tüm isteklerde `Authorization: Bearer ` ve `X-Tenant: ` başlıkları gerekir. Başlıklar için [Başlıklar](/api/istekler/basliklar), `X-Tenant` için [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant) sayfasına bakın. ## Endpoint özeti Yol önekinin tamamı `https://app.flextell.ai/api/v1` şeklindedir. Tabloda yalnızca bu sayfanın konusu olan endpoint'ler yer alır. | Metot | Endpoint | Açıklama | Scope | İzin | | - | - | - | - | - | | GET | `/conversations` | Sohbetleri listeler. | `conversations:read` | `View:Conversation` | | POST | `/conversations` | Sohbet oluşturur veya var olanı döndürür. | `conversations:write` | `Create:Conversation` | | GET | `/conversations/{id}` | Tek sohbeti getirir. | `conversations:read` | `View:Conversation` | | DELETE | `/conversations/{id}` | Sohbeti siler. | `conversations:write` | `Delete:Conversation` | | POST | `/conversations/{id}/open` | Sohbeti açar, hasta mesajlarını okundu yapar. | `conversations:read` ve `conversations:write` | `View:Conversation` | | POST | `/conversations/{id}/read` | Sohbetteki hasta mesajlarını okundu yapar. | `conversations:write` | `View:Conversation` | | POST | `/conversations/read-all` | Görebildiğiniz tüm sohbetleri okundu yapar. | `conversations:write` | `View:Conversation` | | POST | `/conversations/{id}/archive` | Sohbeti arşivler. | `conversations:write` | `Archive:Conversation` | | POST | `/conversations/{id}/unarchive` | Sohbeti arşivden çıkarır. | `conversations:write` | `Archive:Conversation` | | PUT | `/conversations/{id}/tags` | Sohbetin etiket kümesini değiştirir. | `conversations:write` | `ManageTags:Conversation` | | POST | `/conversations/{id}/export` | Sohbeti dosya olarak dışa aktarır. | `conversations:read` | `Export:Conversation` | Scope ve izin farkı: scope, uygulamanın token'ına verilen erişimdir. İzin, token sahibi kullanıcının klinikteki rolünden gelir. İkisi birden gerekir; eksik olan `403 FORBIDDEN` döndürür. Ayrıntı için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın. ## Nesne modeli `GET /conversations` ve `GET /conversations/{id}` aynı alanları döndürür. Oluşturma, arşivleme ve etiket yanıtları daha kısa bir şekil taşır (aşağıdaki not). | Alan | Tür | Açıklama | | - | - | - | | `id` | tam sayı | Sohbet kimliği. | | `display_name` | metin | Kişinin adı ve soyadı. Kişi kaydı yoksa adres. Kısıtlı kayıtta maskelidir. | | `address` | metin veya `null` | Kanaldaki adres. Gizli WhatsApp numarasında `null`, kısıtlı kayıtta maskelidir. | | `hidden_number` | mantıksal | WhatsApp'ta numarası gizli kişi. | | `visitor_id`, `source` | metin | Web sitesi widget'ı sohbetlerinde dolu. `source` değeri `website`. | | `record_state` | nesne | `{is_read_only, reason_code}`. `reason_code`: `CUSTOMER_ERASED` veya `LEAD_NOT_ASSIGNED`. | | `customer` | nesne | Yalnızca sohbetin bağlı olduğu kişi varsa gelir. Alanlar aşağıda. | | `channel` | nesne | `{id, name, type, provider, address}`. | | `last_message`, `last_message_at`, `last_message_type`, `last_message_media_type`, `last_message_is_customer`, `last_message_is_deleted` | çeşitli | Son mesajın önizlemesi. Silinmiş mesaj için `Bu mesaj silindi`. | | `last_customer_message` | nesne veya `null` | Hastanın son mesajı. Anahtar her zaman bulunur. | | `unread_count` | tam sayı | Okunmamış hasta mesajı sayısı. Ekibin tamamı için ortaktır. | | `agent_disabled`, `agent_expires_at`, `agent_disabled_by_user_name` | çeşitli | AI asistanın bu sohbet için duraklatma durumu. | | `is_archived`, `archived_at`, `archived_by_user_name` | çeşitli | Arşiv durumu. | | `lines[]` | dizi | Kişinin tüm WhatsApp hatlarındaki sohbetleri: `conversation_id`, `channel_id`, `channel_name`, `channel_address`, `channel_status`, `last_message_at`, `unread_count`, `is_archived`. | | `tags[]` | dizi | Sohbete atanmış etiketler. | | `blacklist` | nesne veya `null` | Kişinin bu kanaldaki etkin engel kaydı. | `customer` nesnesinde şu alanlar bulunur: `id`, `first_name`, `last_name`, `phone_number`, `avatar_url`, `is_masked`, `is_lead_stage`, `lead_id`, `lead_stage` (`id`, `name`, `next_stage_id`; yalnız lead aşamasındaki kişide), `erased_at`, `open_tasks_count`, `notes_count`. `POST /conversations` yanıtında yalnızca kişi, kanal ve son mesaj bilgisi gelir. `tags`, `lines`, `blacklist` ve görev/not sayaçları yoktur; `unread_count` 0'dır. `archive`, `unarchive` ve `tags` yanıtları `tags` ile `archived_by_user_name` ekler, ama `lines`, `blacklist` ve sayaçları taşımaz. Tarihler klinik saat diliminde, saat farkıyla döner (`2026-10-12T14:30:00+03:00`). Yanıtta `X-Timezone` başlığı bulunur. ## Listeleme ve filtreler `GET /conversations` sayfalı bir liste döndürür. Varsayılan sayfa boyutu 15, en fazla 100'dür (`per_page`). Sayfalama biçimi için [Sayfalama](/api/istekler/sayfalama) sayfasına bakın. Sıralama son mesaj zamanına göredir; en yeni mesajı olan sohbet önce gelir. `search` varsa önce eşleşme alaka düzeyi sayılır. | Parametre | Açıklama | | - | - | | `search` | En fazla 255 karakter. Yalnızca kişi adı, soyadı ve adreste arar. Her kelime ön ek olarak eşleşir, kelimelerin hepsi aranır. Mesaj metninde aramaz. | | `scope` | `assigned` veya `all`. `assigned`: yalnızca lead'i size atanmış sohbetler. `all` (varsayılan): görmeye yetkili olduğunuz her sohbet. | | `channel_type` | `whatsapp`, `instagram`, `website` veya `telegram`. | | `channel_ids[]` | Klinik kanallarının kimlikleri. | | `archived` | `true` veya `false`. Varsayılan: yalnızca arşivde olmayanlar. | | `archive_states[]` | `active`, `archived`. `archived` parametresine üstündür. İkisini birden verirseniz hepsi döner. | | `archived_at_from`, `archived_at_to` | Arşivlenme tarihi aralığı. Klinik saat dilimine göre yorumlanır. | | `lead` | `lead` veya `patient`. Kişi kaydı olmayan sohbetleri eler. | | `has_open_task` | `true`: kişinin veya lead'inin açık görevi olanlar. `false`, kişi kaydı olmayan sohbetleri de getirir. | | `lead_reference_source_ids[]` | Lead kaynağına göre. | | `assigned_user_ids[]` | Lead'in atandığı kullanıcıya göre. Lead'i silinmiş veya hiç olmayan sohbetler eşleşmez. | | `tags[]` | Verilen etiketlerden herhangi birine sahip sohbetler. | | `group_lines` | `true`: birden çok WhatsApp hattından ulaşılan kişiyi tek sohbet olarak gösterir (en son etkin hat). `channel_ids[]` ile birlikte yok sayılır. WhatsApp dışı sohbetler birleştirilmez. | Filtreler birlikte uygulanır (VE). Hiçbir filtre görünürlük kapsamını genişletmez. Mantıksal parametreler `true`, `false`, `1` ve `0` kabul eder; geçersiz değer `422` döndürür. ```bash curl theme={null} curl -G "https://app.flextell.ai/api/v1/conversations" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ --data-urlencode "channel_type=whatsapp" \ --data-urlencode "archived=false" \ --data-urlencode "scope=assigned" \ --data-urlencode "per_page=20" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ channel_type: "whatsapp", archived: "false", scope: "assigned", per_page: "20", }); const res = await fetch(`https://app.flextell.ai/api/v1/conversations?${params}`, { headers: { Authorization: "Bearer ", "X-Tenant": "", }, }); const { data, meta } = await res.json(); ``` ## Sohbet oluşturma `POST /conversations` için `Create:Conversation` izni gerekir. Kişiyi üç yoldan biriyle belirtin: * `customer_id`: var olan bir hasta. * `lead_id`: var olan bir lead. * `channel_id` ve `address`: kanal ve adres. Kişi henüz yoksa oluşturulur. `customer_id` ve `lead_id` birlikte gönderilemez. `customer_id` ve `lead_id` yoksa `channel_id` ile `address` zorunludur. | Alan | Zorunlu | Açıklama | | - | - | - | | `customer_id` | Koşullu | Hasta kimliği. `lead_id` ile birlikte kullanılamaz. | | `lead_id` | Koşullu | Lead kimliği. Lead'i görebiliyor olmanız gerekir. | | `channel_id` | Koşullu | Klinik kanalı. Adres ile birlikte zorunludur. | | `address` | Koşullu | Kanaldaki adres. Telefon kanallarında numara normalize edilir. | | `contact_type` | Hayır | `customer` (varsayılan) veya `lead`. `customer_id` ya da `lead_id` ile birlikte gönderilemez. Yalnızca henüz kimseye ait olmayan bir adres için etkilidir. | | `first_name`, `last_name` | Hayır | En fazla 255 karakter. Verirseniz kişinin mevcut adını ve soyadını değiştirir. | Yanıt her zaman `201` döner, var olan bir sohbet dönse de. * **Kanal seçimi.** `customer_id` veya `lead_id` ile `channel_id` vermezseniz sunucu kanalı sırayla bulur: hastanın son gelen mesajının kanalı, hastanın varsayılan kanalı, kliniğin varsayılan bildirim kanalı, hastaya ulaşılabilen ilk etkin ve bağlı kanal. WhatsApp gibi telefon kanallarında telefon numarası yeterlidir. Telegram, Instagram ve web sitesinde kişinin bir kimliği ya da o kanalda bir sohbeti olmalıdır. * **Tekrar çağrı.** Aynı kanal ve normalize edilmiş adres için tekrar çağrı aynı sohbeti ve aynı kişiyi döndürür. Silinmiş sohbet geçmişiyle geri gelir. * **Lead oluşturma.** `contact_type=lead` ile yeni bir adres, etkin pipeline'ın ilk aşamasında yeni bir lead olur. Etkin pipeline yoksa hiçbir şey oluşmaz ve `422 LEAD_NO_ACTIVE_PIPELINE` döner. `contact_type` vermezseniz yeni kişi lead'siz bir hasta olur; API hiçbir zaman örtük lead oluşturmaz. * **Kısıt.** Çözülen adres başka bir hastanın sohbetine aitse (silinmiş olsa bile) `409 CONVERSATION_ADDRESS_TAKEN` döner. Lead'i size atanmamış bir kişiyle veya size görünmeyen mevcut bir sohbetle sohbet başlatırsanız istek hiçbir şey yazılmadan `403 CONVERSATION_NOT_ASSIGNED` ile reddedilir. Yanıttaki `data.assigned_user`, lead'in sahibini (`id` ve `name`) ya da `null` verir. Mesaj: `Bu kişinin sohbeti size atanmamış. Görüntülemek için yöneticinizden atama ya da yetki isteyin.` ```bash curl theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "channel_id": 123, "address": "+90 5xx xxx xx xx", "contact_type": "lead", "first_name": "Ayşe", "last_name": "Yılmaz" }' ``` ```javascript JavaScript theme={null} const res = await fetch("https://app.flextell.ai/api/v1/conversations", { method: "POST", headers: { Authorization: "Bearer ", "X-Tenant": "", "Content-Type": "application/json", }, body: JSON.stringify({ channel_id: 123, address: "+90 5xx xxx xx xx", contact_type: "lead", first_name: "Ayşe", last_name: "Yılmaz", }), }); const { data: conversation } = await res.json(); ``` ## Okundu ve okunmamış Okunmamış sayısı (`unread_count`) hastadan gelen ve `read_at` değeri boş olan mesajları sayar. Bu sayı ekibin tamamı için ortaktır: biriniz sohbeti okundu yaptığında herkes için okunmuş olur. | Endpoint | Ne yapar | Yanıt | | - | - | - | | `POST /conversations/{id}/read` | Sohbetteki hasta mesajlarını okundu yapar. | `{message: "Konuşma okundu olarak işaretlendi"}` | | `POST /conversations/read-all` | Görebildiğiniz tüm sohbetleri (arşivdekiler dahil) okundu yapar. Gövde göndermezsiniz. | `{message, marked_count}`. `marked_count` sohbet sayısıdır. Okunmamış sohbet yoksa `Okunmamış konuşma yok` ve `0`. | | `POST /conversations/{id}/open` | Sohbetin ilk mesaj sayfasını, bekleyen AI önerisini ve asistan durumunu döndürür; hasta mesajlarını okundu yapar. | `messages`, `read.marked_count` (mesaj sayısı), `ai_suggestion`, `agent`. | `/open` isteği `per_page`, `page`, `search` ve `message_type[]` parametrelerini kabul eder; bunların ayrıntısı [Mesajlar](/api/kaynaklar/mesajlar) sayfasındadır. * Bu üç çağrı da müşteriye "görüldü" bilgisi (mavi tik) göndermez. * Giden mesajlar hiçbir zaman personel işlemiyle okundu olmaz. * Okundu yapılan her sohbet için bir `ConversationRead` olayı yayınlanır. Olaylar için [Kanallar ve olaylar](/api/gercek-zamanli/kanallar-ve-olaylar) sayfasına bakın. * `/open`, silinmiş (imha edilmiş) hastanın sohbetinde de çalışır. ## Arşiv, etiket ve dışa aktarma ### Arşiv `POST /conversations/{id}/archive` ve `POST /conversations/{id}/unarchive` için `Archive:Conversation` izni gerekir. Gövde yoktur; yanıt, kısa şekilli sohbet nesnesidir. * Arşiv durumu klinik genelindedir; kimin arşivlediği `archived_by_user_name` alanında görünür. * Hasta yeniden yazarsa sohbet kendiliğinden arşivden çıkar. Kliniğin gönderdiği mesajlar sohbeti arşivde bırakır. * Zaten arşivdeki sohbeti arşivlemek `422 CONVERSATION_ALREADY_ARCHIVED`, arşivde olmayanı çıkarmak `422 CONVERSATION_NOT_ARCHIVED` döndürür. ### Etiket `PUT /conversations/{id}/tags` sohbetin etiket kümesini **tümüyle değiştirir**. `tags` alanı zorunludur ve klinik etiketlerinin kimliklerinden oluşan bir dizidir. Boş dizi (`[]`) tüm etiketleri kaldırır. `ManageTags:Conversation` izni, etiket tanımlarını düzenleme yetkisi olmadan ortak etiketleri sohbete atamanızı sağlar. ```bash curl theme={null} curl -X PUT "https://app.flextell.ai/api/v1/conversations/123/tags" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{"tags": [4, 9]}' ``` ### Dışa aktarma `POST /conversations/{id}/export` sohbeti indirilebilir dosya olarak akıtır. Yalnızca o sohbetin mesajları, klinik saat diliminde ve eskiden yeniye sıralı gelir. Dosya adı `conversation_{id}_{Ymd_His}.{uzantı}` biçimindedir. | Alan | Zorunlu | Açıklama | | - | - | - | | `format` | Evet | `json`, `csv`, `txt` veya `html`. | | `export_all` | Hayır | Varsayılan `true`: tüm mesajlar. | | `message_count` | Hayır | 1 ile 10000 arası, varsayılan 100. Yalnızca `export_all=false` iken geçerlidir ve en yeni N mesajı alır. | | `include_context` | Hayır | Varsayılan `false`. `true` ise JSON ve CSV'ye `is_processed`, `transcript` ve `metadata` alanları eklenir. | JSON çıktısında `conversation`, `timezone`, `exported_at`, `message_count` ve `messages[]` bulunur. Her mesajda `id`, `direction` (`incoming` veya `outgoing`), `sender`, `type`, `message` ve `timestamp` alanları vardır. CSV sütunları: `id`, `direction`, `sender`, `type`, `message`, `timezone`, `timezone_offset`, `timestamp`. ```bash curl theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations/123/export" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{"format": "csv", "export_all": false, "message_count": 500}' \ -o sohbet-123.csv ``` ### Silme `DELETE /conversations/{id}` sohbeti siler (`Delete:Conversation`). Silinen sohbet kaydı geri dönüşebilir durumdadır: aynı kişi yeniden yazarsa ya da aynı kanal ve adres için sohbet yeniden oluşturulursa aynı kimlikle, geçmişiyle birlikte geri gelir. Silme yaşam döngüsünün genel kuralları için [Silme yaşam döngüsü](/api/istekler/silme-yasam-dongusu) sayfasına bakın. ## Görünürlük Hangi sohbetleri gördüğünüzü `ViewAllConversations:Conversation` izni belirler. | Kullanıcı | Gördüğü sohbetler | | - | - | | Platform yöneticisi veya `ViewAllConversations:Conversation` sahibi | Kliniğin tüm sohbetleri. | | Diğer herkes | Yalnızca kişinin lead'i size atanmış sohbetler. Kişi kaydı olmayan veya lead'i olmayan sohbetler görünmez. | Görmediğiniz bir sohbetin kimliğini kullanırsanız veya başka bir kliniğin kimliğini verirseniz `404 RESOURCE_NOT_FOUND` alırsınız. Bu kural liste, tek kayıt, tüm yazma işlemleri ve `read-all` için geçerlidir. `scope` parametresi ve diğer filtreler kapsamı daraltır, genişletmez. `ViewAllConversations:Conversation` iznine sahip olmayan kullanıcılar başkasına atanmış lead'lerin sohbetlerini ve ortak hasta sohbetlerini görmez; yalnızca kendilerine atanmış lead'lerin sohbetleri gelir. Entegrasyonunuz bu izne sahip olmayan bir kullanıcı adına çalışıyorsa listeler beklediğinizden kısa gelebilir. ### Başkasına atanmış lead'ler `ViewAllConversations:Conversation` izni olduğu halde tüm lead'leri görme izni (`ViewAllLeads:Lead`) olmayan bir Satış Temsilcisi, başka birine atanmış bir lead'in sohbetini görebilir ancak kayıt kısıtlıdır: * `customer.is_masked` değeri `true` olur. Ad ilk iki harfe (`Jo••`), telefon ve adres son iki hane dışında maskelenir. `avatar_url` boş gelir. * `record_state` değeri `{is_read_only: true, reason_code: "LEAD_NOT_ASSIGNED"}` olur. * Her yazma işlemi `403 LEAD_NOT_ASSIGNED` döndürür. `/messages`, `/open`, `/read`, `/export` gibi okuma uçları bu kilide takılmaz. Silinmiş (imha edilmiş) bir hastanın sohbetinde okuma çağrıları çalışır, her yazma `409 CUSTOMER_ERASED` döndürür. Sohbet görünürlüğü gerçek zamanlı kanalları da etkiler; ayrıntı için [Kanallar ve olaylar](/api/gercek-zamanli/kanallar-ve-olaylar) sayfasına bakın. ## Hata kodları Hata yanıtı biçimi ve genel kodlar için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın. Sohbet endpoint'lerine özgü olanlar: | Kod | HTTP | Ne zaman | | - | - | - | | `RESOURCE_NOT_FOUND` | 404 | Sohbet yok, size görünmüyor veya başka klinikte. Mesaj `Konuşma bulunamadı`. Oluşturmada kanal, hasta veya lead için `Kanal bulunamadı`, `Hasta bulunamadı`, `Potansiyel hasta bulunamadı`. `/open` için mesaj İngilizce `Conversation not found` olarak döner. | | `CONVERSATION_NOT_ASSIGNED` | 403 | Sohbet başlatmada kişi size atanmamış veya mevcut sohbet size görünmüyor. `data.assigned_user` sahibi gösterir. | | `LEAD_NOT_ASSIGNED` | 403 | Başkasına atanmış lead'in sohbetinde yazma işlemi. Mesaj: `Bu potansiyel hasta size atanmamış. Görüntülemek için yöneticinizden atama ya da yetki isteyin.` | | `FORBIDDEN` | 403 | Eksik izin veya scope. Mesaj: `Bu işlem için yetkiniz yok.` | | `CUSTOMER_ERASED` | 409 | İmha edilmiş hastanın sohbetinde yazma. Mesaj: `Bu hastanın verileri imha edildi; kayıt salt okunurdur.` | | `CONVERSATION_ADDRESS_TAKEN` | 409 | Adres başka bir hastanın sohbetine ait. | | `CONVERSATION_CUSTOMER_UNREACHABLE` | 422 | `customer_id` veya `lead_id` için ulaşılabilir kanal ya da adres bulunamadı. | | `LEAD_NO_ACTIVE_PIPELINE` | 422 | `contact_type=lead` iken etkin pipeline yok. | | `CONVERSATION_ALREADY_ARCHIVED` | 422 | Zaten arşivdeki sohbeti arşivleme. | | `CONVERSATION_NOT_ARCHIVED` | 422 | Arşivde olmayan sohbeti arşivden çıkarma. | | `VALIDATION_FAILED` | 422 | Geçersiz parametre, örneğin `archived=maybe`. Ayrıntı `errors` alanındadır. | `402 SUBSCRIPTION_REQUIRED` ve `402 ACCESS_RESTRICTED_BY_OVERDUE_PAYMENT` yanıtları her sohbet endpoint'i için, okumalar dahil geçerlidir. Bu kilitler [Erişim kilitleri](/api/istekler/erisim-kilitleri) sayfasında anlatılır. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.