---
title: "Panduan Embed Webchat Widget Mitrachat: Bubble, Iframe, dan Allowed Domains"
description: "Panduan teknis memasang widget chat Mitrachat di website — bubble loader hosted, iframe inline, allowed domains, parentOrigin, dan troubleshooting connect."
canonical: https://mitrachat.id/blog/panduan-embed-webchat-widget-mitrachat
publishedAt: 2026-06-27
updatedAt: 2026-06-27
locale: id
author: Mitrachat
tags:
  - webchat
  - embed
  - widget
  - tutorial
  - integration
---
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**:

1. **Bubble loader** (`embed.min.js`) — file kecil di situs Anda yang menampilkan tombol chat.
2. **Hosted frame** (`frame.html` di `/webchat/chatbot/{providerId}`) — UI chat penuh dimuat dari server Mitrachat, bukan dari origin website Anda.
3. **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:

```html
<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

1. Publish perubahan HTML.
2. Buka situs di browser biasa (bukan hanya preview dashboard).
3. Klik bubble — panel chat harus terbuka dan status connect berhasil.
4. 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.