Tutorial Embed SDK Livechat Barantum di Web

Panduan HTML, pembuatan identifier HMAC, konfigurasi widget, dan implementasi yang aman

Diperbarui pada 07 September 2026

Dokumen ini menjelaskan cara memasang Livechat Barantum pada halaman HTML. Tutorial mencakup pembuatan identifier hash dengan HMAC-SHA256, pemuatan widget secara dinamis, penjelasan setiap bagian kode, serta pola implementasi yang direkomendasikan untuk production.


Gambar 0.1. Tampilan Livechat widget

Gambar 0.2. Tampilan Livechat di buka


1. Hasil akhir

Setelah integrasi selesai, halaman web akan menampilkan bubble Livechat Barantum. Jika pengunjung sudah login, widget juga menerima ID, nama, dan email pengunjung sehingga agent dapat mengenali pengguna yang sedang menghubungi.

Penting: contoh HMAC di browser hanya digunakan untuk demonstrasi. Pada production, HMAC secret wajib disimpan dan diproses di backend.


2. Prasyarat

  • Inbox Livechat Barantum sudah dibuat dan diaktifkan.
  • Anda memiliki inbox identifier untuk inbox tersebut.
  • Anda memiliki HMAC secret jika ingin menggunakan identitas pengunjung terverifikasi.
  • Halaman dijalankan melalui HTTPS atau localhost agar Web Crypto API tersedia.


3. Konsep identifier dan HMAC

visitorId adalah ID unik pengguna di sistem Anda, misalnya ID dari database atau sesi login. Nilai ini dikirim ke widget melalui atribut data-visitor-id.

identifierHash adalah tanda tangan digital yang dibuat dari visitorId menggunakan HMAC secret milik inbox. Widget mengirim nilai tersebut sebagai data-livechat-hash untuk membuktikan bahwa visitorId tidak dibuat atau diubah secara sembarangan.

identifier_hash = HMAC_SHA256(hmacSecret, visitorId)

Nilai visitorId yang ditandatangani harus sama persis dengan nilai data-visitor-id. Perbedaan huruf besar, spasi, prefix, atau karakter lain akan menghasilkan hash yang berbeda.


4. Contoh HTML lengkap untuk demonstrasi

Contoh berikut membuat HMAC di browser, menempatkannya pada konfigurasi widget, lalu memuat widget.js secara dinamis. Ganti semua nilai placeholder sebelum melakukan pengujian.

<!DOCTYPE html>

<html lang="id">

<head>

  <meta charset="UTF-8">

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <meta http-equiv="X-UA-Compatible" content="ie=edge">

  <title>Embedding Livechat Barantum</title>

  <link rel="stylesheet" href="styles.css">

</head>


<body>

  <h1>Embedding Livechat Barantum</h1>


  <script>

    /**

     * Membuat HMAC-SHA256 dalam format hexadecimal lowercase.

     */

    async function generateIdentifierHmac(identifier, secretKey) {

      const encoder = new TextEncoder();


      const key = await crypto.subtle.importKey(

        "raw",

        encoder.encode(secretKey),

        {

          name: "HMAC",

          hash: "SHA-256"

        },

        false,

        ["sign"]

      );


      const signature = await crypto.subtle.sign(

        "HMAC",

        key,

        encoder.encode(identifier)

      );


      return Array.from(new Uint8Array(signature))

        .map(byte => byte.toString(16).padStart(2, "0"))

        .join("");

    }


    /**

     * Menyiapkan konfigurasi dan memuat widget Livechat Barantum.

     */

    async function loadBarantumLivechat() {

      const visitor = {

        id: "USER_ID_DARI_SISTEM_ANDA",

        name: "NAMA_USER",

        email: "EMAIL_USER"

      };


      // Hanya untuk demo lokal. Jangan taruh secret di frontend production.

      const hmacSecret = "HMAC_SECRET_ANDA";


      try {

        const identifierHash = await generateIdentifierHmac(

          visitor.id,

          hmacSecret

        );


        const widgetScript = document.createElement("script");


        widgetScript.src =

          "https://livechat.barantum.com/widget.js";


        widgetScript.dataset.livechatUrl =

          "https://livechat.barantum.com";


        widgetScript.dataset.livechatInbox =

          "INBOX_IDENTIFIER_ANDA";


        widgetScript.dataset.livechatHash =

          identifierHash;


        widgetScript.dataset.visitorId =

          visitor.id;


        widgetScript.dataset.visitorName =

          visitor.name;


        widgetScript.dataset.visitorEmail =

          visitor.email;


        widgetScript.dataset.title =

          "Demo";


        widgetScript.dataset.subtitle =

          "Kami siap membantu 24 jam!";


        widgetScript.dataset.locale =

          "id";


        widgetScript.dataset.position =

          "left";


        widgetScript.dataset.logo =

          "https://example.com/logo.png";


        widgetScript.onload = function () {

          console.log("Livechat Barantum berhasil dimuat");

        };


        widgetScript.onerror = function () {

          console.error("Livechat Barantum gagal dimuat");

        };


        document.body.appendChild(widgetScript);

      } catch (error) {

        console.error(

          "Gagal membuat identifier HMAC:",

          error

        );

      }

    }


    loadBarantumLivechat();

  </script>

</body>

</html>


5. Penjelasan kode

5.1 Fungsi generateIdentifierHmac

Fungsi generateIdentifierHmac(identifier, secretKey) bertugas membuat signature HMAC-SHA256. Fungsi diberi kata kunci async karena Web Crypto API bekerja secara asynchronous dan mengembalikan Promise.

const encoder = new TextEncoder();

TextEncoder mengubah identifier dan secret dari string menjadi byte UTF-8. Web Crypto API memproses data dalam bentuk byte, bukan string JavaScript biasa.

const key = await crypto.subtle.importKey(

  "raw",

  encoder.encode(secretKey),

  { name: "HMAC", hash: "SHA-256" },

  false,

  ["sign"]

);

crypto.subtle.importKey mengubah secret menjadi CryptoKey. Konfigurasi name: "HMAC" menentukan jenis algoritma, sedangkan hash: "SHA-256" menentukan fungsi hash yang digunakan. Izin ["sign"] membatasi kunci untuk membuat signature.

const signature = await crypto.subtle.sign(

  "HMAC",

  key,

  encoder.encode(identifier)

);

crypto.subtle.sign menandatangani identifier menggunakan kunci HMAC. Hasilnya masih berupa ArrayBuffer.

return Array.from(new Uint8Array(signature))

  .map(byte => byte.toString(16).padStart(2, "0"))

  .join("");

Bagian terakhir mengubah ArrayBuffer menjadi string hexadecimal lowercase. Format inilah yang dikirim sebagai identifier_hash.


5.2 Fungsi loadBarantumLivechat

Fungsi loadBarantumLivechat mengumpulkan identitas visitor, meminta atau membuat identifier hash, lalu membuat elemen script untuk widget.

const visitor = {

  id: "USER_ID_DARI_SISTEM_ANDA",

  name: "NAMA_USER",

  email: "EMAIL_USER"

};

Pada aplikasi nyata, data visitor sebaiknya berasal dari user yang sudah terautentikasi, bukan dari input bebas pada halaman.


5.3 Mengapa widget dimuat secara dinamis?

Pembuatan HMAC membutuhkan await. Karena itu, widget.js baru ditambahkan setelah identifierHash tersedia. Cara ini mencegah widget dijalankan lebih awal tanpa hash.

const widgetScript = document.createElement("script");

widgetScript.src = "https://livechat.barantum.com/widget.js";

document.body.appendChild(widgetScript);

5.4 Pemetaan dataset ke atribut HTML

Properti dataset menggunakan camelCase. Browser otomatis mengubahnya menjadi atribut data-* pada elemen script.

  • dataset.livechatUrl menjadi data-livechat-url.
  • dataset.livechatInbox menjadi data-livechat-inbox.
  • dataset.livechatHash menjadi data-livechat-hash.
  • dataset.visitorId menjadi data-visitor-id.
  • dataset.visitorName menjadi data-visitor-name.
  • dataset.visitorEmail menjadi data-visitor-email.


6. Referensi konfigurasi utama

  • data-livechat-url: alamat server Livechat Barantum.
  • data-livechat-inbox: identifier inbox tujuan.
  • data-livechat-hash: HMAC-SHA256 untuk memverifikasi visitorId.
  • data-visitor-id: ID unik pengguna dari sistem Anda.
  • data-visitor-name: nama pengguna yang ditampilkan kepada agent.
  • data-visitor-email: email pengguna.
  • data-title: judul pada header widget.
  • data-subtitle: teks tambahan pada header widget.
  • data-locale: bahasa widget, misalnya id atau en.
  • data-position: posisi bubble, left atau right.
  • data-logo: URL logo yang dapat diakses secara publik.


7. Event Livechat pada Web SDK

Web SDK menyediakan fungsi Barantum.on(event, callback) untuk menerima perubahan dari widget. Pasang listener setelah widget.js selesai dimuat. Setiap pemanggilan Barantum.on() mengembalikan fungsi unsubscribe yang dapat digunakan untuk melepas listener.


7.1 Event yang tersedia

  • ready — dipanggil ketika sesi Livechat berhasil terhubung dan widget siap digunakan. Event ini tidak memiliki payload.
  • open — dipanggil ketika panel Livechat dibuka. Event ini tidak memiliki payload.
  • close — dipanggil ketika panel Livechat ditutup, baik melalui tombol widget maupun pemanggilan Barantum.close(). Event ini tidak memiliki payload.
  • unread — dipanggil ketika jumlah pesan agent yang belum dibaca berubah. Callback menerima count berupa number.
  • status — dipanggil ketika status percakapan berubah. Callback menerima nilai pending, progress, atau done.

7.2 Contoh pemasangan listener

Karena contoh tutorial memuat widget secara dinamis, pasang listener melalui event load milik elemen script sebelum elemen tersebut ditambahkan ke halaman:

widgetScript.addEventListener("load", function () {

  const unsubscribeReady = Barantum.on("ready", function () {

    console.log("Livechat siap digunakan");

  });


  const unsubscribeOpen = Barantum.on("open", function () {

    console.log("Panel Livechat dibuka");

  });


  const unsubscribeClose = Barantum.on("close", function () {

    console.log("Panel Livechat ditutup");

  });


  const unsubscribeUnread = Barantum.on("unread", function (count) {

    console.log("Pesan belum dibaca:", count);

    // Contoh: perbarui badge pada tombol bantuan.

  });


  const unsubscribeStatus = Barantum.on("status", function (status) {

    console.log("Status percakapan:", status);


    if (status === "pending") {

      console.log("Percakapan menunggu respons agent");

    } else if (status === "progress") {

      console.log("Percakapan sedang ditangani");

    } else if (status === "done") {

      console.log("Percakapan telah selesai");

    }

  });


  window.addEventListener("pagehide", function () {

    unsubscribeReady();

    unsubscribeOpen();

    unsubscribeClose();

    unsubscribeUnread();

    unsubscribeStatus();

  }, { once: true });

});


document.body.appendChild(widgetScript);

Jika widget.js dipasang langsung menggunakan tag script dengan atribut defer, listener dapat didaftarkan di dalam callback DOMContentLoaded.


7.3 Melepas listener

Simpan fungsi unsubscribe yang dikembalikan oleh Barantum.on(), kemudian panggil fungsi tersebut saat komponen atau halaman dibersihkan. Hal ini mencegah callback terdaftar lebih dari sekali ketika widget diinisialisasi ulang.

const unsubscribeUnread = Barantum.on("unread", function (count) {

  updateUnreadBadge(count);

});


// Panggil ketika listener tidak lagi dibutuhkan.

unsubscribeUnread();


8. Implementasi production yang aman

Jangan pernah menyimpan HMAC secret di HTML, JavaScript frontend, repository publik, localStorage, atau response API.

Pada production, backend harus mengambil user ID dari sesi login, menghitung HMAC, kemudian mengirimkan hanya identifierHash dan profil visitor ke browser.


8.1 Contoh backend Node.js

import crypto from "node:crypto";


app.get(

  "/api/livechat/identity",

  requireAuthentication,

  (request, response) => {

    const visitorId = String(request.user.id);


    const identifierHash = crypto

      .createHmac(

        "sha256",

        process.env.LIVECHAT_HMAC_SECRET

      )

      .update(visitorId, "utf8")

      .digest("hex");


    response.json({

      visitorId,

      visitorName: request.user.name,

      visitorEmail: request.user.email,

      identifierHash

    });

  }

);

Endpoint tidak menerima visitorId bebas dari browser. ID diambil dari sesi user yang sudah diverifikasi oleh requireAuthentication.


8.2 Contoh frontend production

async function getLivechatIdentity() {

  const response = await fetch(

    "/api/livechat/identity",

    {

      credentials: "include"

    }

  );


  if (!response.ok) {

    throw new Error("Gagal mengambil identitas livechat");

  }


  return response.json();

}


async function loadBarantumLivechat() {

  const identity = await getLivechatIdentity();

  const widgetScript = document.createElement("script");


  widgetScript.src =

    "https://livechat.barantum.com/widget.js";


  widgetScript.dataset.livechatUrl =

    "https://livechat.barantum.com";


  widgetScript.dataset.livechatInbox =

    "INBOX_IDENTIFIER_ANDA";


  widgetScript.dataset.livechatHash =

    identity.identifierHash;


  widgetScript.dataset.visitorId =

    identity.visitorId;


  widgetScript.dataset.visitorName =

    identity.visitorName;


  widgetScript.dataset.visitorEmail =

    identity.visitorEmail;


  document.body.appendChild(widgetScript);

}


loadBarantumLivechat();

Dengan pola ini, browser tidak pernah menerima HMAC secret. Browser hanya menerima signature untuk user yang sedang login.


9. Urutan proses integrasi

  1. Pengguna membuka halaman web dan login ke aplikasi Anda.
  2. Frontend meminta identitas Livechat dari backend.
  3. Backend mengambil user ID dari sesi login.
  4. Backend membuat HMAC-SHA256 menggunakan HMAC secret.
  5. Backend mengirim visitorId, profil visitor, dan identifierHash.
  6. Frontend memasang konfigurasi tersebut pada elemen widget.js.
  7. Widget Livechat Barantum dimuat dan bubble chat ditampilkan.


10. Cara menguji

  1. Ganti INBOX_IDENTIFIER_ANDA dengan inbox identifier yang valid.
  2. Untuk demo lokal saja, isi HMAC_SECRET_ANDA dengan secret inbox.
  3. Jalankan halaman melalui localhost atau HTTPS.
  4. Buka Developer Tools lalu periksa tab Console.
  5. Pastikan pesan “Livechat Barantum berhasil dimuat” muncul.
  6. Buka bubble chat dan kirim pesan percobaan.
  7. Pastikan identitas visitor yang terlihat oleh agent sesuai dengan user yang login.


11. Troubleshooting

Bubble chat tidak muncul

  • Pastikan URL widget adalah https://livechat.barantum.com/widget.js.
  • Pastikan inbox identifier sudah benar dan inbox sudah aktif.
  • Periksa error pada Console dan Network di browser.
  • Pastikan elemen widget tidak dimuat lebih dari satu kali.

HMAC ditolak atau identitas tidak terverifikasi

  • Pastikan algoritma yang digunakan adalah HMAC-SHA256.
  • Pastikan output menggunakan hexadecimal lowercase.
  • Pastikan visitorId yang ditandatangani sama persis dengan data-visitor-id.
  • Pastikan secret berasal dari inbox yang sama dengan inbox identifier.
  • Pastikan tidak ada spasi tambahan sebelum atau sesudah visitorId.


12. Checklist sebelum production

  • HMAC secret hanya tersimpan di environment variable backend.
  • Endpoint identitas dilindungi autentikasi.
  • Backend mengambil user ID dari sesi, bukan dari parameter bebas browser.
  • Tidak ada secret atau token sensitif di source code frontend.
  • visitorId dan identifierHash berasal dari user yang sama.
  • Inbox identifier dan URL Livechat sudah sesuai environment.
  • Error frontend ditangani tanpa mencetak secret ke log.


13. Ringkasan

Integrasi widget dilakukan dengan membuat konfigurasi pada elemen script, lalu menambahkan widget.js ke halaman. Untuk identitas terverifikasi, backend membuat HMAC-SHA256 dari visitorId menggunakan secret inbox. Frontend hanya menerima hasil hash dan tidak boleh mengetahui secret.

Apakah konten di atas membantu?

Bantu kami meningkatkan kualitas dari guidebook kami dengan mengisi form

Isi Form Saran

© 2026 Barantum. All rights reserved.

Banner CTA