Lewati ke konten utama

Client API dan Realtime SSE

Jalur integrasi untuk aplikasi sisi pengunjung/end-user (widget, portal, aplikasi kustom) yang memakai Client API, serta saluran realtime Server-Sent Events (SSE) untuk update percakapan. Alur kerja dan batasnya ada di bawah ini; skema endpoint ada di OpenAPI runtime, bukan di dokumen ini.

Tujuan​

Integrator memakai Client API dengan identitas terbatas yang benar, dan menerima event realtime lewat SSE dengan autentikasi ticket tanpa mengekspos JWT di URL.

Untuk siapa​

Developer/integrator yang membangun alur end-user: memulai percakapan, mengirim pesan, membaca riwayat, dan menampilkan update live.

Prasyarat​

  • Inbox tipe client/widget tersedia beserta public key yang sah.
  • Token sesi dibuat server-side dengan scope minimum; jangan menaruh secret di bundle publik.
  • Konsep tenant dan status fitur dipahami; lihat Glosarium.

Client API​

Client API berada di bawah /api/v1/client dan memakai autentikasi widget/visitor (bukan kredensial agent penuh). Alur utama:

  1. Dapatkan identitas visitor dari server aplikasi Anda; endpoint konfigurasi inbox tidak memerlukan autentikasi, tetapi data dan aksi tetap dibatasi tenant.
  2. Mulai percakapan untuk inbox yang sah.
  3. Kirim pesan dari visitor; verifikasi respons dan request ID.
  4. Baca riwayat percakapan bila diperlukan.
  5. Kirim indikator typing sebagai state ephemeral; penyebarannya ke agen lewat SSE.

Client API membawa konteks account dan inbox dari token, bukan dari parameter yang bisa dipalsukan. Jangan memakai kredensial tenant penuh di sisi end-user.

Realtime SSE​

Aliran event percakapan disalurkan lewat SSE pada /api/v1/events/stream. Karena EventSource browser tidak dapat mengirim header Authorization, stream memakai ticket sekali pakai:

  1. Minta ticket via POST /api/v1/sse-ticket menggunakan JWT biasa pada header Authorization.
  2. Gunakan ticket sebagai parameter kueri stream dalam jangka pendek (TTL bawaan 5 menit, single-use).
  3. Sambungkan ke stream; event dikirim per tenant dan dapat dibatasi ke recipient user.
  4. Pada pemutusan, auto-reconnect dengan backoff; error jaringan bukan berarti sesi kedaluwarsa — jangan mengarahkan pengguna ke login ulang hanya karena koneksi putus.

Event yang terpublikasi (misalnya pesan baru, update percakapan, penugasan, mention, health sesi) disimpan dan dapat diputar ulang berbasis cursor, sehingga client yang baru tersambung dapat mengejar ketertinggalan. Tipe event yang benar-benar diproses aplikasi client masih terbatas; periksa implementasi yang Anda integrasikan.

Kondisi hub​

Stream SSE hanya terdaftar pada deployment yang menyediakan SSE hub. Bila deployment tidak menyediakan hub (kondisi konfigurasi, bukan mode normal), jalur stream tidak tersedia dan tidak boleh dianggap aktif. Verifikasi keberadaan jalur pada deployment Anda sebelum membangun ketergantungan realtime; jangan menganggap polling tidak diperlukan hanya karena dokumen OpenAPI mencantumkan stream.

Tanda berhasil​

Percakapan dapat dimulai dan diisi pesan dari identitas visitor terbatas; event baru muncul live tanpa reload; reconnect terjadi tanpa kehilangan konteks dan tanpa bounce ke layar login palsu.

Jika terjadi masalah​

  • 401 token/ticket invalid atau kedaluwarsa: minta token baru dari server Anda; ticket baru untuk stream.
  • 403 scope/inbox ditolak: periksa public key, inbox, dan batas tenant.
  • 404 inbox/percakapan salah: periksa konfigurasi inbox.
  • 429: hormati Retry-After dan backoff.
  • Koneksi stream putus berulang: gunakan backoff dan replay cursor; jangan perlakukan error jaringan sebagai auth-expired.

Batasan​

Client API dan SSE masih limited: tidak semua tipe event diproses client, dan delivery realtime tidak menjamin urutan di luar jangkauan replay. Push notification native bukan pengganti SSE dan tetap terbatas sampai end-to-end terbukti. Jangan mengklaim semua update live tanpa verifikasi pada deployment Anda.

Tugas terkait​