Hızlı yanıtlar

/v1/quick-replies kaynağı kliniğin Hızlı Yanıt kayıtlarını yönetir. Hızlı yanıt, sohbet ekranında / yazılınca listelenen hazır bir mesajdır. Kayıtlar kliniğe aittir ve tüm kullanıcılar tarafından paylaşılır; kullanıcıya özel hızlı yanıt yoktur. Bir hızlı yanıtın metni ve en çok 10 medya eki olur. Bu sayfa hızlı yanıtları oluşturma, güncelleme ve silmeyi, medya eklerini ve ek sırasını anlatır. Hızlı yanıtı bir sohbette göndermek Sohbetler kaynağının işidir. Panelde aynı işlemler için Hızlı yanıtlar sayfasına bakın.

Endpoint özeti

Tüm isteklerde Authorization: Bearer <access_token> ve X-Tenant: <tenant_id> başlıkları gerekir. Scope’ların anlamı için Scope’lar, izin ve görünürlük kuralları için İzinler ve görünürlük sayfasına bakın.

Metot	Endpoint	Açıklama	Scope	İzin
GET	`/v1/quick-replies`	Hızlı yanıtları listeler.	`quick_replies:read`	`View:QuickReply`
POST	`/v1/quick-replies`	Hızlı yanıt oluşturur.	`quick_replies:write`	`Create:QuickReply`
GET	`/v1/quick-replies/{id}`	Tek hızlı yanıtı getirir.	`quick_replies:read`	`View:QuickReply`
PUT	`/v1/quick-replies/{id}`	Metni, kısayolu, biçimi ve aktiflik durumunu günceller.	`quick_replies:write`	`Update:QuickReply`
DELETE	`/v1/quick-replies/{id}`	Hızlı yanıtı siler.	`quick_replies:write`	`Delete:QuickReply`
POST	`/v1/quick-replies/{id}/media`	Mevcut eklerin sonuna bir medya dosyası ekler.	`quick_replies:write`	`Update:QuickReply`
DELETE	`/v1/quick-replies/{id}/media`	Tüm medya eklerini kaldırır.	`quick_replies:write`	`Update:QuickReply`
DELETE	`/v1/quick-replies/{id}/media/{fileId}`	Tek bir medya ekini kaldırır.	`quick_replies:write`	`Update:QuickReply`
PUT	`/v1/quick-replies/{id}/media/order`	Medya eklerini yeniden sıralar.	`quick_replies:write`	`Update:QuickReply`

Rol editöründe bu izinler Hızlı Yanıtlar grubunda görünür.

Nesne modeli

Tüm uç noktalar aynı hızlı yanıt nesnesini döner.

Alan	Tür	Açıklama
`id`	sayı	Hızlı yanıt kimliği.
`shortcut`	metin	Sohbette `/` sonrası yazılan kısayol.
`message`	metin	Mesaj metni.
`message_format`	metin	`plain` veya `markdown`.
`is_active`	boolean	Pasif hızlı yanıt sohbette gönderilemez.
`usage_count`	sayı	Hızlı yanıtın kaç kez gönderildiği.
`last_used_at`	tarih veya `null`	Son gönderim zamanı.
`files`	dizi	Medya ekleri, `sort_order` sırasıyla. Her öğe bir dosya nesnesidir.
`file`	nesne veya `null`	Kullanımdan kalkmıştır: `files` içindeki ilk ek. Eski mobil sürümler için korunur.
`created_at`, `updated_at`, `deleted_at`	tarih	Zaman damgaları.

file alanını yeni entegrasyonlarda kullanmayın. Ekleri her zaman files dizisinden okuyun.

Oluşturma

POST /v1/quick-replies isteği shortcut ve message alanlarını zorunlu tutar. Dosya göndermeyecekseniz application/json, dosya da göndereceksiniz multipart/form-data kullanın.

string

gerekli

En çok 50 karakter. Harf (Türkçe harfler dahil), rakam, _ ve - kabul edilir; boşluk kabul edilmez. Sunucu kısayolu kırpar, baştaki / işaretini atar ve küçük harfe çevirir. Kısayol, silinmemiş kayıtlar arasında klinik içinde benzersiz olmalıdır. Başka bir klinik aynı kısayolu kullanabilir.

string

gerekli

Mesaj metni. En çok 5000 karakter.

string

varsayılan:"plain"

plain veya markdown.

boolean

varsayılan:"true"

Hızlı yanıtın kullanılabilir olup olmadığı.

file

İsteğe bağlı medya dosyası, en çok 50 MB. İlk ek olur.

curl -X POST "https://app.flextell.ai/api/v1/quick-replies" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcut": "adres",
    "message": "Kliniğimiz Örnek Mah. Örnek Cad. No:1 adresindedir.",
    "message_format": "plain",
    "is_active": true
  }'

curl -X POST "https://app.flextell.ai/api/v1/quick-replies" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -F "shortcut=fiyat-listesi" \
  -F "message=Güncel fiyat listemiz ektedir." \
  -F "file=@fiyat-listesi.pdf"

Başarılı istek 201 ve hızlı yanıt nesnesini döner. PUT /v1/quick-replies/{id} isteğinde shortcut, message, message_format ve is_active alanlarının hepsi isteğe bağlıdır. Medya ekleri bu uç noktayla değişmez; aşağıdaki medya uç noktalarını kullanın. DELETE /v1/quick-replies/{id} kaydı siler ve {"message": "Hızlı yanıt silindi"} döner. Silinen bir kısayol yeniden kullanıma açılır: aynı kısayolla yeni bir hızlı yanıt oluşturabilirsiniz.

Medya

Bir hızlı yanıtta en çok 10 medya eki olabilir ve her dosya en çok 50 MB’tır. Genel dosya yükleme kuralları için Dosya yükleme sayfasına bakın. POST /v1/quick-replies/{id}/media dosyayı mevcut eklerin sonuna ekler; var olan ekleri değiştirmez. İstek multipart/form-data olmalıdır.

Alan	Zorunlu	Açıklama
`file`	Evet	Eklenecek dosya, en çok 50 MB.
`client_upload_id`	Hayır	İstemcinin ürettiği UUID.

Ağ hatasında isteği yeniden denemek güvenlidir: aynı hızlı yanıt için aynı client_upload_id ile gelen istek, dosyanın ikinci bir kopyasını eklemez; ilk seferde saklanan dosyayı döner. client_upload_id tek bir hızlı yanıt için geçerlidir.

curl -X POST "https://app.flextell.ai/api/v1/quick-replies/123/media" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -F "file=@tanitim.jpg" \
  -F "client_upload_id=3f6c1d9e-5a7b-4c2e-9d10-8b4a2e6f7c11"

curl -X DELETE "https://app.flextell.ai/api/v1/quick-replies/123/media/456" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Kaldırma uç noktaları güncel hızlı yanıt nesnesini döner:

DELETE /v1/quick-replies/{id}/media/{fileId} tek eki kaldırır. Dosya zaten kaldırılmışsa istek yine başarılı olur. Dosya bu hızlı yanıta hiç ait olmadıysa 404 alırsınız (Dosya bulunamadı).
DELETE /v1/quick-replies/{id}/media tüm ekleri kaldırır. Hiç ek yoksa 422 QUICK_REPLY_MEDIA_MISSING döner.

Sıralama

Listeyi sıralama

GET /v1/quick-replies listesi şu parametreleri kabul eder. Sayfalama için Sayfalama, genel sıralama kuralları için Filtreleme ve sıralama sayfasına bakın.

Parametre	Açıklama
`search`	En çok 255 karakter. Kısayolda veya mesajda büyük/küçük harf ayırmadan arar.
`is_active`	Aktiflik durumuna göre süzer.
`created_at_from`, `created_at_to`	Oluşturulma tarihi aralığı. `created_at_to`, `created_at_from` değerinden önce olamaz.
`sort_by`	`shortcut`, `usage_count`, `last_used_at`, `created_at`, `updated_at`. Varsayılan `usage_count`.
`sort_order`	`asc` veya `desc`, küçük harfle.
`per_page`, `page`	Sayfa boyutu 1–100, varsayılan 15.

Varsayılan sıralama usage_count azalan olduğundan en çok kullanılan hızlı yanıtlar listenin başında gelir. sort_by verip sort_order vermezseniz shortcut A’dan Z’ye (Türkçe alfabe sırasıyla), diğer alanlar büyükten küçüğe sıralanır. Açık bir sort_by, arama alaka sırasının yerini alır. Listede olmayan bir sort_by değeri 422 döner.

Kısayola göre sıralama

curl "https://app.flextell.ai/api/v1/quick-replies?is_active=true&sort_by=shortcut&sort_order=asc&per_page=50" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>"

Medya sırasını değiştirme

Ekler files dizisinde kayıtlı sırayla gelir. Sırayı değiştirmek için PUT /v1/quick-replies/{id}/media/order isteği gönderin.

integer[]

gerekli

Hızlı yanıtın mevcut eklerinin kimlikleri, istediğiniz sırayla. Her mevcut ek dizide tam olarak bir kez bulunmalıdır; en çok 10 öğe kabul edilir ve kimlikler birbirinden farklı olmalıdır. Boş dizi [] yalnızca hiç eki olmayan bir hızlı yanıt için geçerlidir.

Sırayı değiştirme

curl -X PUT "https://app.flextell.ai/api/v1/quick-replies/123/media/order" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{"file_ids": [457, 456, 458]}'

Yanıt, yeni sıradaki güncel hızlı yanıt nesnesidir.

Hatalar

Hata yanıtının yapısı için Yanıt yapısı, tüm kodlar için Hata kodları sayfasına bakın.

Kod	HTTP	Ne zaman
`VALIDATION_FAILED`	422	Alan doğrulaması başarısız: kısayol boşluk içeriyor, 50 karakteri aşıyor veya klinikte zaten var; `message` 5000 karakteri aşıyor; dosya 50 MB’ı aşıyor; `sort_by` listede yok.
`QUICK_REPLY_MEDIA_LIMIT_REACHED`	422	Hızlı yanıtta zaten 10 ek varken 11. dosya eklenmek istendi. Mesaj: `Bu hızlı yanıt izin verilen en fazla eke zaten sahip.`
`QUICK_REPLY_MEDIA_MISSING`	422	Hiç eki olmayan hızlı yanıtta `DELETE .../media` çağrıldı. Mesaj: `Bu hızlı yanıta eklenmiş medya yok.`
`QUICK_REPLY_MEDIA_ORDER_MISMATCH`	422	`file_ids`, mevcut eklerin her birini tam olarak bir kez içermiyor. Mesaj: `Yeni sıralama, bu hızlı yanıtın tüm eklerini birer kez içermelidir.`
(kodsuz)	404	Hızlı yanıt bulunamadı (`Hızlı yanıt bulunamadı`) ya da `fileId` bu hızlı yanıta ait değil (`Dosya bulunamadı`).
(kodsuz)	403	Token’da gerekli scope veya kullanıcıda gerekli izin yok.

Bir hızlı yanıtı sohbette gönderirken şu hatalarla da karşılaşabilirsiniz. Bunlar POST /v1/conversations/{id}/messages/quick-reply uç noktasına aittir; bu uç nokta Send:Message izni ister.

Kod	HTTP	Ne zaman
`QUICK_REPLY_INACTIVE`	422	Pasif bir hızlı yanıt gönderilmek istendi.
`QUICK_REPLY_EMPTY_MESSAGE`	422	Mesaj boş ve dosya seçilmedi.
`MESSAGE_TOO_LONG`	422	Mesaj kanalın karakter sınırını aşıyor.
`UNSUPPORTED_FILE_TYPE`	422	Ek, kanalın desteklemediği bir dosya türünde.

Birden fazla dosya eklemek için hızlı yanıtı önce dosyasız oluşturun, ardından her dosyayı client_upload_id ile /media uç noktasına gönderin. Yeniden denemeler kopya oluşturmaz.

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

Hızlı yanıtlar

Endpoint özeti

Nesne modeli

Oluşturma

Medya

Sıralama

Listeyi sıralama

Medya sırasını değiştirme

Hatalar

​Endpoint özeti

​Nesne modeli

​Oluşturma

​Medya

​Sıralama

​Listeyi sıralama

​Medya sırasını değiştirme

​Hatalar

Endpoint özeti

Nesne modeli

Oluşturma

Medya

Sıralama

Listeyi sıralama

Medya sırasını değiştirme

Hatalar