AI asistan: agent'lar ve öneriler

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 ve Kanallar sayfalarına bakın. Panel tarafındaki ekranlar için Agent prompt’ları ve AI asistan sayfalarını açın.

Endpoint özeti

Tüm isteklerde Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> 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 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 ve Filtreleme ve sıralama 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.

curl -X POST "https://app.flextell.ai/api/v1/agent-prompts" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "info",
    "language": "tr",
    "is_active": true,
    "prompt": "Siz {{clinic_name}} kliniğinin bilgi asistanısınız. ..."
  }'

curl -X PUT "https://app.flextell.ai/api/v1/agent-prompts/123" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -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.

curl -X POST "https://app.flextell.ai/api/v1/conversations/123/agent/disable" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "duration_minutes": 60 }'

curl -X POST "https://app.flextell.ai/api/v1/conversations/123/agent/enable" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

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 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.

curl -X POST "https://app.flextell.ai/api/v1/conversations/123/ai-suggestion/send" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{ "send_source": "suggestion_as_is" }'

curl -X POST "https://app.flextell.ai/api/v1/conversations/123/ai-suggestion/send" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -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 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ı sayfasına bakın. Asistan kontrolünü adım adım anlatan bir akış için AI asistan kontrolü rehberine, sohbet kaynağının kendisi için Sohbetler sayfasına geçin.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

AI asistan: agent'lar ve öneriler

Endpoint özeti

Agent prompt’ları

Nesne alanları

Agent tipleri

Listeleme

Oluşturma ve güncelleme

Mod kısıtı

Silme

Revizyonlar

Sohbette asistan kontrolü

AI önerileri

Öneri nesnesi

Bekleyen randevuyu düzenleme

Yeniden oluşturma

Önerileri onaylama ve reddetme

Gönderme

Reddetme

Puanlama

Hata kodları

​Endpoint özeti

​Agent prompt’ları

​Nesne alanları

​Agent tipleri

​Listeleme

​Oluşturma ve güncelleme

​Mod kısıtı

​Silme

​Revizyonlar

​Sohbette asistan kontrolü

​AI önerileri

​Öneri nesnesi

​Bekleyen randevuyu düzenleme

​Yeniden oluşturma

​Önerileri onaylama ve reddetme

​Gönderme

​Reddetme

​Puanlama

​Hata kodları

Endpoint özeti

Agent prompt’ları

Nesne alanları

Agent tipleri

Listeleme

Oluşturma ve güncelleme

Mod kısıtı

Silme

Revizyonlar

Sohbette asistan kontrolü

AI önerileri

Öneri nesnesi

Bekleyen randevuyu düzenleme

Yeniden oluşturma

Önerileri onaylama ve reddetme

Gönderme

Reddetme

Puanlama

Hata kodları