Lewati ke konten utama

Pemecahan masalah

Gunakan halaman ini ketika widget dipasang tetapi tidak berfungsi seperti yang diharapkan.

Widget Tidak Muncul​

Periksa konsol browser terlebih dahulu. ChattyBox melaporkan di sana jika atribut yang diperlukan tidak ada.

Penyebab umum:

  • Skrip tidak ada baik di HTML yang di-deploy maupun DOM langsung.
  • Skrip ditambahkan ke template, tata letak, wadah pengelola tag, atau area kode CMS yang salah.
  • Skrip berada di balik aturan persetujuan atau pemicu pengelola tag yang tidak terpicu.
  • Komponen aplikasi yang memasang loader tidak pernah berjalan pada rute tersebut.
  • Kebijakan Keamanan Konten memblokir https://chattybox.ai/widget.js.
  • CSS atau widget lain tumpang tindih dengan peluncur.
  • Konfigurasi yang di-deploy memiliki widget.enabled: false.

Perbaikan terkecil:

  1. Buka halaman publik yang diterapkan di jendela penyamaran.
  2. Cari chattybox.ai/widget.js di sumber halaman dan panel Elements browser; loader yang disuntikkan SDK atau JavaScript mungkin hanya ada di DOM langsung.
  3. Konfirmasikan skrip muncul satu kali dan menyertakan data-api-key dan data-api-url.
  4. Pindahkan skrip ke footer global, tata letak aplikasi, root Docusaurus, atau pemicu GTM Semua Halaman jika tidak ada.

Untuk proyek yang dikelola melalui konfigurasi, widget.enabled: false mencegah widget ter-host diinisialisasi dan membuat request publik POST /chat mengembalikan 403 Widget is disabled, termasuk request SDK headless. Ubah pengaturan itu melalui alur deployment konfigurasi, bukan dengan merotasi kunci publik. Menghapus skrip loader setelah inisialisasi tidak menghapus widget yang sudah dirender.

Hilang data-api-url​

Widget keluar lebih awal ketika data-api-url hilang.

Gunakan cuplikan lengkap dari dasbor atau tambahkan atribut yang diperlukan:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Gunakan URL API dari dasbor, jangan menebaknya. Di production, URL tersebut diharapkan berupa URL https://...convex.site/chat yang stabil.

401 Invalid API key Generik​

Untuk keamanan, endpoint API widget mengembalikan respons generik 401 Invalid API key yang sama untuk kunci publik yang tidak dikenal, kedaluwarsa, atau ditolak karena origin. Jangan gunakan respons ini untuk menentukan penyebabnya.

Penyebab umum:

  • Kunci widget publik salah disalin.
  • Kunci dihapus, kedaluwarsa, atau disalin dari deployment backend yang berbeda dari URL API.
  • Proyek atau pemilik kunci sedang dihapus.
  • Pembatasan origin opsional diaktifkan dan origin situs saat ini tidak tercantum.

Perbaikan:

  1. Buka proyek di dasbor ChattyBox.
  2. Buka Pasang → Instalasi situs web, masukkan URL situs web, lalu salin cuplikan yang memenuhi syarat jika tersedia.
  3. Di Kunci & domain pada halaman yang sama, gunakan Edit origin untuk kunci dalam cuplikan yang dipasang. Jika Batasi kunci ini ke origin tertentu diaktifkan, tambahkan origin persis yang menyajikan halaman atau nonaktifkan pembatasan opsional. Skema, hostname, dan port harus cocok: https://example.com, https://preview.example.com, dan http://localhost:3000 adalah origin yang berbeda. Path tidak memerlukan entri terpisah.
  4. Terapkan ulang atau terbitkan ulang situs dan uji lagi di jendela penyamaran.

Kunci valid untuk chatbot lain pada backend yang sama biasanya memilih chatbot tersebut alih-alih menghasilkan 401; periksa proyek jika jawaban tidak terkait. Nama kunci seperti "production" dan "staging" tidak menegakkan environment. API HTTP menggunakan header Origin jika ada; hanya jika header itu tidak ada, API memakai origin dari Referer. Kunci yang dibatasi menolak request jika origin yang dipilih tidak ada, tidak valid, atau tidak diizinkan. Origin Referer yang diizinkan tidak dapat mengesampingkan Origin yang tidak diizinkan. Pembatasan origin bukan pengganti autentikasi pengunjung.

Batas Pesan atau Batas Laju​

Periksa Akun & Tagihan di /settings/account untuk penggunaan pesan, paket, dan anggaran PAYG opsional Pro/Business. Test Chat dan chat publik memakai kuota pesan pemilik yang sama. Menghapus percakapan atau membuat kunci lain tidak mereset kuota tersebut.

Error kuota pesan bulanan berbeda dari batas laju request jangka pendek. Untuk respons HTTP 429, patuhi Retry-After jika tersedia, jangan terus-menerus mengirim ulang request. Untuk error batas pesan bulanan, tunggu kuota direset atau sesuaikan paket/anggaran PAYG yang memenuhi syarat. Percakapan → Riwayat berisi riwayat percakapan, bukan konsol error per request; gunakan panel Network browser untuk memeriksa kegagalan HTTP.

Bahasa yang Salah​

Periksa pengaturan bahasa widget terlebih dahulu di Sesuaikan → Tampilan. Widget ter-host sesuai kode sumber saat ini memilih bahasa UI dengan urutan berikut:

  1. data-locale pada skrip widget, hanya jika Allow script override diaktifkan dan nilainya didukung.
  2. Dalam mode Fixed, bahasa default yang dikonfigurasi.
  3. Dalam mode Auto-detect, <html lang> halaman, lalu kandidat bahasa browser, lalu default yang dikonfigurasi.

Kandidat yang tidak didukung akan dilewati. Jika tidak ada kandidat yang didukung, bahasa fallback terakhir adalah bahasa Inggris; bahasa default awalnya adalah bahasa Inggris.

Perbaikan:

  • Untuk pemilihan bahasa otomatis, pilih Auto-detect dan hapus nilai data-locale yang salah atau nonaktifkan override skrip.
  • Tetapkan <html lang="de">, <html lang="fr">, atau kode bahasa yang cocok pada halaman yang dilokalkan.
  • Untuk memaksa bahasa yang dikonfigurasi, pilih Fixed dan nonaktifkan Allow script override. Jika override aktif, data-locale tetap diprioritaskan bahkan dalam mode Fixed.
  • Pastikan pengaturan sudah tersimpan dan inisialisasi ulang widget terpasang agar perubahan pengaturan dashboard diterapkan. Widget ter-host widget.js v16 sesuai kode sumber saat ini dapat memperbarui label produk ketika perubahan pada <html lang> atau data-locale loader mengubah locale yang terpilih. Periksa versi loader yang di-deploy sebelum mengandalkan pembaruan langsung; perilaku loader ter-host ini berbeda dari versi npm SDK yang dipublikasikan, 0.1.4. locale yang diberikan ke mountWidget() menjadi data-locale dan mengikuti aturan proyek yang sama.
  • Jika widget tidak tersedia, periksa request /widget-config dan kunci publik. Pada hosted widget.js v16 sesuai kode sumber saat ini, kegagalan mengambil konfigurasi membuat widget tetap tidak tersedia, bukan memulainya dengan pengaturan default. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku ini.
  • Bahasa UI widget tidak memaksa bahasa jawaban dan tidak menerjemahkan konten sumber. Generator jawaban mendeteksi bahasa dari pertanyaan. Indeks setiap versi bahasa yang diperlukan jika jawaban mengambil konten dalam bahasa yang salah. Jika assistant.fallbackMessage khusus tidak dikonfigurasi melalui config-as-code, fallback bawaan untuk konten yang tidak ditemukan menggunakan bahasa pertanyaan yang terdeteksi jika sesuai; jika deteksi bahasa tidak pasti, fallback menggunakan locale widget. Bahasa Inggris hanya menjadi fallback terakhir.

Tidak Ada Kutipan atau Jawaban Lemah​

ChattyBox menggunakan konten sumber yang diambil untuk menghasilkan jawaban. Kutipan yang hilang atau jawaban yang lemah dapat disebabkan oleh konten sumber yang hilang atau tidak sesuai, masalah pengambilan, atau kegagalan generasi; hal itu sendiri tidak menunjukkan penyebabnya.

Chatbot RAG yang didasarkan pada sumber terbantu oleh konten sumber yang jelas, tetapi sitasi saja tidak memverifikasi jawaban. Bandingkan setiap klaim penting dengan halaman yang dikutip.

Perbaikan:

  • Ajukan pertanyaan yang sama di obrolan uji dasbor dan bandingkan halaman yang dikutip.
  • Pastikan halaman sumber bersifat publik dan disertakan dalam perayapan.
  • Tambahkan judul yang jelas, contoh, FAQ, dan teks jawaban langsung ke halaman sumber.
  • Hindari mengandalkan tangkapan layar, video, markup tersembunyi yang dikecualikan, konten khusus JavaScript, atau iframe sebagai satu-satunya sumber.
  • Kikis ulang halaman yang diperbarui ketika cooldown mengizinkan, tunggu tugas embedding, lalu uji lagi.
  • Periksa peringatan Partially indexed; teks setelah batas 512 KiB per halaman tidak dipertahankan. Pisahkan halaman sumber panjang.
  • Buat setiap pertanyaan jelas dan mandiri jika memungkinkan. Generator jawaban dapat menerima hingga 12 pesan terbaru yang tersimpan, masing-masing dibatasi 2.000 karakter; generator tidak menerima transkrip percakapan lengkap.

Persona menambahkan instruksi khusus situs ke aturan dasar bawaan; persona tidak dapat menyediakan konten terindeks yang hilang atau menggantikan fallback untuk konteks yang hilang atau kesenjangan konten ketika fallback tersebut terpicu. Detektor kesenjangan konten bersifat heuristik dan mungkin tidak menangkap setiap jawaban yang tidak didukung sumber. Fallback tersebut memiliki pengaturan assistant.fallbackMessage terpisah dalam konfigurasi sebagai kode.

Halaman Tidak Tergores atau Kontennya Basi​

Penyebab umum:

  • Halaman tersebut hilang dari peta situs yang dikirimkan.
  • Mode URL manual tidak menyertakan halaman.
  • Halaman memblokir fetch HTTP biasa, memerlukan autentikasi, mengembalikan CAPTCHA/error, atau dialihkan ke target yang diblokir.
  • Konten halaman berubah setelah scraping terakhir.
  • Konten hanya dirender JavaScript atau berada di luar root konten semantik yang dipilih.
  • URL terpilih melampaui kuota halaman, anggaran refresh bulanan habis, atau difilter aturan include/exclude.

Perbaikan:

  1. Konfirmasikan bahwa halaman dibuka secara publik di jendela browser pribadi.
  2. Gunakan mode peta situs untuk cakupan luas atau URL manual untuk kumpulan yang dikurasi.
  3. Kirimkan URL kanonik, bukan URL pelacakan, URL pengalihan, atau URL masuk.
  4. Scrape ulang setelah memublikasikan perubahan dan cooldown refresh: minimal tujuh hari sejak tugas terakhir dibuat di Free atau 24 jam di paket berbayar, termasuk jika tugas itu gagal.
  5. Di Pengetahuan → Halaman, perluas Riwayat impor jika ada tugas, lalu pilih tugas di bawah Job Scrape. Bandingkan jumlah halaman tersimpan/terpilih pada tugas dan daftar Halaman dengan URL yang dituju. Completed dapat mencakup URL yang dilewati atau gagal; Completed with warnings secara khusus menandai teks halaman yang tersimpan sebagian, bukan semua kegagalan crawl. UI tidak menyediakan daftar lengkap kegagalan per URL.

ChattyBox tidak menerapkan arahan crawl dari robots.txt, tetapi dapat membaca file tersebut untuk menemukan deklarasi sitemap. Jangan anggap robots.txt sebagai kontrol akses. ChattyBox mengikuti pengalihan HTTP yang aman, jadi pengalihan saja bukan kegagalan. Jangan hilangkan perlindungan akses atau membuat konten privat menjadi URL publik agar dapat di-crawl. Crawler tidak menjalankan JavaScript. Jika URL dihapus dari situs atau pilihan sumber, halaman tersimpannya dapat tetap dipakai; hapus juga dari Pengetahuan → Halaman dan kecualikan dari penemuan berikutnya. Bangun Ulang Indeks memakai teks tersimpan, bukan fetch jaringan baru. Tindakan ini memiliki cooldown tersendiri sesuai paket dan menggunakan anggaran refresh halaman bulanan bersama.

Pengaturan Tidak Tersimpan​

Perubahan pada detail chatbot dan pengaturan sumber disimpan otomatis. Periksa status penyimpanan dan atasi error validasi atau coba simpan lagi jika penyimpanan gagal. Dashboard memerlukan Website URL tersimpan bahkan saat Anda memasukkan Manual URLs. Penemuan dan penyimpanan otomatis tidak memulai impor; tinjau halaman yang dipilih lalu mulai impor secara eksplisit.

Jika proyek Config locked, konfigurasi harus di-deploy melalui alur CLI. Lock tidak dapat dibuka; penyimpanan Persona, konfigurasi scraping, Scrape Now, penghapusan konten, dan rebuild indeks ditolak meskipun kontrol masih terlihat. Hanya preferensi branding yang tetap dapat diedit di dashboard dalam konfigurasi widget ter-host, sesuai paket. Kunci widget publik dan token deployment adalah kredensial terpisah.

Jika proyek tidak ditemukan atau akses ditolak, pastikan Anda masuk sebagai pemiliknya. Kunci widget, token deployment, atau keanggotaan organisasi tidak memberikan izin kepemilikan dashboard. Dalam Percakapan, tampilan Analisis dan Pertanyaan yang belum terjawab tersedia pada Pro dan Business; tampilan yang tidak tersedia menampilkan ajakan untuk meningkatkan paket. Riwayat tersedia di semua paket.

Masih Terjebak​

Kumpulkan detail berikut sebelum menghubungi dukungan:

  • URL halaman publik tempat widget akan muncul.
  • Tangkapan layar atau salinan kesalahan konsol browser apa pun.
  • Apakah halaman menggunakan HTML biasa, Next.js, Docusaurus, WordPress, CMS, atau Google Tag Manager.
  • Apakah cuplikan menyertakan data-api-key dan data-api-url.
  • Satu pertanyaan tes yang seharusnya berfungsi dan halaman sumber yang menjawabnya.