> ## 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. # AI asistan: agent'lar ve öneriler > Agent prompt'larını, revizyonları, sohbet bazında asistan kontrolünü ve AI önerilerini anlatır. AI asistan, hastalarla yazışan ve klinik adına yanıt üreten yapay zeka özelliğidir. Her adımı bir **agent** yürütür (karşılama, randevu, bilgi, destek gibi). Bu sayfa üç şeyi kapsar: agent'ların prompt metinlerini yönetmek, bir sohbette asistanı duraklatmak ve **Yarı-otomatik** modda üretilen **AI önerilerini** onaylamak ya da reddetmek. Yanıt modu (`auto`, `semi_auto`, `closed`) kliniğin sohbet ayarlarından ve kanalın `ai_reply_mode` alanından gelir. Bu alanlar için [Ayarlar](/api/kaynaklar/ayarlar) ve [Kanallar](/api/kaynaklar/kanallar) sayfalarına bakın. Panel tarafındaki ekranlar için [Agent prompt'ları](/panel/sistem/agent-promptlari) ve [AI asistan](/panel/sohbetler/ai-asistan) sayfalarını açın. ## Endpoint özeti Tüm isteklerde `Authorization: Bearer ` ve `X-Tenant: ` başlıkları zorunludur. | Metot | Endpoint | Açıklama | Scope | İzin | | - | - | - | - | - | | GET | `/agent-prompts` | Prompt'ları listeler | `agent-prompts:read` | `View:AgentPrompt` | | GET | `/agent-prompts/flow` | Agent akış şemasını döner | `agent-prompts:read` | `View:AgentPrompt` | | GET | `/agent-prompts/types` | Seçilebilir agent tipleri | `agent-prompts:read` | `View:AgentPrompt` | | GET | `/agent-prompts/models` | Seçilebilir modeller | `agent-prompts:read` | `View:AgentPrompt` | | GET | `/agent-prompts/tools` | Asistanın araç kataloğu | `agent-prompts:read` | `View:AgentPrompt` | | POST | `/agent-prompts` | Prompt oluşturur | `agent-prompts:write` | `Create:AgentPrompt` | | GET | `/agent-prompts/{id}` | Prompt detayı | `agent-prompts:read` | `View:AgentPrompt` | | PUT | `/agent-prompts/{id}` | Prompt günceller (kısmi) | `agent-prompts:write` | `Update:AgentPrompt` | | DELETE | `/agent-prompts/{id}` | Prompt siler | `agent-prompts:write` | `Delete:AgentPrompt` | | GET | `/agent-prompts/{id}/revisions` | Revizyon listesi | `agent-prompts:read` | `View:AgentPrompt` | | GET | `/agent-prompts/{id}/revisions/{revisionId}` | Revizyon ve fark (diff) | `agent-prompts:read` | `View:AgentPrompt` | | POST | `/agent-prompts/{id}/revisions/{revisionId}/restore` | Revizyonu geri yükler | `agent-prompts:write` | `Update:AgentPrompt` | | PUT, DELETE | `/agent-prompts/{id}/stable-version` | Stabil işareti koyar, kaldırır | `agent-prompts:write` | `PublishRevision:AgentPrompt` | | GET | `/conversations/{id}/agent` | Asistanın sohbetteki durumu | `conversations:read` | `View:Conversation` | | POST | `/conversations/{id}/agent/disable` | Asistanı duraklatır | `conversations:write` | `ToggleAgent:Conversation` | | POST | `/conversations/{id}/agent/enable` | Asistanı yeniden açar | `conversations:write` | `ToggleAgent:Conversation` | | GET | `/conversations/{id}/ai-suggestion` | Bekleyen öneriyi döner | `conversations:read` | `View:Conversation` | | POST | `/conversations/{id}/ai-suggestion/send` | Öneriyi gönderir | `conversations:write` | `ManageAiSuggestions:Conversation` ve `Send:Message` | | POST | `/conversations/{id}/ai-suggestion/dismiss` | Öneriyi reddeder | `conversations:write` | `ManageAiSuggestions:Conversation` | | PUT | `/conversations/{id}/ai-suggestion/rating` | Öneriyi puanlar | `conversations:write` | `ManageAiSuggestions:Conversation` | | PUT | `/conversations/{id}/ai-suggestion/pending-appointment` | Önerilen randevuyu düzenler | `conversations:write` | `ManageAiSuggestions:Conversation` | | POST | `/conversations/{id}/ai-suggestion/regenerate` | Yeni öneri ürettirir | `conversations:write` | `ManageAiSuggestions:Conversation` | Sohbet endpoint'leri için görünürlük kuralı geçerlidir: `ViewAllConversations:Conversation` iznine sahip değilseniz yalnızca lead'i size atanmış kişilerin sohbetlerini görürsünüz. Genel kurallar için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın. ## Agent prompt'ları Prompt, bir agent'ın davranışını belirleyen sistem metnidir. Klinik başına, her **tip** ve **dil** için aynı anda yalnızca bir prompt aktif olabilir. ### Nesne alanları | Alan | Tür | Açıklama | | - | - | - | | `id` | integer | Prompt kimliği. | | `type` | string | Agent tipi (aşağıdaki tablo). | | `type_label` | string | Tipin Türkçe etiketi (`Accept-Language`'e göre). | | `language` | string | `tr` veya `en`. Varsayılan `tr`. | | `llm_model` | string, null | Model kimliği. `null` ise platform varsayılanı kullanılır. | | `prompt` | string | Prompt metni. | | `is_active` | boolean | Yalnızca aktif prompt'lar kullanılır. | | `can_activate` | boolean | Mevcut modda bu tipin aktifleştirilip aktifleştirilemeyeceği. | | `activation_restriction_reason` | string, null | Aktifleştirilemiyorsa nedeni. | | `stable_version_id` | integer, null | Stabil işaretli revizyon. | | `created_at`, `updated_at`, `deleted_at` | string | Zaman damgaları. | ### Agent tipleri `GET /agent-prompts/types` dokuz tip döner. | `type` | Etiket | | - | - | | `greeter` | Karşılama | | `booking` | Randevu | | `info` | Bilgi | | `support` | Destek | | `router` | Yönlendirici | | `spam` | Spam | | `ai_report` | AI Rapor | | `intake_router` | Yönlendirici (Ön Kayıt Modu) | | `intake` | Ön Kayıt | Sistem tarafından yönetilen tipler (Randevu Özeti, Tedavi Özeti, Ürün Özeti) API'de görünmez; bu tiplerin kayıtları `404` döner. ### Listeleme `GET /agent-prompts` aşağıdaki sorgu parametrelerini kabul eder. Genel kurallar için [Sayfalama](/api/istekler/sayfalama) ve [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama) sayfalarına bakın. | Parametre | Açıklama | | - | - | | `search` | Prompt metninde arar (en çok 255 karakter). | | `type` | Tenant tiplerinden biri. | | `language` | `tr` veya `en`. | | `is_active` | `true` / `false` (`1` / `0` da kabul edilir). | | `sort_by` | `type`, `is_active`, `created_at`, `updated_at`. Varsayılan `created_at`. | | `sort_order` | `asc` veya `desc`. Varsayılan `desc`. | | `per_page` | 1–100. Varsayılan 15. | ### Oluşturma ve güncelleme `POST /agent-prompts` gövdesinde `type`, `prompt` ve `is_active` zorunludur. `language` ve `llm_model` isteğe bağlıdır. `llm_model` değeri `GET /agent-prompts/models` listesinden gelmelidir. `PUT` kısmi güncellemedir; `llm_model` alanını `null` göndererek temizleyebilirsiniz. ```bash Oluşturma theme={null} curl -X POST "https://app.flextell.ai/api/v1/agent-prompts" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "type": "info", "language": "tr", "is_active": true, "prompt": "Siz {{clinic_name}} kliniğinin bilgi asistanısınız. ..." }' ``` ```bash Aktifliği kapatma theme={null} curl -X PUT "https://app.flextell.ai/api/v1/agent-prompts/123" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "is_active": false }' ``` Başarılı oluşturma `201` döner. Prompt metninde `{{clinic_name}}` yazarsanız asistan bunu klinik adıyla değiştirir; klinik adını metne elle yazmayın. Aynı tip ve dilde yeni bir prompt oluşturduğunuzda ya da mevcut birini aktifleştirdiğinizde, aynı tip ve dildeki diğer aktif prompt sessizce pasife alınır; hata dönmez. Aktif prompt'u olmayan bir agent yönlendirilemez: örneğin **Randevu** prompt'unu pasife almak, asistanın randevu almasını fiilen kapatır. ### Mod kısıtı Klinik **Standart** veya **Ön Kayıt Modu**'ndadır. Standart modda `intake` ve `intake_router` aktifleştirilemez; Ön Kayıt Modu'nda `booking` ve `router` aktifleştirilemez. İzin verilmeyen bir tipi `is_active: true` ile kaydederseniz (etkin bir prompt'u izin verilmeyen bir tipe taşımak da dahil) `422 AGENT_PROMPT_TYPE_DISABLED_IN_MODE` alırsınız; yanıtın `data.type` alanı tipi, `message` alanı nedeni verir. Pasif kayıt oluşturmak serbesttir. Akış şeması (`GET /agent-prompts/flow`) `active_mode` alanında `mod1` (Standart) ya da `mod2` (Ön Kayıt Modu) döner. ### Silme `DELETE` yumuşak silmedir ve `{"message": "Ajan istemi başarıyla silindi"}` döner. Silinen prompt için geri yükleme endpoint'i yoktur. ## Revizyonlar Prompt metnindeki her değişiklik bir revizyon oluşturur ve değişikliği yapan kullanıcıyı kaydeder. Tip, dil, model ya da `is_active` değişiklikleri revizyon oluşturmaz. * `GET /agent-prompts/{id}/revisions`, en yeni revizyon başa gelecek şekilde listeler. Her kayıtta `is_current`, `is_stable` ve `user` alanları bulunur. * `GET /agent-prompts/{id}/revisions/{revisionId}`, revizyonun `prompt`, `previous_prompt` ve birleşik biçimli `diff` alanlarını döner. İlk revizyonda `diff` `null`'dır. * `POST …/restore`, seçilen revizyonun metnini prompt'a yazar. Bu işlem yeni bir revizyon oluşturur; geçmiş silinmez. * `PUT …/stable-version` gövdesindeki `revision_id` ile bir revizyonu **stabil** olarak işaretler; `DELETE` işareti kaldırır. `revision_id` aynı prompt'a ait olmalıdır, değilse `404` alırsınız. Stabil işareti yalnızca bir geri dönüş noktasıdır. Asistan her zaman prompt'un güncel metnini kullanır. Platform güncellemeleri varsayılan prompt metinlerini yenileyebilir; önceki metin revizyon geçmişinde kalır. ## Sohbette asistan kontrolü Bir sohbette asistanı geçici olarak susturmak için duraklatın. Duraklatma yalnızca o sohbeti etkiler. `GET /conversations/{id}/agent` şu alanları döner: `agent_disabled`, `agent_expires_at`, `agent_disabled_by_user_name`, `remaining_minutes`. Süresi dolmuş duraklatma okuma sırasında temizlenir. `POST /conversations/{id}/open` yanıtı da aynı yapıyı `agent` alanında taşır. | İşlem | Gövde | Başarılı yanıt | | - | - | - | | `POST …/agent/disable` | `duration_minutes`: 1–525600 dakika. `null` veya boş ise süresiz. | `{"message": "Ajan başarıyla devre dışı bırakıldı"}` | | `POST …/agent/enable` | Yok | `{"message": "Ajan başarıyla etkinleştirildi"}` | Her iki işlem de sohbete bir sistem mesajı yazar. Hastası silinmiş (imha edilmiş) sohbette `409 CUSTOMER_ERASED`, size atanmamış lead'in sohbetinde `403 LEAD_NOT_ASSIGNED` alırsınız. ```bash Duraklatma theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations/123/agent/disable" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "duration_minutes": 60 }' ``` ```bash Yeniden açma theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations/123/agent/enable" \ -H "Authorization: Bearer " \ -H "X-Tenant: " ``` Asistan bazı durumlarda kendiliğinden duraklar: * Asistan açıkken personel panelden, mobilden veya API'den elle mesaj gönderirse sohbet 30 dakika duraklar. * Düzenlenmiş bir öneriyi `take_over_agent: true` ile gönderirseniz sohbet 30 dakika duraklar. * Öneriyi olduğu gibi göndermek asistanı duraklatmaz. Duraklatma sırasında kuyrukta bekleyen asistan yanıtı gönderilmez. Duraklatılmış sohbette yeni öneri üretmeye (`regenerate`) devam edebilirsiniz. ## AI önerileri **Yarı-otomatik** modda asistan yanıtı doğrudan göndermez; öneri olarak saklar. Bir sohbette en çok bir bekleyen öneri bulunur. Yeni bir öneri üretildiğinde eskisinin yerini alır ve bekleyen işlemlerini devralır. ### Öneri nesnesi `GET /conversations/{id}/ai-suggestion` bekleyen öneriyi döner. Bekleyen öneri yoksa `200` ile `data: null` gelir; `404` gelmez. | Alan | Tür | Açıklama | | - | - | - | | `id`, `conversation_id` | integer | Öneri ve sohbet kimliği. | | `original_text` | string | Asistanın ürettiği taslak. | | `final_text` | string, null | Gönderilen metin. | | `status` | string | Aşağıdaki tabloya bakın. | | `rating` | string, null | `up`, `down` veya `null`. | | `attachments`, `actions` | array | Onayla birlikte gidecek ekler ve yapılacak işler: `{type, icon, label}`. | | `block_reason` | object, null | Engelleme önerisiyse `{label, description, color, note, ttl_seconds}`. | | `editable_insert` | boolean | Öneri bir randevu oluşturacaksa `true`. | | `found_treatments` | array | Asistanın bulduğu tedaviler: `{id, name}`. | | `has_new_messages` | boolean | Öneriden sonra hastadan yeni mesaj geldiyse `true`. | | `generated_at` | string | Klinik saatiyle `HH:mm`. | | `sent_at`, `created_at`, `updated_at` | string | UTC ISO 8601 (`+00:00`). | `pending_actions` alanı ham iç veriyi (telefon numarası, UTC saat, dosya yolu gibi) içerir. Kullanıcıya göstermek için `actions`, `attachments` ve `block_reason` alanlarını kullanın. | `status` | Etiket | Anlamı | | - | - | - | | `pending` | Bekliyor | Operatörün kararını bekliyor. | | `sent_as_is` | Olduğu Gibi Gönderildi | Değiştirilmeden onaylandı. | | `sent_edited` | Düzenlenip Gönderildi | Düzenlenerek gönderildi. | | `dismissed` | Reddedildi | Reddedildi; bekleyen işlemler çalışmaz. | | `superseded` | Güncellendi | Yeni bir öneri tarafından değiştirildi. | Yeni hasta mesajı geldiğinde bekleyen öneri kendiliğinden yenilenmez; yalnızca `has_new_messages` `true` olur. Güncel bir yanıt için `regenerate` çağırın. ### Bekleyen randevuyu düzenleme Öneri bir randevu oluşturacaksa (`editable_insert: true`), göndermeden önce `PUT …/pending-appointment` ile düzeltebilirsiniz. Gövdede `scheduled_at` (klinik saat dilimi), `doctor_id`, `treatment_ids[]` (en az bir, seçilen doktorun sunduğu aktif tedaviler) ve `message` (en çok 4096 karakter; öneri metni olur) zorunludur. Çalışma saatleri, tatiller, slot aralığı ve en geç randevu tarihi kuralları geçerlidir; geçmiş tarih kabul edilir. Randevu yine yalnızca öneri gönderildiğinde oluşur. Öneride randevu işlemi yoksa `422 PENDING_APPOINTMENT_UPDATE_FAILED` döner. ### Yeniden oluşturma `POST …/regenerate` yeni bir öneri ürettirir ve `202 {"status": "queued", "conversation_id": 123}` döner. Yeni öneri eşzamansız gelir; birkaç saniye sonra `GET …/ai-suggestion` ile okuyun. İsteğe bağlı `treatment_ids[]` (aktif tedaviler) yanıtı yalnızca bu tedavilerle sınırlar. Şu koşullardan biri sağlanmazsa `422 SUGGESTION_SOURCE_MISSING` alırsınız: kanalın geçerli modu **Yarı-otomatik** olmalı, son giden mesajdan sonra yanıtsız ve metin içeren bir hasta mesajı bulunmalıdır. Yeniden oluşturma AI kredisi harcar; asistan duraklatılmış olsa da çalışır. Kredi için [Krediler](/api/kaynaklar/krediler) sayfasına bakın. ## Önerileri onaylama ve reddetme ### Gönderme `POST …/ai-suggestion/send` gövdesi: | Alan | Zorunlu | Açıklama | | - | - | - | | `send_source` | Evet | `suggestion_as_is` veya `suggestion_edited`. | | `message` | `suggestion_edited` ise | Gönderilecek metin, en çok 4096 karakter. `suggestion_as_is` ile gelen `message` yok sayılır. | | `take_over_agent` | Hayır | Yalnızca `suggestion_edited` ile etkilidir; sohbeti 30 dakika duraklatır. | Her gönderim için `ManageAiSuggestions:Conversation` ve `Send:Message` izinleri gerekir. `suggestion_edited` ile `take_over_agent: true` birlikte kullanılırsa ek olarak `ToggleAgent:Conversation` gerekir. ```bash Olduğu gibi gönderme theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations/123/ai-suggestion/send" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "send_source": "suggestion_as_is" }' ``` ```bash Düzenleyip gönderme theme={null} curl -X POST "https://app.flextell.ai/api/v1/conversations/123/ai-suggestion/send" \ -H "Authorization: Bearer " \ -H "X-Tenant: " \ -H "Content-Type: application/json" \ -d '{ "send_source": "suggestion_edited", "message": "Merhaba Ayşe Hanım, size uygun saatleri paylaşıyorum.", "take_over_agent": true }' ``` Başarılı yanıt `202` ve `{"status": "queued", "message_id": "semi_ai_…", "conversation_id": 123}` biçimindedir. Metin önce gönderilir. Sonra öneriye bağlı bekleyen işlemler (randevu oluşturma, taşıma, iptal; dosya, konum veya tedavi görseli gönderme; engelleme) aynı istekte çalışır. Öneri `sent_as_is` ya da `sent_edited` olur ve yanıtlanan hasta mesajları okundu olarak işaretlenir. Bekleyen işlemler çalıştırılmadan önce güncel verilere göre yeniden doğrulanır. Artık geçerli olmayan bir işlem (örneğin dolan saat) sessizce atlanır, API hata dönmez ve onaylanan mesaj hastaya yine gider. Randevunun gerçekten oluştuğunu doğrulamak için [Randevular](/api/kaynaklar/randevular) kaynağını okuyun. ### Reddetme `POST …/ai-suggestion/dismiss`, öneriyi `dismissed` yapar ve `{"message": "Öneri başarıyla reddedildi"}` döner. Öneriye bağlı bekleyen işlemler hiçbir zaman çalışmaz. ### Puanlama `PUT …/ai-suggestion/rating` gövdesinde `rating` anahtarı bulunmalıdır: `up`, `down` ya da puanı kaldırmak için `null`. Puan hastaya iletilmez ve kredi harcamaz. Yalnızca bekleyen öneri puanlanabilir. ### Hata kodları | Kod | HTTP | Ne zaman | | - | - | - | | `RESOURCE_NOT_FOUND` | 404 | Sohbet görünür değil ya da yok (`Konuşma bulunamadı`); bekleyen öneri yok (`Bekleyen öneri bulunamadı`); prompt veya revizyon yok (`Ajan istemi bulunamadı`, `Ajan istemi sürümü bulunamadı`). | | `AGENT_PROMPT_TYPE_DISABLED_IN_MODE` | 422 | Mevcut modda kullanılamayan prompt tipi aktifleştirilmek istendi. | | `SUGGESTION_SOURCE_MISSING` | 422 | `Yeniden oluşturulabilecek yanıtsız bir hasta mesajı yok.` | | `PENDING_APPOINTMENT_UPDATE_FAILED` | 422 | Düzenlenecek randevu işlemi yok ya da saat kuralları ihlal edildi (ör. `Seçilen saat çalışma saatleri dışında.`). | | `CONVERSATION_CHANNEL_MISSING` | 422 | `Konuşma kanalı bulunamadı.` | | `QUOTA_EXHAUSTED` | 422 | WhatsApp mesaj hakkı doldu; `data.billing_type` verilir. | | `SUBSCRIPTION_REQUIRED` | 402 | Abonelik süresi dolmuş ya da ücretli plan seçilmemiş. | | `CUSTOMER_ERASED` | 409 | Hastanın verileri imha edilmiş; kayıt salt okunur. | | `LEAD_NOT_ASSIGNED` | 403 | Lead'i size atanmamış bir sohbette işlem yapmaya çalıştınız. | | `VALIDATION_FAILED` | 422 | Geçersiz parametre (ör. `per_page=101`, `type=booking_summary`). | Genel hata biçimi için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın. Asistan kontrolünü adım adım anlatan bir akış için [AI asistan kontrolü](/api/rehberler/ai-asistan-kontrolu) rehberine, sohbet kaynağının kendisi için [Sohbetler](/api/kaynaklar/sohbetler) sayfasına geçin. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.