Gerçek zamanlı olaylar ve yetkilendirme

Flextell, sohbet ve bildirim gibi değişiklikleri Pusher Channels protokolüyle anlık olarak istemcilere iletir. Entegrasyonunuz bu olayları dinleyerek ekranını yenilemeden güncel kalabilir. Bu sayfa bağlantı kurmayı ve kanal aboneliğini yetkilendirmeyi anlatır. Kanal ve olay ayrıntıları için Kanallar ve olaylar, çalışan bir istemci için Örnek istemci sayfasına bakın.

Nasıl çalışır

Flextell olayları yayınlar, siz Pusher üzerinden abone olursunuz. Abonelik yönü tek taraflıdır: gerçek zamanlı bağlantı yalnızca bildirim taşır, işlem yapmak için REST API’yi kullanırsınız. Flextell yalnızca özel (private-) kanalları ve bir adet presence- kanalını kullanır. Herkese açık kanal yoktur. Her aboneliği Flextell sunucusu imzalar. İmzayı almak için kendi access token’ınızla /api/broadcasting/auth endpoint’ini çağırırsınız.

Gerçek zamanlı olaylar yalnızca “bir şey değişti” bilgisini verir. REST API gerçeğin kaynağı olarak kalır. Bağlantı kopup yeniden kurulduğunda kaçan olaylar tekrar gönderilmez, bu yüzden aboneliğin kurulduğu anda REST’ten güncel durumu yeniden okuyun. Ayrıntı için Teslim garantileri bölümüne bakın.

Bağlantı bilgileri

Pusher istemcisini yapılandırmak için şu bilgilere ihtiyacınız var.

Bilgi	Değer
Pusher uygulama anahtarı (`key`)	Flextell destek ekibinden alırsınız. Anahtar herkese açık bir değerdir, gizli tutulması gerekmez.
`cluster`	`eu`
`forceTLS`	`true`
Yetkilendirme endpoint’i	`POST https://app.flextell.ai/api/broadcasting/auth`
Access token	`Authorization: Bearer <access_token>` (Token’lar)

Yetkilendirme endpoint’i /api/v1 altında değil, /api altındadır: https://app.flextell.ai/api/broadcasting/auth.

Anahtarı almak için Destek sayfasındaki yolları kullanın.

Kanal yetkilendirmesi

Özel veya presence- bir kanala abone olurken Pusher istemciniz socket_id ve channel_name ile Flextell’e yetkilendirme isteği gönderir. Flextell isteği doğrularsa imza döner, istemciniz bu imzayla aboneliği tamamlar.

İstek

Alan	Zorunlu	Açıklama
`socket_id`	Evet	Pusher bağlantısının verdiği kimlik.
`channel_name`	Evet	`private-` veya `presence-` önekiyle tam kanal adı. Örneğin `private-chat-log.123`.

İstek gövdesini form (application/x-www-form-urlencoded) veya JSON olarak gönderebilirsiniz. JSON gövdesi bozuksa 400 ve MALFORMED_JSON hata kodu döner. Gerekenler:

Authorization: Bearer <access_token> başlığı.
Herhangi bir scope gerekmez.
X-Tenant başlığı gerekmez. Gönderseniz de Flextell yok sayar, çünkü klinik bilgisi kanal adından alınır.

curl -X POST https://app.flextell.ai/api/broadcasting/auth \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json" \
  -d "socket_id=1234.5678" \
  -d "channel_name=private-chat-log.123"

Yanıtlar

HTTP	Gövde	Ne zaman
`200`	`{"auth":"<key>:<imza>"}`	Özel kanalda yetki var.
`200`	`{"auth":"...","channel_data":"..."}`	`presence-` kanalında yetki var. `channel_data` üye bilgisini içerir.
`401`	`error_code`: `UNAUTHENTICATED`	Token eksik veya geçersiz.
`403`	`error_code`: `FORBIDDEN`	Token geçerli ama kanal kuralı sizi reddetti.

Hata yanıtı standart zarfı kullanır:

{
  "success": false,
  "error_code": "FORBIDDEN",
  "message": "Bu işlem için yetkiniz yok."
}

Hata yapısının tamamı için Hata kodları sayfasına bakın. 403 aldığınızda Pusher istemciniz kanalda pusher:subscription_error olayını üretir.

Access token kısa ömürlüdür. Yetkilendirme isteğini her gönderdiğinizde güncel token’ı kullanın ve süresi dolmuşsa önce yenileyin. Ayrıntılar için Token’lar sayfasına bakın.

Klinik ve izin kontrolleri

Yetkilendirme isteği klinik bağlamı taşımaz. Kontrol, kanal adındaki kimliğe göre ve token’ın ait olduğu kullanıcı için yapılır. Önce kullanıcının o klinikte üye olup olmadığına bakılır. Üye değilse ya da klinik yoksa abonelik reddedilir. Üyelik varsa kanala özgü izin kuralı uygulanır.

Kanal	Kim abone olabilir
`private-chat-log.{tenantId}`	Klinikte `View:Conversation` iznine sahip ve tüm sohbetleri görebilen kullanıcı (`ViewAllConversations:Conversation` iznine sahip olanlar veya platform yöneticisi). Mesaj içeriklerini taşır.
`private-chat-log-activity.{tenantId}`	Klinikte `View:Conversation` iznine sahip her kullanıcı. Yalnızca kimlik bilgisi taşır; değişikliği görünce REST’ten yeniden okursunuz.
`private-ai-suggestion.{conversationId}`	Sohbetin kliniğinde `View:Conversation` iznine sahip ve o sohbeti görebilen kullanıcı.
`private-App.Models.User.{userId}`	Yalnızca kimliği `userId` olan kullanıcının kendisi.
`presence-conversation.{conversationId}`	Web sitesi widget’ının ziyaretçisi veya `View:Conversation` iznine sahip, o sohbeti görebilen personel.

Bir kullanıcının sohbeti görebilmesi için ya tüm sohbetleri görme iznine sahip olması ya da sohbetteki kişinin Lead’inin kendisine atanmış olması gerekir. Kişisi veya Lead’i olmayan sohbetleri bu izne sahip olmayan kullanıcılar göremez. Görünürlük kuralları için İzinler ve görünürlük sayfasına bakın.

Bazı noktalara dikkat edin.

Tüm sohbetleri görme izni olmayan kullanıcı private-chat-log.{tenantId} kanalına abone olamaz ve 403 alır. Bu kullanıcılar için private-chat-log-activity.{tenantId} kanalını kullanın.
private-App.Models.User.{userId} kanalı kliniğe bağlı değildir. Bir kullanıcı birden fazla kliniğe üye olabileceğinden bu kanaldaki olaylar tenant_id alanı taşır. Aktif kliniğinize ait olmayanları istemcinizde atın. userId, GET /api/v1/account yanıtındaki Flextell kullanıcı kimliğidir.
Kanal adındaki tenantId ve conversationId sayısal kimliklerdir. Klinik kimliği için Klinikler ve X-Tenant sayfasına bakın.
presence-conversation.{conversationId} kanalını yalnızca web sitesi widget’ı kullanır. Ziyaretçi yetkilendirmesi ayrı bir endpoint üzerinden yapılır; bkz. Web sitesi widget’ı.

Teslim garantileri

Gerçek zamanlı kanalı güvenilir bir olay kuyruğu gibi kullanmayın. Aşağıdaki davranışları göz önünde bulundurun.

Konu	Ne olur
Kaçan olaylar	Teslim en fazla bir kez yapılır. Bağlantınız kopukken veya uygulamanız arka plandayken yayınlanan olaylar sonradan gönderilmez.
Sıra	Olay türleri arasında sıra garantisi yoktur. Bazı olaylar istek sırasında anında, bazıları arka planda gönderilir. Örneğin `ConversationRead` olayı, kendisinden sonra oluşan bir `ChatLogCreated` olayından sonra gelebilir.
Kendi değişiklikleriniz	Değişikliği siz yapsanız da olayı siz de alırsınız. Gönderen istemci hariç tutulmaz. Olayları kimliğe göre tekrarlardan arındırın.
Eksik yükler	Bazı olaylar yalnızca kimlik taşır (örneğin `ConversationCreated`, `ConversationDeleted`, `ConversationRead`, `CustomerUpdated`) veya etiket listesi gibi ayrıntıyı içermez (`ConversationTagsChanged`). Bunları “yeniden oku” sinyali sayın.
Boyut	Pusher olay verisi için 10 KB sınır uygular. AI öneri olaylarında yük 9000 bayt üstüne çıkarsa kısaltılmış gelir ve `requires_hydration` alanı `true` olur. Bu durumda öneriyi REST’ten okuyun.
Eski içerik	AI öneri yükleri olay üretildiği andaki görüntüdür. Güncel hâli için REST’e bakın.

Abone olun

Kanala abone olun ve pusher:subscription_succeeded olayını bekleyin.

Durumu yeniden okuyun

Bu olayda REST’ten güncel durumu çekin, örneğin sohbet listesini ve açık sohbetin mesajlarını. Olay, ilk abonelikte ve her yeniden bağlanmadan sonra gelir.

Olayları uygulayın

Bundan sonra gelen olayları ekrandaki duruma uygulayın. Eksik yükte REST’e dönün.

Flextell’in panel ve mobil uygulaması da aynı yöntemi kullanır: her abonelik kurulduğunda ve bağlantı yeniden kurulduğunda REST’ten yeniden okur.

İlgili sayfalar

Kanallar ve olaylar

Her kanalın olayları ve yük alanları.

Örnek istemci

Abonelik ve yeniden bağlanma için çalışan örnek.

Token'lar

Access token alma ve yenileme.

Bildirimler

Kişisel kanalda gelen bildirimlerin REST karşılığı.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri