SDK JavaScript

:::note Status versi SDK npm 0.1.4 yang dipublikasikan memvalidasi baseUrl, membungkus badan respons yang tidak terbaca, dan hanya mencoba ulang config HTTP 400 sekali. Dengan widget.js v15, remove()/window.ChattyBox.destroy() mendukung teardown; sendMessage() headless tidak mencoba ulang otomatis. :::

Paket npm adalah cara yang direkomendasikan untuk mengintegrasikan ChattyBox dari kode aplikasi. Konfigurasikan kunci publik dan URL API, lalu muat widget mengambang terkelola dari layout browser yang persisten atau gunakan metode headless dengan komponen sendiri.

Mulai Cepat

bun add @openstaticfish/chattybox

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Pertahankan loader sepanjang masa hidup halaman, termasuk navigasi SPA.

Panggil mountWidget() setelah document.body tersedia, bukan saat rendering atau eksekusi server. Ini menambahkan widget mengambang di bawah document.body; { locale: 'fr' } hanya meminta bahasa saat inisialisasi bila proyek mengizinkan script override.

Dapatkan Konfigurasi Publik Anda

1. Buat proyek dan indeks konten Anda.
2. Uji pertanyaan representatif di dasbor.
3. Buka Public Keys dan buat kunci browser. Secara default kunci ini bekerja dari origin production, preview, staging, dan localhost.
4. Buka Embed, pilih kunci tersebut, dan salin URL API widget yang ditampilkan bersama cuplikan yang dibuat.

Kunci API widget publik dirancang untuk muncul dalam kode browser. Kunci ini mengidentifikasi proyek, tetapi bukan kredensial pengelolaan. Untuk hardening opsional, aktifkan pembatasan di Public Keys > Edit origins dan daftar origin browser yang tepat. Paket ini adalah klien ESM untuk aplikasi Node.js terkini dan browser yang menyediakan fetch.

Pembatasan mencocokkan skema, hostname, dan port yang dinormalisasi, bukan path atau wildcard subdomain. API memakai Origin request, lalu fallback ke origin Referer. Origin yang tidak ada atau tidak diizinkan pada kunci terbatas mengembalikan 401 Invalid API key; fetch Node.js tidak otomatis mengirim header tersebut. Pembatasan origin bukan autentikasi.

Pasang Widget Ter-host dari Kode

Gunakan ini untuk menginisialisasi antarmuka mengambang terkelola ChattyBox dari kode aplikasi:

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget({ locale: 'fr', debug: false });

mountWidget(options?) mengembalikan HostedWidgetHandle secara sinkron, sebelum skrip dimuat atau UI siap. scriptUrl defaultnya https://chattybox.ai/widget.js; locale menetapkan data-locale jika tidak kosong dan proyek mengizinkannya; debug menetapkan data-debug="true" hanya saat truthy. handle.element adalah HTMLScriptElement yang disuntikkan atau digunakan ulang.

mountWidget() mengembalikan handle sebelum skrip atau UI siap. Dalam SDK 0.1.4 yang dipublikasikan, mount identik berbagi skrip dan setiap handle memiliki referensi: remove() idempoten dan hanya handle terakhir yang membatalkan inisialisasi, percobaan ulang, serta chat berjalan, lalu menghapus UI, gaya, tautan font, skrip, dan API global. Kunci, URL API, scriptUrl, locale, atau opsi debug yang berbeda ditolak selama masih ada handle. Dengan widget.js v15, window.ChattyBox.destroy() melakukan teardown yang sama. Pertahankan loader di shell persisten selama navigasi sisi klien.

SDK menggunakan kembali skrip script[data-chattybox-widget="true"] pertama tanpa memperbarui kunci, URL API, atau opsinya. Jangan gabungkan pemasangan SDK dengan plugin, tag GTM, atau skrip terpisah. Tidak ada promise ready SDK, target container, atau API pembaruan locale reaktif; gunakan remove() untuk teardown SDK atau window.ChattyBox.destroy() untuk widget ter-host.

Bangun UI Anda Sendiri

Gunakan metode headless di bawah ini jika aplikasi Anda memiliki daftar pesan, input, state pemuatan dan error, sitasi, serta aksesibilitas sendiri.

Kirim Pesan

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const answer = await chattybox.sendMessage({
  message: 'How do I get started?',
});

console.log(answer.message);
console.log(answer.sources);

Atur PUBLIC_CHATTYBOX_API_URL ke URL API widget yang persis dari tab Embed. SDK menerima root deployment maupun URL yang diakhiri /chat.

Respons berisi:

Bidang	Tipe	Deskripsi
message	string	Teks jawaban atau fallback yang dikonfigurasi; render aman sebagai teks atau Markdown disanitasi, bukan HTML mentah.
conversationId	string	Pengenal yang digunakan untuk melanjutkan percakapan ini.
sources	string[]	URL sumber jawaban; dapat kosong pada fallback. Validasi URL HTTP(S) sebelum merender tautan.

sendMessage(input) hanya menerima message, conversationId opsional, dan idempotencyKey opsional. SDK tidak mengirim konteks halaman (sourceUrl atau sourcePath), locale, maupun opsi model. Validasi pesan tidak kosong dan maksimum 2.000 karakter setelah trim sebelum dikirim. SDK tidak menyediakan streaming, retry otomatis, timeout, AbortSignal, penyimpanan, atau state UI; tidak ada bidang status jawaban/fallback terpisah.

Lanjutkan Percakapan

Simpan ID percakapan yang dikembalikan dalam state UI Anda dan kirimkan bersama pesan berikutnya:

const followUp = await chattybox.sendMessage({
  message: 'Can you explain the second step?',
  conversationId: answer.conversationId,
});

Jangan gunakan kembali satu ID percakapan untuk pengunjung yang tidak berkaitan. Buat percakapan baru dengan tidak menyertakan conversationId pada pesan pertama mereka.

Mengirim null juga memulai percakapan baru. ID mengelompokkan pesan tersimpan dalam proyek, tetapi jalur pembuatan publik saat ini tidak meneruskan giliran sebelumnya ke model. Buat follow-up mandiri, jangan mengasumsikan model mengingat jawaban sebelumnya.

Keamanan Retry

Gunakan idempotencyKey unik untuk tiap pesan logis dan simpan input yang sama untuk retry. SDK tidak membuat kunci atau melakukan retry untuk Anda. Jangan membuta melakukan retry atas setiap 409; request yang sedang berjalan, input yang berubah, atau kegagalan terminal dapat mengembalikan konflik.

Tangani Error

import { Chattybox, ChattyboxError } from '@openstaticfish/chattybox';

try {
  await chattybox.sendMessage({ message: 'Where is the API reference?' });
} catch (error) {
  if (error instanceof ChattyboxError) {
    console.error(error.status, error.code, error.message);
  } else {
    console.error(error);
  }
}

ChattyboxError.status berisi status HTTP. code hanya ada saat API mengembalikan code string. Kegagalan jaringan/fetch diteruskan tanpa pembungkus. Respons sukses dicast ke tipe yang dideklarasikan tanpa validasi runtime per bidang.

Gunakan Kembali Pengaturan Proyek dan Terjemahan

SDK juga menyediakan getWidgetConfig() dan getWidgetTranslations(locale). Metode ini mendukung klien yang ingin mereproduksi pengaturan proyek dan label terlokalisasi dari widget ter-host:

const [config, labels] = await Promise.all([
  chattybox.getWidgetConfig(),
  chattybox.getWidgetTranslations('en'),
]);

UI yang sepenuhnya khusus dapat mengabaikannya. Simpan conversationId setiap pengunjung dalam browser atau state sesi pengunjung tersebut; jangan pernah membagikan satu ID percakapan global. Locale mengubah label UI, bukan bahasa request chat atau jaminan kualitas respons.

Langkah Berikutnya

• Lebih memilih UI terkelola tanpa build? Instal widget.js.
• Sesuaikan UI ter-host di Kustomisasi widget ter-host.
• Sebelum peluncuran, uji pembatasan origin bila Anda mengaktifkannya, jawaban fallback, sitasi, dan perilaku seluler dengan daftar periksa peluncuran.