Page Layout
Halaman Embed terdiri dari tiga blok, tersusun dari atas ke bawah. Tautan lama yang memakai ?tab= di URL tetap berfungsi: tautan itu menggulir ke blok yang sesuai.
| |
|---|
| Build your embed | Membuka builder, atau menyalin snippet terkecil yang sudah berfungsi. Tombolnya: Open builder (terbuka di tab browser baru) dan Copy basic snippet. |
| Opening lines from websites | Menentukan apa yang boleh dikirim situs yang meng-embed agent untuk membuka chat, menggantikan Welcome Message. Satu-satunya setelan yang disimpan di halaman ini. |
| Developer guide | Bacaan untuk memasang elemen ke situs secara manual. Tidak ada yang disimpan di sini. Menautkan ke dokumentasi ini lewat Full docs on qlar.ai. |
Developer Guide Sections
| |
|---|
| Install | Tag script, elemen, dan contoh satu halaman penuh. |
| In React | Memuat script di index.html, mendeklarasikan custom element untuk TypeScript, dan memakainya di komponen. |
| Layout | Inline versus floating. |
| Floating panel | Sudut, offset, dan ukuran panel. |
| Theme and colors | Tema, app mode, logo agent, judul panel, dan warna header. |
| Top bar | Switch utama dan setiap item di bar. |
| Behavior | Autofocus dan resume window. |
| Opening line from code | Cara mengirim kalimat pembuka dari halaman situs. |
| Attribute reference | Seluruh atribut, dikelompokkan seperti tabel di bawah. |
Copy Basic Snippet
Menyalin tag script dan satu elemen di dalam <div style="height: 600px">, dengan hanya ID agen Anda yang diisi. Semua yang lain memakai default: tema pengunjung, aplikasi penuh, dan input yang langsung fokus. Tombolnya menampilkan Copied selama dua detik.
Element and Script
| |
|---|
| Script | https://app-container.qlar.ai/qlar-component.mjs, dimuat dengan type="module" crossorigin. |
| Element | <qlar-component>. Script ini juga mendaftarkan nama lama elemennya, <pusaka-container>, sehingga embed yang memakai nama itu tetap berfungsi. |
| Agent Binding | Setiap elemen terhubung ke satu agent, diatur lewat data-agent-id. |
| Inline Mode | Mode default. Chat mengisi elemen induknya, jadi elemen induk perlu punya tinggi. |
| Floating Mode | data-mode="floating". Tombol yang menempel di sudut jendela membuka dan menutup panel chat. Tidak perlu elemen pembungkus, baik di HTML biasa maupun di React. |
Attributes
Semua atribut <qlar-component>, dikelompokkan seperti referensi atribut di CMS. Semua opsional kecuali data-agent-id.
Identity
| Atribut | Default | Keterangan |
|---|
data-agent-id | Wajib | Agent yang diajak bicara oleh chat. |
Layout
| Atribut | Default | Keterangan |
|---|
data-mode | inline | floating menampilkan tombol yang menempel di sudut viewport untuk membuka dan menutup panel chat. Bila dikosongkan atau inline, chat mengisi elemen induk. |
data-position | bottom-right | Sudut tombol floating: bottom-right, bottom-left, top-right, top-left. Hanya untuk mode floating. |
data-offset-x | 20px | Jarak horizontal antara tombol dan tepi viewport. CSS length apa pun. Hanya untuk mode floating. |
data-offset-y | 20px | Jarak vertikal antara tombol dan tepi viewport. CSS length apa pun. Hanya untuk mode floating. |
data-chat-width | 380px | Lebar panel floating. CSS length apa pun. Memenuhi layar bila lebar viewport di bawah 480px. Hanya untuk mode floating. |
data-chat-height | 580px | Tinggi panel floating. CSS length apa pun. Hanya untuk mode floating. |
Appearance
| Atribut | Default | Keterangan |
|---|
data-theme | system | system (mengikuti OS), light, atau dark. |
data-app-mode | full-app | full-app atau chat. Saat ini keduanya tampil sama. Atribut ini tidak menyembunyikan top bar: pakai data-show-top-bar="false" untuk itu. |
data-show-agent-logo | true | Menampilkan atau menyembunyikan logo agent di atas sapaan. |
data-chat-title | Chat | Judul di header bar panel floating. Hanya untuk mode floating. |
data-show-title | true | Menampilkan atau menyembunyikan header bar panel floating: judul, tombol perbesar, dan tombol tutup. Saat disembunyikan, tombol launcher menutup panel. Bila lebar jendela di bawah 480px, header bar selalu tampil. Hanya untuk mode floating. |
Keempatnya menerima nilai hex CSS, misalnya #5651D4, dan hanya berlaku di mode floating. Bila warna latar dikosongkan, warnanya diturunkan dari warna tema agent, sekitar 18% lebih gelap.
| Atribut | Default | Keterangan |
|---|
data-light-title-bg | Diturunkan | Warna latar header bar di mode terang. |
data-light-title-fg | Tidak ada | Warna teks judul dan ikon header bar di mode terang. |
data-dark-title-bg | Diturunkan | Warna latar header bar di mode gelap. |
data-dark-title-fg | Tidak ada | Warna teks judul dan ikon header bar di mode gelap. |
Top Bar
| Atribut | Default | Keterangan |
|---|
data-show-top-bar | true | Switch utama. false menyembunyikan semua item di bar. Atribut di bawahnya hanya berlaku selama ini true. |
data-show-menu | true | Menampilkan atau menyembunyikan menu hamburger (daftar percakapan). |
data-show-new-chat | true | Menampilkan atau menyembunyikan tombol percakapan baru. |
data-show-theme-toggle | true | Menampilkan atau menyembunyikan toggle tema terang/gelap. |
data-show-sign-in | true | Menampilkan atau menyembunyikan tombol sign-in, atau menu akun setelah sign-in. |
Opening Line
Tiga atribut pertama hanya berlaku bila switch pasangannya di Opening lines from websites menyala, sudah disimpan, dan agent sudah dipublish. Bila halaman mengisi lebih dari satu, yang menang mengikuti urutan daftar ini.
| Atribut | Default | Keterangan |
|---|
data-intro-message | Tidak ada | Teks yang ditampilkan apa adanya, menggantikan Welcome Message. Butuh Custom text. |
data-intro-prompt | Tidak ada | Prompt yang dijawab agent. Jawabannya menjadi kalimat pembuka. Persona, tools, dan knowledge agent berlaku, dan pengunjung tidak pernah melihat prompt-nya. Butuh Custom prompt. |
data-intro-raw-prompt | Tidak ada | Prompt yang dijawab tanpa system prompt sama sekali, untuk mengubah data milik situs menjadi kalimat pembuka, misalnya ringkasan pesanan. Persona dan guardrail agent tidak berlaku. Butuh Prompt without system prompt, beserta guardrail. |
data-show-examples | true | Menampilkan atau menyembunyikan contoh pesan di bawah sapaan, yang diatur di Conversation → Introduction. Tidak butuh switch, dan tidak memengaruhi saran lanjutan yang ditulis agent setelah setiap jawaban. |
Behavior
| Atribut | Default | Keterangan |
|---|
data-enable-autofocus | true | Memfokuskan input chat saat dimuat dan setelah setiap jawaban. false mematikannya. |
data-thread-ttl | 21600000 | Berapa lama, dalam milidetik, percakapan bisa dilanjutkan setelah halaman situs dimuat ulang, dihitung dari pesan terakhir. Default-nya 6 jam. Hanya untuk pengunjung anonim di mode floating. |
data-wa-handoff | true | Mengambil kode masuk WhatsApp (wa_code) dari alamat halaman situs dan memasukkan pengunjung. false membuat chat ini mengabaikannya. Lihat WhatsApp Bridge Mode di bawah. |
Dalam praktiknya:
| |
|---|
| Autofocus | Menyala secara default. Matikan bila chat berada jauh di bawah halaman yang panjang, karena lompatan fokus terlihat seperti halaman menggulir sendiri. |
| Resume Window | Untuk pengunjung anonim di mode floating, memuat ulang halaman akan melanjutkan percakapan yang sama sampai data-thread-ttl habis. Setelah itu, percakapan baru dimulai. Batas waktu ini hanya disimpan di browser pengunjung; tidak ada yang dihapus di server. Embed inline tidak melanjutkan percakapan. |
WhatsApp Bridge Mode
Halaman yang memasang chat bisa menjadi tujuan WhatsApp → Alihkan ke web. Qlar menambahkan ?wa_code=…&wa_agent={ID agent} ke alamat halaman pada tautan yang dikirim lewat WhatsApp.
| |
|---|
| Terbaca Otomatis | Chat membaca wa_code dari alamat halaman, memasukkan pengunjung sebagai akun WhatsApp-nya, lalu menghapus wa_code dan wa_agent dari address bar. Parameter lain tetap ada. Tidak perlu mengubah kode halaman. |
| Panel Floating | Terbuka sendiri saat kode datang. |
| Pesan Pertama | Pesan yang ditulis pengunjung di WhatsApp langsung dikirim sebagai pesan pertama, sehingga agent langsung menjawabnya. |
| Beberapa Chat | Hanya chat yang data-agent-id-nya sama dengan wa_agent yang mengambil kode. |
| Percakapan Tamu | Chat floating tidak melanjutkan percakapan anonim pengunjung sebelumnya, sehingga tidak menempel ke akun WhatsApp. |
| Menolak | data-wa-handoff="false" membuat chat mengabaikan kode dan membiarkan alamat halaman apa adanya. |
| Tautan Tidak Berlaku | Tautan yang sudah dipakai atau kedaluwarsa menampilkan "This link is no longer valid. Send us another WhatsApp message to get a new link.", dengan Continue dan Sign in. |
Opening Lines From Websites
Bila semua switch mati, pengunjung melihat Welcome Message dari Conversation → Introduction, apa pun yang dikirim halaman yang meng-embed. Menyimpan di sini tidak mengubah Welcome Message itu sendiri.
| |
|---|
| Custom text | Teks dari situs ditampilkan persis seperti yang dikirim (data-intro-message). |
| Custom prompt | Agent menjawab prompt dari situs dengan persona, tools, dan knowledge-nya. Pengunjung melihat jawabannya, tidak pernah prompt-nya (data-intro-prompt). |
| Prompt without system prompt | Diberi tanda Needs guardrail. Untuk mengubah data milik situs menjadi kalimat pembuka, misalnya ringkasan pesanan. Persona dan guardrail agent tidak berlaku (data-intro-raw-prompt). |
| Guardrail for this route | Muncul saat Prompt without system prompt menyala, dan wajib diisi. Tulis untuk apa route ini dan minta ia menolak permintaan lain. Menyimpan tanpa guardrail memunculkan "Add a guardrail, or turn this route off". Guardrail kosong berarti route itu mati. |
| Status Chip | Menunjukkan keadaan yang tersimpan: Welcome Message only, 1 route open / 2 routes open / 3 routes open, dengan tambahan · incl. no system prompt bila switch ketiga menyala. |
| Save | Menyimpan switch ke agent. Setelah itu, publish agent: situs live memakai agent yang sudah dipublish, jadi route baru berlaku setelah Publish. |
| Write and test an opening in the builder | Membuka builder di tab browser baru. Bila ada perubahan yang belum disimpan, CMS bertanya dulu, karena builder memakai route yang sudah disimpan. |
Sending an Opening Line From Host Code
| |
|---|
| Read Once at Start | Atribut kalimat pembuka dibaca saat chat terhubung. Menyetelnya pada elemen yang sudah berjalan tidak berpengaruh apa pun, dan tidak memunculkan error. |
| Server-Rendered | Menuliskan atribut langsung ke markup yang dikirim server adalah pola yang tidak punya isu waktu sama sekali. |
| Built in JavaScript | Untuk data yang diambil di browser: buat elemennya, set semua atributnya, baru tambahkan ke halaman. |
| Restarting | Untuk membuka percakapan baru dengan kalimat pembuka berbeda, ganti elemennya alih-alih mengubah atributnya. Di React, key yang berubah melakukan hal itu. |
Embed Builder
| |
|---|
| Reached From | Open builder di kartu Build your embed, atau Write and test an opening in the builder di kartu Opening lines from websites. |
| Own Browser Tab | Terbuka di /widget/builder pada tab tersendiri, tanpa sidebar CMS maupun panel preview agent, sehingga layar hanya berisi satu percakapan. |
| Header | Panah Back to Embed, judul "Embed builder" beserta nama agent, breadcrumb Channels › Embed › Builder, More actions, Download, dan Start (Restart setelah preview berjalan). |
| More Actions | Copy settings link (membuka builder dengan setelan ini) dan Reset settings (mengembalikan semua field ke default). Di ponsel, menu ini juga berisi Download HTML page dan Download React component. |
| Download | HTML page menyimpan qlar-embed.html, yang bisa dibuka di browser apa pun. React component menyimpan QlarChat.tsx, untuk ditambahkan ke aplikasi React. Keduanya memakai id agent yang sudah dipublish. |
| Generated Code | Hanya memuat yang berbeda dari default. Atribut yang tidak berlaku pada layout terpilih tidak ditulis. |
| Changed Fields | Titik pada tab setelan menandakan tab itu berisi perubahan. Switch Show attribute names di bagian bawah menampilkan nama data-* di samping setiap field. |
Settings Tabs
| |
|---|
| Layout | How the chat sits on the page: Inline ("Fills the box you place it in.") atau Floating ("A button in a corner opens a chat panel."). Floating menambahkan Position (Corner, Horizontal, Vertical) dan Panel size (Width, Height). Inline menambahkan Size → Height: tinggi kotak di halaman hasil generate, bukan atribut. 100% membuat chat memenuhi seluruh halaman. |
| Look | Berjudul Appearance. Theme (System, Light, Dark), What the chat shows (Full app atau Chat only; Chat only juga mematikan top bar), Show the agent logo above the greeting. Floating menambahkan Show the panel header, Panel title (kosong berarti "Chat"), dan Panel header colors (Light bar, Light text, Dark bar, Dark text), lengkap dengan preview header. |
| Top bar | Show the top bar, lalu Conversation list (menu), New chat button, Light/dark toggle, serta Sign-in button and account menu. Saat bar mati, item-itemnya tampil abu-abu, tidak disembunyikan. |
| Intro | Berjudul Introduction. Show example messages under the greeting, lalu What your site sends: Nothing, Introduction text, Introduction prompt, atau Introduction prompt, no system prompt. Fill in a sample mengisi teks contoh. Route yang tidak diizinkan agent tampil abu-abu, dengan Check again untuk membaca ulang switch yang tersimpan. Peringatan muncul bila route ketiga menyala tetapi belum ada guardrail yang tersimpan. Dua route berbasis prompt memakan satu panggilan model. |
| Behavior | Focus the chat input on load, dan Resume window for anonymous visitors: 30 min, 1 hour, 6 hours · default, 1 day, 7 days, atau Custom… dalam minutes, hours, atau days. |
Presets
Kotak Preset ada di bagian atas tab Layout. Change membuka daftarnya. Preset hanya mengatur hal yang menjadi fokusnya dan mengembalikan field lain ke default. Setelah diedit, preset menampilkan Modified. Menerapkan preset, atau Reset settings, menawarkan Undo selama 6 detik.
| |
|---|
| Full app | "A chat page of its own". Memenuhi seluruh halaman. |
| Page section | "Part of an existing page". Chat only, tanpa top bar, tanpa contoh pesan. |
| Support bubble | "A launcher on every page". Floating, chat only, tanpa top bar, tanpa logo, judul panel "Need help?". |
Preview
| |
|---|
| Draft Chip | Preview menjalankan agent draft: simpanan terakhir yang belum dipublish. Kode dan file unduhan memakai agent yang sudah dipublish. |
| Anonymous Chip | Preview chat sebagai pengunjung yang belum sign-in. |
| Width | Desktop (lebar penuh), Tablet (768px), atau Phone (390px, tempat panel floating memenuhi layar). Tidak tampil di ponsel. |
| Live update | Membangun ulang preview sesaat setelah Anda berhenti mengubah setelan (Live di ponsel). Setiap rebuild memulai chat baru, dan dengan introduction prompt, setiap rebuild memakan satu panggilan model. Bila dimatikan, setelan yang berubah memunculkan "Settings changed. Restart to see them." ("Settings changed" di header pada ponsel) sampai Anda menekan Restart. |
| Code | Show code / Hide code membuka drawer di bawah preview. Tampilannya: Element, HTML page, React. |
Settings Link
Copy settings link menaruh field yang berubah di hash URL (#settings=). Membuka tautan itu akan membuka builder dengan setelan yang sama. Nilai yang tidak cocok dengan field-nya dibuang saat tautan dibaca.
On Phones
Di bawah lebar 1200px, halaman yang berjalan memenuhi layar. Bottom navigation bar berisi satu entri per tab setelan ditambah Code, dan masing-masing membuka sheet di atas halaman. Sheet terbuka setengah tinggi layar, berpindah ke tinggi penuh lewat tombolnya atau swipe ke atas, dan tertutup lewat swipe ke bawah atau Close. Halaman tetap termuat, jadi membuka sheet tidak memutus percakapan yang sedang berjalan.