Lewati ke konten utama

Widget Situs Web (Website Widget)

Widget situs web adalah kotak obrolan yang disematkan ke halaman situs Anda sehingga pengunjung dapat memulai percakapan dengan tim Anda melalui inbox bertipe website. Anda perlu menyiapkan inbox, membuat production Embed Key, mengambil cuplikan sematan (embed snippet), dan memahami alur percakapan di sisi pengunjung.

Tujuan​

  • Menyiapkan inbox bertipe website untuk menerima percakapan dari widget.
  • Membuat production Embed Key dan memahami cara kerjanya.
  • Mendapatkan cuplikan HTML siap semat dan memahami atribut-atributnya.
  • Memahami alur pengunjung: identitas → sesi → konfigurasi → percakapan → pesan.
  • Mengetahui batas keamanan dan batasan produk widget saat ini.

Untuk siapa​

  • Admin/owner yang mengelola inbox, kunci widget, dan menyalin kode sematan.
  • Developer yang menyematkan widget ke situs atau menyesuaikan integrasinya.

Prasyarat​

  • Peran admin/owner untuk membuat inbox website dan mengelola Embed Key.
  • Kunci rahasia JWT aplikasi telah dikonfigurasi (aplikasi menolak mulai bila kunci kosong).
  • URL dasar API (API base) dapat diakses dari situs yang akan menyematkan widget.
  • Origin halaman sematan harus terdaftar pada daftar izin CORS server (CORS_ORIGINS; lihat Deployment dan runtime). Tanpa izin ini, peramban memblokir panggilan widget ke API.

Langkah-langkah​

1. Membuat inbox website​

  1. Buka menu Inboxes dan buat inbox baru dengan tipe saluran website.
  2. Beri nama inbox (misalnya "Dukungan Situs") dan isi setelan opsional seperti sambutan (greeting) dan URL avatar.
  3. Simpan; inbox ini yang akan menerima percakapan dari widget.

2. Membuat production Embed Key (wajib)​

  1. Buka setelan Website widget (khusus owner/admin).
  2. Pilih inbox website yang akan menerima percakapan.
  3. Pada bagian instalasi, pilih Create embed key dan beri nama deskriptif, misalnya website-produksi.
  4. Salin raw key yang ditampilkan — kunci hanya ditampilkan sekali. Setelah halaman ditutup, kunci tidak dapat dilihat lagi; sistem hanya menyimpan hash SHA-256-nya.
  5. Gunakan kunci tersebut pada atribut data-widget-key di cuplikan sematan.

Apakah perlu membuat Workspace API Key? Tidak. Untuk website widget, buat Embed Key dari setelan Website widget setelah memilih inbox. Embed Key ini terikat pada inbox dan merupakan token bootstrap publik, bukan secret admin/CRM. Jangan memakai API key generik atau token admin pada kode situs.

3. Mengambil dan menyematkan cuplikan​

  1. Di setelan Website widget, pilih inbox website tujuan.

  2. Salin cuplikan sematan. Bentuk dasarnya:

    <script
      src="{base}/widget.js"
      data-inbox-id="{websiteInboxId}"
      data-widget-key="crmw_…"
      data-api-base="{base}"
      data-widget></script>

  3. Tempel cuplikan sebelum penutup </body> pada halaman yang dituju.

  4. Pastikan kedua atribut berikut selalu ada:

    • data-inbox-id="{websiteInboxId}" — menentukan inbox tujuan.
    • data-widget-key="crmw_…" — diperlukan untuk memulai sesi widget.

  5. Isi data-api-base dengan origin API publik (tanpa akhiran /api/v1). Atribut opsional lain yang didukung skrip: data-theme-color, data-greeting, dan data-position (bottom-left/bottom-right).

4. Memverifikasi pengalaman pengunjung​

  1. Buka halaman yang sudah disematkan di jendela privat.
  2. Klik gelembung obrolan; widget meminta nama, email, dan nomor telepon yang valid sebelum memulai percakapan.
  3. Kirim pesan uji dan pastikan percakapan muncul di inbox website pada aplikasi.
  4. Muat ulang halaman dengan identitas yang sama — widget melanjutkan percakapan yang ada (sesi dipulihkan lewat visitor_id).
  5. Uji papan ketik: buka/tutup panel dari gelembung (elemen <button> asli) dan kirim pesan dengan menekan Enter pada kolom input.
  6. Periksa dukungan teknologi bantu: gelembung serta tombol tutup/kirim memiliki aria-label, kolom input memiliki aria-label, dan panel memakai role="dialog" dengan aria-modal="true". Setelah panel ditutup, fokus kembali ke gelembung.
  7. Catat bahwa kontras warna, ukuran target sentuh, dan perilaku pembaca layar belum diverifikasi menyeluruh lintas peramban; lakukan pengujian aksesibilitas pada halaman nyata bila hal itu menjadi syarat.

5. Merotasi atau mencabut Embed Key​

  1. Buat Embed Key pengganti dari setelan Website widget untuk inbox yang sama.
  2. Perbarui data-widget-key pada halaman situs dan publikasikan perubahan tersebut.
  3. Verifikasi widget dengan jendela privat, lalu cabut key lama dari daftar Workspace API keys.
  4. Kunci yang dicabut langsung ditolak pada permintaan berikutnya; statusnya ditandai revoked_at.

Tanda berhasil​

  • Cuplikan sematan menampilkan gelembung widget dengan nama inbox dan sambutan yang dikonfigurasi.
  • Pengunjung yang mengisi profil berhasil membuka percakapan; pesannya muncul di inbox website.
  • Percakapan dan pesan baru tampil di aplikasi web tanpa autentikasi tambahan dari sisi pengunjung.
  • Kunci yang dicabut tidak lagi dapat membuat sesi.

Dari pesan visitor ke balasan agen​

Setelah pesan visitor muncul di inbox website, supervisor atau aturan auto-assignment dapat menugaskan percakapan kepada agen atau tim. Agen membalas dari percakapan Custelio; pesan website disimpan sebagai sent, lalu widget mengambil riwayat pesan terbaru secara berkala untuk menampilkan balasan kepada visitor. Lihat Siklus Pesan Kanal ke Agen untuk alur lengkap inbound, assignment, dan balasan customer.

Jika terjadi masalah​

  • 401 invalid widget key: Embed Key salah, dicabut, atau tidak cocok dengan data-inbox-id. Periksa kedua atribut tersebut, buat key pengganti bila perlu, lalu perbarui halaman.
  • 429 saat membuat sesi berulang kali: proteksi brute-force aktif (10 percobaan per 5 menit, terkunci 10 menit). Tunggu hingga jendela berakhir.
  • Pesan gagal terkirim: pastikan percakapan sudah dibuat — endpoint pesan memerlukan sesi yang sudah memiliki percakapan aktif (alur /client/conversation dijalankan sebelum mengirim).
  • Widget tidak muncul atau berhenti pada setup: periksa konsol browser untuk galat CORS/akses ke {base}/api/v1; pastikan data-api-base, data-inbox-id, dan data-widget-key benar.

Batasan​

  • Embed Key produksi terikat pada satu inbox website. Cuplikan produksi harus menyediakan data-inbox-id dan data-widget-key; jangan menggantinya dengan Workspace API Key generik atau token admin.
  • Kunci ditampilkan sekali; bila hilang, buat kunci baru dan cabut kunci lama.
  • Kunci adalah token bootstrap publik — bukan rahasia admin/CRM. Lindungi halaman yang menyematkannya sebagaimana Anda melindungi kode publik lainnya.
  • Indikator mengetik (/client/typing) dicatat statusnya tetapi belum terhubung ke pengiriman real-time ke agen.
  • Avatar logo diverifikasi sebagai gambar (jpeg/png/webp) sebelum ditampilkan.
  • Widget menyimpan identitas pengunjung di localStorage browser pengunjung; menghapus data situs berarti pengunjung dianggap baru.
  • Penyematan memakai satu inbox website per cuplikan; untuk banyak tujuan gunakan beberapa cuplikan/inbox.
  • CORS hanya mengizinkan origin yang terdaftar pada CORS_ORIGINS (atau * bila dikonfigurasi demikian). Kebijakan CORS adalah kontrol peramban, bukan otorisasi API: permintaan dari origin tak terdaftar tetap dapat dikirim oleh klien non-peramban, jadi jangan andalkan CORS sebagai satu-satunya batas keamanan.

Tugas terkait​