Panduan teknis memasang widget chat Mitrachat di website — bubble loader hosted, iframe inline, allowed domains, parentOrigin, dan troubleshooting connect.

Setelah membuat Provider Webchat di dashboard Mitrachat, langkah berikutnya adalah memasang widget di website Anda. Artikel ini menjelaskan tiga mode embed yang tersedia, cara mengisi Allowed Domains, dan apa yang harus dicek jika chat tidak bisa connect.

Ringkasan arsitektur hybrid embed

Mitrachat memakai model hosted hybrid:

Bubble loader (embed.min.js) — file kecil di situs Anda yang menampilkan tombol chat.
Hosted frame (frame.html di /webchat/chatbot/{providerId}) — UI chat penuh dimuat dari server Mitrachat, bukan dari origin website Anda.
Connect API — saat pengunjung membuka chat, widget memanggil webchat.connect dengan origin situs tenant untuk validasi domain.

Keuntungannya: situs Anda tidak perlu mem-bundle widget ~160KB, dan pembaruan UI/widget bisa dilakukan tanpa redeploy situs.

Prasyarat

Provider tipe Webchat sudah dibuat dan terhubung ke AI Agent.
Anda punya akses edit HTML situs (atau tag manager seperti GTM).
Hostname situs production sudah diketahui (mis. www.tokoanda.com dan tokoanda.com).

Langkah 1: Salin Provider ID dan snippet

Buka Providers > [webchat provider Anda] > Embed & Integration.

Tab default Bubble (recommended) menampilkan snippet seperti:

<script>
  window.mitrachatChatbotConfig = {
    token: 'YOUR-PROVIDER-UUID',
    baseUrl: 'https://mitrachat.id',
  };
</script>
<script
  src="https://mitrachat.id/webchat/embed.min.js"
  defer
></script>

Tempel snippet sebelum tag penutup </body> di setiap halaman yang perlu widget chat.

Langkah 2: Isi Allowed Domains

Di form provider yang sama, tambahkan satu hostname per baris (tanpa https://):

tokoanda.com
www.tokoanda.com

Field ini mengontrol dua hal:

Mekanisme	Fungsi
`frame-ancestors` CSP	Browser hanya mengizinkan iframe hosted dimuat di domain yang Anda daftarkan.
`webchat.connect` origin check	Server menolak koneksi jika `origin` pengunjung tidak cocok dengan whitelist.

Development: localhost dan 127.0.0.1 didukung. Tambahkan ke daftar jika Anda menguji embed lokal.

Production: Jangan biarkan daftar kosong saat go-live. Tanpa whitelist, respons hosted frame bisa memakai frame-ancestors 'none' (mode strict).

Langkah 3: Uji di situs live

Publish perubahan HTML.
Buka situs di browser biasa (bukan hanya preview dashboard).
Klik bubble — panel chat harus terbuka dan status connect berhasil.
Kirim pesan uji; pastikan AI Agent merespons.

Jika pratinjau di dashboard diblokir tetapi situs live berjalan, itu normal: hostname dashboard mungkin belum ada di Allowed Domains. Pratinjau hanya untuk smoke test cepat.

Inline iframe

Untuk menempatkan chat di dalam halaman (bukan floating bubble), gunakan tab Inline iframe. Snippet memuat:

/webchat/chatbot/{providerId}?parentOrigin={encoded-tenant-origin}

Parameter parentOrigin wajib agar server tahu situs mana yang meng-embed frame. Tanpa itu, connect bisa gagal dengan ORIGIN_REQUIRED.

Kustomisasi tanpa ubah snippet

Warna widget, judul, pesan sambutan, posisi bubble, dan form kontak dikontrol dari form provider di dashboard. Perubahan ini dipropagasi ke widget yang sudah terpasang — tidak perlu mengedit snippet di website.

Troubleshooting

Gejala	Kemungkinan penyebab	Solusi
Bubble muncul, chat error "Situs ini belum diizinkan"	Hostname tidak ada di Allowed Domains	Tambahkan hostname persis seperti di address bar (`www` vs non-`www`).
Frame kosong / diblokir browser	CSP `frame-ancestors`	Pastikan domain parent terdaftar; cek Console untuk error CSP.
Preview dashboard tidak load	Hostname dashboard tidak di-whitelist	Tambahkan hostname dashboard untuk uji, atau tes di staging/production.
Chat dibuka langsung lewat URL `/webchat/chatbot/...`	Navigasi top-level dengan whitelist aktif	Embed lewat bubble/iframe resmi; URL langsung ditolak (`ORIGIN_REQUIRED`).
Widget tidak muncul sama sekali	Snippet salah posisi atau `baseUrl` salah	Pastikan script sebelum `</body>`; `baseUrl` harus origin server widget.

Kode error connect

Server mengembalikan kode berikut lewat oRPC saat connect ditolak:

DOMAIN_NOT_ALLOWED — origin tidak cocok whitelist.
ORIGIN_REQUIRED — origin tidak bisa diverifikasi (iframe tanpa parentOrigin, atau navigasi document langsung).
INVALID_PROVIDER — UUID tidak valid atau bukan provider webchat.

Widget menampilkan pesan ramah pengguna dalam Bahasa Indonesia untuk setiap kode.

Checklist go-live

Snippet bubble terpasang di semua halaman target
Semua hostname production (termasuk www) ada di Allowed Domains
AI Agent aktif dan Knowledge Base terisi
Tes kirim pesan dari perangkat dan browser berbeda
(Opsional) Inline iframe memakai parentOrigin yang benar

Butuh bantuan lebih lanjut? Hubungi tim Mitrachat atau buka dokumentasi production readiness di repositori internal tim engineering.

Panduan Embed Webchat Widget Mitrachat: Bubble, Iframe, dan Allowed Domains