Realtime WebSocket Hub
1. Ikhtisar & Nilai Bisnis
Selain menawarkan Webhook tradisional, infrastruktur DagangBot memiliki subsistem Realtime WebSocket Hub. Alih-alih melakukan push data lintas-server (Server-to-Server), antarmuka WebSocket didesain secara spesifik agar antarmuka pengguna (Frontend), aplikasi klien, atau dasbor internal (CRM) dapat langsung mendengarkan perubahan seketika tanpa perantara tambahan.
Nilai Bisnis yang difasilitasi meliputi:
- Latensi Menuju Nol: Data mengalir melalui sambungan TCP persisten, memberikan status pesanan seketika dan kemampuan pengalaman pesan instan kepada agen Customer Service (CS).
- Pengurangan Beban Infrastruktur: Membebaskan server atau klien web dari keharusan mereload halaman atau membanjiri antarmuka REST API guna memeriksa status percakapan pelanggan atau status sinkronisasi.
- Isolasi Penyewa Bawaan: Anda tidak perlu memprogram logika saluran (Channel/Room) atau langganan (subscribe). Otorisasi tiket secara otomatis memastikan klien hanya menerima event yang menjadi hak penyewa (Tenant) dan cabang (Branch) Anda sendiri.
2. Alur Visual & Antarmuka
Fungsi seketika (realtime) ini menggerakkan antarmuka live-chat agen layanan pelanggan dan panel pemantauan pesanan yang senantiasa mutakhir:


3. Panduan Langkah-demi-Langkah
Integrasi aliran WebSocket memerlukan pola pertukaran tiket tunggal guna mencegah pengeksposan token JWT jangka panjang pada koneksi persisten websocket header.
Langkah 1: Mengambil Tiket Sekali-Pakai
Klien harus membuat permintaan HTTP POST menggunakan kredensial standar (Authorization Bearer). Sistem akan memberikan tiket sementara yang mengikat profil identitas Anda (merchant, cabang, otorisasi). Tiket ini didesain sebagai mekanisme pengamanan untuk tidak mengirimkan token JWT berumur panjang melalui koneksi terbuka WSS.
Belum ada endpoint terdaftar untuk tag Integrations.
# Mengambil WebSocket Ticket menggunakan cURL
curl -X POST https://dagangbot.web.id/api/v1/events/ticket \
-H "Authorization: Bearer <JWT_ACCESS_TOKEN>" \
-H "Content-Type: application/json"Respons yang diterima:
{
"ticket": "tkt_a1b2c3d4e5f6g7h8",
"expires_in": 60
}Langkah 2: Membuka Koneksi WebSocket dengan Reconnection
Gunakan tiket yang baru diperoleh pada parameter URI (Query parameter) saat melakukan negosiasi protokol dari HTTP ke WSS (WebSockets Secure). Anda memiliki waktu presisi kurang dari 60 detik sebelum tiket tersebut dihanguskan oleh memori Hub DagangBot.
Berikut adalah implementasi klien JavaScript dunia nyata (Vanilla JS) yang secara tangguh menangani pengambilan tiket, koneksi, serta logika Exponential Backoff saat koneksi terputus:
class DagangBotRealtimeClient {
constructor(apiBaseUrl, jwtToken) {
this.apiBaseUrl = apiBaseUrl;
this.jwtToken = jwtToken;
this.socket = null;
this.reconnectAttempts = 0;
this.maxReconnectDelay = 30000; // Maksimal jeda 30 detik
this.isDeliberateClose = false;
}
async connect() {
this.isDeliberateClose = false;
try {
// 1. Ambil tiket baru setiap kali akan menyambung
const response = await fetch(`${this.apiBaseUrl}/api/v1/events/ticket`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${this.jwtToken}` }
});
if (!response.ok) throw new Error('Gagal mengambil tiket WebSocket');
const { ticket } = await response.json();
// 2. Buka koneksi menggunakan tiket
const wsUrl = this.apiBaseUrl.replace(/^http/, 'ws') + `/ws?ticket=${ticket}`;
this.socket = new WebSocket(wsUrl);
this.socket.onopen = this.handleOpen.bind(this);
this.socket.onmessage = this.handleMessage.bind(this);
this.socket.onclose = this.handleClose.bind(this);
this.socket.onerror = this.handleError.bind(this);
} catch (error) {
console.error("Kesalahan koneksi Hub:", error);
this.scheduleReconnect();
}
}
handleOpen(event) {
console.log("Terhubung ke Realtime Hub DagangBot secara aman!");
this.reconnectAttempts = 0; // Reset hitungan pada koneksi sukses
}
handleMessage(event) {
try {
const payload = JSON.parse(event.data);
console.log(`[Event: ${payload.event}]`, payload.data);
// Pemrosesan berdasarkan tipe kejadian
if (payload.event === 'chat:message') {
// Render pesan masuk di UI...
}
} catch (e) {
console.error("Muatan WebSocket tidak valid:", event.data);
}
}
handleClose(event) {
if (this.isDeliberateClose) return;
console.warn(`Koneksi terputus (Kode: ${event.code}). Menjadwalkan koneksi ulang...`);
this.socket = null;
this.scheduleReconnect();
}
handleError(event) {
console.error("Terjadi kesalahan jaringan pada soket:", event);
// onclose otomatis dipanggil oleh peramban setelah onerror
}
scheduleReconnect() {
// Implementasi Jeda Eksponensial (Exponential Backoff)
const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
this.reconnectAttempts++;
console.log(`Mencoba sambung kembali dalam ${delay}ms...`);
setTimeout(() => this.connect(), delay);
}
disconnect() {
this.isDeliberateClose = true;
if (this.socket) this.socket.close(1000, "User logout");
}
}
// Cara Penggunaan
const client = new DagangBotRealtimeClient("https://dagangbot.web.id", "eyJh...");
client.connect();Karena tiket secara deterministik mendefinisikan batas otorisasi dan isolasi berdasarkan merchant_id yang valid, klien tidak perlu (dan dilarang) mengirimkan pesan tambahan seperti otorisasi sekunder atau pendaftaran subscribe ke topik. Aliran data otomatis akan menyesuaikan ruang tayang (Room Multiplexing).
4. Parameter & Spesifikasi Teknis
Pola Heartbeat dan Batas Tekanan (Backpressure)
Infrastruktur Hub kami sangat protektif terhadap koneksi terbengkalai (Zombie Connections) atau malicious payloads untuk memastikan ketersediaan memori tingkat tinggi:
- Ping/Pong Terjadwal: Server memancarkan paket kontrol
PINGke setiap klien persis setiap 54 detik (pingPeriod = (pongWait * 9) / 10, di manapongWait = 60 detik). Peramban (Browser) yang mematuhi standar RFC 6455 WebSockets akan secara transparan dan otomatis membalas dengan paketPONGtanpa perlu implementasi aplikasi tambahan. Kegagalan klien memantulkanPONGdalam waktu 60 detik berturut-turut akan menyebabkan pemutusan sepihak dengan asumsi perangkat terputus dari jaringan internet fisik. - Kapasitas Pembatasan: Ukuran muatan logis masuk (Dari klien ke peladen) maksimal ditetapkan dengan sangat kaku di angka
512 KB(maxMessageSize = 512 * 1024 bytes). Mengirimkan JSON melebihi limitasi kapasitas buffer ini seketika membuat parser membuang saluran. Selain itu, masa tunggu tulis jaringan (Write Wait) adalah 10 detik—jika Anda mengirim koneksi yang sengaja dihambat (Slowloris Attack), server akan memutuskannya secara agresif.
Transmisi Andal dengan Pola Outbox (Realtime Event Outbox)
Berbeda dengan antarmuka Webhook keluar yang bersifat Fire-and-Forget (seperti pemanggilan Webhook asinkron yang tidak melakukan penahanan (queue) ketika gagal), komponen infrastruktur kritis dalam DagangBot—terutama modul penagihan (Billing) dan mutasi kuota komputasi—menggunakan pendekatan Transactional Outbox Pattern.
Ketika sebuah transaksi terjadi (misalnya: pengurangan kuota komputasi saat sistem bot membalas pesan), perubahan saldo dan injeksi penyiaran pesan ditulis ke dalam basis data PostgreSQL pada satu siklus transaksi yang sama. Acara siaran disimpan ke tabel antrean transaksi internal secara berurutan dan persisten (monotonic sequence).
Jika klien kehilangan koneksi jaringan, klien dapat memanfaatkan fungsi Replay untuk mengambil (pull) acara-acara yang terlewat (sequence > afterSeq). Mekanisme perpaduan antara siaran memori (Hub) dan ketersediaan data permanen ini dengan aman menggaransi pengiriman yang tahan banting (Reliable), meminimalkan risiko klien kehilangan visibilitas (Data Loss) atas kejadian krusial walau di saat terjadinya lonjakan beban trafik (Spike load).
Tabel Parameter Negosiasi WebSocket
Saat melakukan transisi protokol (handshake) menuju ke rute /ws, autentikasi standar (Bearer Token) tidak dapat lagi digunakan pada header di lingkungan peramban web murni. Oleh karena itu, satu-satunya jalan masuk adalah melalui Query Parameter:
Penggusuran Sesi Aktif (EvictClient)
Infrastruktur Realtime secara terpusat menyiagakan fungsi evictClient. Apabila terjadi perubahan pada peran akses otoritas Anda (Role-Based Access Control) secara tiba-tiba di dasbor pengurus platform, Hub akan menendang (Drop) sesi WebSocket Anda yang tengah aktif. Peristiwa penggusuran ini membuat klien JavaScript terputus seketika dan dipaksa untuk meracik JWT token barunya guna menyambung kembali dengan serangkaian otorisasi mutakhir.
Katalog Event Klien (Masuk / Client-to-Server)
Meski saluran realtime dominan berjalan dari arah server, klien dapat melontarkan paket Client-to-Server Events sebagai tanggapan atau sinyal kehadiran. Muatan tetap harus berformat JSON dengan atribut kunci event dan data.
chat:typing: Meneruskan interaksi Live-typing kepada antarmuka pelanggan atau Dasbor lainnya, menyatakan bahwa agen CS manusia sedang merangkai pesan. Kejadian ini disiarkan secara efemeral (Ephemeral Broadcast)—semua agen dalam cabang yang sama akan melihatnya, kecuali sang pengirim itu sendiri, guna menghindari duplikasi visual di layar. Format:{"event": "chat:typing", "data": {"conversation_id": "conv-1", "is_typing": true, "typer": "agent"}}.escalation:ack: Merespons notifikasi status eskalasi (misalnya: Bot kecerdasan buatan memanggil intervensi manusia), yang menegaskan secara kriptografis bahwa agen yang sedang berjaga sudah menekan tombol tanggapan (Acknowledgement) dan mengambil alih rute percakapan.
Katalog Event Publik (Keluar / Server-to-Client)
Setiap event seketika dikirim sebagai teks murni JSON dengan struktur yang seragam. Berikut adalah kamus referensi untuk semua kejadian yang diinjeksikan secara asinkron dari Hub kami:
Rincian Muatan (Payload) Kejadian Publik
Berikut adalah spesifikasi JSON absolut untuk setiap kejadian yang diterima dari saluran WebSocket. Semua kejadian disiarkan secara asinkron dari Hub kami. Format utamanya selalu dibalut dalam envelope berikut:
{
"event": "nama_kejadian",
"data": { ... }
}1. Event: chat:message
Mentransmisikan objek pesan secara utuh sesaat setelah pesan diproses di database, atau jika terdapat balasan dari agen/bot (Outbound).
Struktur data:
2. Event: chat:status_change
Mentransmisikan transisi atau perubahan tanggung jawab balasan dalam sebuah saluran (misalnya, peralihan robotik ke campur tangan manusia).
Struktur data:
3. Event: escalation:new
Memicu notifikasi saat resolusi penyelesaian mandiri bot (RAG System) dipertimbangkan tidak cukup (RAG Fail) atau karena pelanggan menekan kata kunci eskalasi secara spesifik (Contoh: "Bicara dengan admin").
Struktur data:
4. Event: chat:message_status
Menyampaikan pembaruan resi pengiriman Meta WhatsApp untuk setiap gelembung pesan. Terpisah dari status percakapan untuk mencegah penimpaan (Overwriting) tak terduga (Race Condition).
Struktur data:
5. Event: fraud:alert
Pemicu seketika saat modul keamanan heuristik (Fraud Detection Module) mendeteksi pola percakapan manipulatif (Social Engineering / Scam / Upaya Bypass Instruksi Bot).
Struktur data:
6. Event Penagihan (billing:balance_updated & billing:invoice_updated)
Memberitahu antarmuka pengguna secara mulus saat limit kuota AI bertambah tanpa memerlukan penyegaran halaman (F5).
Struktur billing:balance_updated (data):
Struktur billing:invoice_updated (data):
5. Relasi & Integrasi
- Takeover CRM: Pusat kontak agen layanan pelanggan mengambil manfaat tertinggi dari Realtime Hub. Seluruh kejadian pengetikan pelanggan (
chat:typing) maupun peralihan robotik ke manusia bertumpu pada WebSockets untuk antarmuka nir-reload. - Notification Center: Menggantungkan peringatan pop-up (Toast notification), eskalasi RAG (
escalation:new), serta kedatangan deteksi manipulasi penipuan (fraud:alert) melalui WebSocket terpusat.
6. Tabel Pemecahan Masalah (Troubleshooting)
Koneksi WebSockets yang persisten memunculkan kompleksitas tersendiri di perutean jaringan (Routing). Berikut adalah diagnosis mendalam apabila Realtime Hub mengalami malfungsi:
7. Kode Error & Penanganan
Koneksi yang ditutup dapat menampilkan variasi kode terminasi (Close Status Codes) berdasarkan RFC 6455 standar protokol. Pahami kode ini untuk mengawasi status siklus sirkuit koneksi Anda:
