Olaylar

Host sayfanız widget içindeki olaylara abone olabilir — örneğin gelen bir mesajda kendi bildiriminizi göstermek veya bir temsilci çevrimiçi olduğunda kendi arayüzünüzü güncellemek için.

Abone olma

İki yol var; ikisi de aynı olay veriyoluna bağlanır.

1. Kurulum nesnesinde (Yapılandırma):

initWebfon({
  providerId: 'PROVIDER_ID',
  onMessage: (m) => console.log('yeni mesaj', m),
  onAgentAvailable: (a) => console.log('temsilci çevrimiçi', a),
});

2. Çalışma zamanında onEvent ile — aboneliği kaldıran bir fonksiyon döner:

// CDN
const off = window.Webfon.onEvent('message', (m) => console.log('yeni mesaj', m));
off();   // aboneliği kaldır

// npm
import { onEvent, offEvent } from 'webfon-client';
const off = onEvent('agentAvailable', (a) => console.log(a));

Handler'ınız hata atarsa yakalanır — widget akışı ve diğer handler'lar etkilenmez. Tanımsız bir olay adı sessizce yok sayılır: onEvent no-op bir kaldırma fonksiyonu döndürür.

Olay listesi

Olay	Kurulum anahtarı	Yük	Ne zaman
message	onMessage	mesaj nesnesi (aşağıda)	Soketten gelen bir sohbet mesajı düştüğünde.
agentAvailable	onAgentAvailable	temsilci nesnesi	Bir temsilci uygun duruma (online/away) geçtiğinde.

message yükü

{
  id, content,              // uuid · metin ('' olabilir: yalnız ek içeren mesaj)
  from_me,                  // bool — bu olayda daima false (aşağı bkz.)
  send_at,                  // ISO tarih
  sender_type,              // 'agent' | 'system' | 'ai_agent'
  agent_id,                 // gönderen temsilci (atanan değil) — yoksa null
  file, file_type,          // bool · 'photo'|'video'|'audio'|'file'|null (ilk ek)
  url, file_name, file_size,// ilk ekin kısayolları — yoksa null
  media,                    // tüm ekler: [{id, url, mime, size, file_name}] (yoksa [])
  reply_to,                 // yanıtlanan mesajın id'si — yoksa null
  is_pinned,                // bool
  reactions,                // { "<uid>": [{type:'emoji', emoji}] } — yoksa null
}

Ek URL'leri geçicidir

url ve media[].url private depoda presigned adreslerdir ve ~1 saat geçerlidir. Kalıcı olarak saklamayın.

agentAvailable yükü

{ user_id, first_name, last_name, avatar, title, status }   // status: 'online' | 'away'

Yalnız geçişte tetiklenir — bağlanışta gelen temsilci listesinin tamamı için değil. Ayrıca temsilci listesinin yüklenmiş olmasını gerektirir (liste, sohbet/arama sayfası ilk açıldığında çekilir); liste gelmeden düşen durum değişimleri eşleşemez ve yayınlanmaz.

message neyi tetiklemez

• Kendi gönderdiğiniz mesajlar — sunucu göndericiye kendi mesajını echo'lamaz; ziyaretçinin kendi onayı ayrı bir çerçevedir ve olay yayınlamaz. Yani message her zaman karşı taraftan gelir.
• Geçmiş — sohbet açılışında/yeniden bağlanışta çekilen mesaj geçmişi olay yayınlamaz; yalnız canlı gelen mesajlar yayınlar. Aynı mesaj iki kez düşerse (yeniden bağlanma) id'den elenir, tek olay çıkar.
• Düzenleme / reaksiyon / sabitleme güncellemeleri.

Olaylar soket bağlıyken akar

Sunucu tarafı bildirim için uygun değildir

Widget soketi tembel açar — sayfa yüklenir yüklenmez değil. Bağlantı şu durumlarda kurulur:

• panel açıldığında,
• sohbet/arama sayfası ilk açıldığında,
• başka bir sekmede canlı bir konuşma varken (bu durumda widget kapalıyken de arka planda bağlanır, böylece mesaj ve bildirim akmaya devam eder).

Ziyaretçi widget'ı hiç açmadıysa ve açık konuşması yoksa soket yoktur → message hiç tetiklenmez. Her mesajı kaçırmadan yakalamanız gerekiyorsa sunucu tarafı bir entegrasyon kullanın.

Abonelik ömrü

Aboneler modül düzeyinde tutulur ve destroy() sonrasında kayıtlı kalır — widget yok edilip yeniden init edilirse eski handler'lar çalışmaya devam eder. Aynı fonksiyon referansı iki kez kaydedilmez, ama her init'te satır içi yeni bir fonksiyon verirseniz (onMessage: (m) => …) handler çoğalır.

Mount/unmount döngüsü olan uygulamalarda callback'i kurulum nesnesinde vermek yerine onEvent'in döndürdüğü kaldırma fonksiyonunu cleanup'ta çağırın:

useEffect(() => {
  const widget = initWebfon({ providerId: 'PROVIDER_ID' });
  const off = onEvent('message', (m) => console.log(m));
  return () => { off(); widget?.destroy(); };
}, []);