Lewati ke konten utama

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. SDK 0.1.4 yang dipublikasikan belum mendukung uiLocale; perilaku uiLocale di bawah ini hanya berlaku pada SDK dan backend dalam kode sumber saat ini. :::

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.

Perbaikan lifecycle dan deklarasi NodeNext yang ketat tersedia dalam SDK npm 0.1.4. Pembersihan widget secara penuh juga memerlukan widget.js terkelola yang diperbarui; instalasi yang di-host sendiri harus memperbarui file tersebut secara terpisah.

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' } meminta bahasa Prancis saat widget diinisialisasi, jika proyek mengizinkan override locale skrip.

Nama import.meta.env.PUBLIC_* dalam contoh hanya ilustrasi. Gunakan konvensi konfigurasi publik framework Anda, seperti import.meta.env.VITE_* pada Vite atau process.env.NEXT_PUBLIC_* pada Next.js. Pada Node.js, baca dan validasi nilai process.env.

Dapatkan Konfigurasi Publik Anda​

  1. Buat proyek dan indeks konten Anda.
  2. Uji pertanyaan representatif di Uji chatbot.
  3. Di Pasang → Kunci & domain, periksa atau buat kunci browser publik dan periksa pengaturan origin-nya. Kunci tanpa pembatasan berfungsi di berbagai origin; kunci yang disiapkan untuk situs web mungkin sudah dibatasi.
  4. Di Pasang → Instalasi situs web, masukkan URL situs web HTTP(S), pilih kunci yang sesuai, dan salin URL API widget dari cuplikan. Pemilih menawarkan kunci yang belum kedaluwarsa dan tidak dibatasi atau diizinkan untuk origin URL tersebut. Masukkan origin yang diizinkan untuk memilih kunci yang dibatasi dan periksa pembatasannya melalui Kelola kunci & domain yang diizinkan. Jika formulir tidak tersedia, selesaikan dahulu langkah penyiapan yang ditampilkan di dasbor.

Kunci API widget publik dirancang untuk muncul dalam kode browser. Kunci ini mengidentifikasi proyek, tetapi bukan kredensial pengelolaan. Untuk hardening opsional, aktifkan pembatasan di Pasang → Kunci & domain → Edit origin 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 dan tidak dapat mencegah klien non-browser memalsukan header.

Konstruktor dan Ekspor​

new Chattybox(options) menerima apiKey dan baseUrl berupa string yang wajib dan tidak kosong, serta implementasi fetch opsional; jika tidak diberikan, SDK menggunakan fetch global. SDK 0.1.4 mensyaratkan baseUrl berupa URL HTTP(S) absolut tanpa kredensial, query string, atau fragmen. Salin URL API widget dari cuplikan instalasi situs web, bukan URL dasbor atau URL klien Convex .cloud. SDK menghapus garis miring di akhir, lalu sufiks /chat; properti apiKey dan baseUrl yang telah dinormalisasi bersifat readonly.

Konstruktor melempar Error biasa jika opsi hilang atau bukan objek, apiKey atau baseUrl hilang, bukan string, atau kosong, fetch yang diberikan bukan fungsi, atau baseUrl tidak memenuhi persyaratan URL tersebut. Paket mengekspor Chattybox, ChattyboxError, dan tipe ChattyboxOptions, SendMessageInput, ChatResponse, WidgetConfig, WidgetTranslations, HostedWidgetOptions, serta HostedWidgetHandle. Paket tidak memiliki komponen atau hook React. Bundle IIFE ./browser mengekspos kedua konstruktor pada window.ChattyboxSDK; memuat bundle saja tidak memasang UI.

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 memberi sinyal teardown. Dengan widget.js v15 ter-host, sinyal itu membatalkan inisialisasi, percobaan ulang, serta chat berjalan, lalu menghapus UI, gaya, tautan font, dan API global; SDK menghapus skrip. Kunci, URL API, scriptUrl, locale, atau opsi debug yang berbeda ditolak selama masih ada handle. Dengan widget.js v15, window.ChattyBox.destroy() melakukan teardown widget. Pertahankan loader di shell persisten selama navigasi sisi klien.

SDK npm 0.1.4 yang dipublikasikan hanya menggunakan kembali skrip bertanda script[data-chattybox-widget="true"] yang dikelolanya jika seluruh konfigurasi mount identik (kunci publik, URL API, scriptUrl, locale, dan opsi debug); konfigurasi yang berbeda ditolak, bukan diam-diam menggunakan skrip yang sudah ada. 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.

Gunakan scriptUrl alternatif hanya untuk loader pratinjau atau self-hosted yang tepercaya. SDK tidak mendeteksi loader manual tanpa penanda. fetch kustom pada konstruktor hanya digunakan oleh metode headless, tidak diteruskan ke widget ter-host. Teardown tidak dapat membatalkan permintaan yang sudah diproses server.

Widget ter-host v15 mencoba ulang kegagalan transport, body respons sukses yang terputus, respons yang masih diproses dengan Retry-After yang dapat dibaca, pembatasan laju, dan error server dengan body serta kunci idempotensi yang sama. Maksimal 10 percobaan dan tidak ada retry otomatis yang dijadwalkan melewati 30 detik; waktu tunggu Retry-After yang dapat dibaca termasuk dalam batas ini. Setelah habis, tombol untuk mencoba ulang pesan menggunakan kembali permintaan logis tersebut; pertanyaan baru memulai permintaan baru. JSON atau bentuk respons yang tidak valid pada respons sukses adalah error protokol terminal, bukan retry otomatis. Respons API lintas origin harus mengekspos Retry-After melalui Access-Control-Expose-Headers.

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 Instalasi situs web. SDK menerima root deployment maupun URL yang diakhiri /chat.

Respons berisi:

BidangTipeDeskripsi
messagestringTeks jawaban atau fallback yang dikonfigurasi; render aman sebagai teks atau Markdown disanitasi, bukan HTML mentah.
conversationIdstringPengenal yang digunakan untuk melanjutkan percakapan ini.
sourcesstring[]URL sumber jawaban; dapat kosong pada fallback. Validasi URL HTTP(S) sebelum merender tautan.
providerErrorstring (opsional, kode sumber saat ini)Kode kegagalan provider yang terstruktur. Tidak ada pada jawaban biasa maupun fallback yang dikonfigurasi; perlakukan kode yang tidak dikenal sebagai kegagalan umum.
productFallback'no_context_ui' | 'no_context_question' (opsional, kode sumber saat ini)Menandai teks fallback tanpa konteks milik produk dan cara bahasanya dipilih; lihat di bawah.

sendMessage(input) mengembalikan Promise<ChatResponse>. SendMessageInput menerima message: string, conversationId: string | null opsional, dan idempotencyKey: string opsional. SDK dalam kode sumber saat ini juga menerima uiLocale: string opsional; opsi ini tidak tersedia di SDK 0.1.4 yang dipublikasikan. SDK dalam kode sumber saat ini meneruskan locale yang diberikan tanpa mengubahnya dan menghilangkannya jika tidak ada atau bernilai undefined; SDK tidak mendeteksi locale secara otomatis. Server memvalidasi locale lalu menormalkannya ke bahasa dasar yang didukung. Locale dengan format tidak valid atau yang tidak didukung menghasilkan HTTP 400 Invalid uiLocale, bukan diam-diam dialihkan ke bahasa fallback. Contoh: chattybox.sendMessage({ message: 'Help', uiLocale: 'fr-CA' }). Locale adalah konteks presentasi, bukan kontrol autentikasi atau otorisasi.

Untuk pesan fallback milik produk, sinyal bahasa pertanyaan yang dikenali lebih diutamakan daripada uiLocale. Jika deteksi tidak meyakinkan atau hanya mengandalkan heuristik bahasa Inggris ASCII, locale UI dapat menentukan bahasa fallback tersebut. Jika keduanya tidak tersedia, default produk yang digunakan. Pesan fallback yang ditulis oleh pemilik proyek digunakan apa adanya; uiLocale tidak menerjemahkan teks fallback tersebut atau mengubah keluaran AI, dan tidak menjamin bahasa maupun kualitas jawaban.

Widget/chat API dalam kode sumber saat ini menambahkan productFallback hanya pada respons tanpa konteks milik produk; ketersediaannya bergantung pada versi backend, bukan versi SDK. no_context_ui berarti bahasa pesan fallback dipilih dari locale UI/default atau tidak dapat ditentukan; UI khusus dapat menyesuaikan lokalisasinya dengan entri katalog message.noContext yang sedang berlaku. no_context_question berarti pengklasifikasi yang ada mengenali bahasa pertanyaan; pertahankan teks pesan yang dikembalikan. Ini tidak membuktikan bahwa bahasanya teridentifikasi dengan benar. Marker tidak ada pada fallback khusus yang ditulis oleh pemilik proyek, jawaban biasa, kegagalan provider, dan respons lama. Jangan pernah menyimpulkan asal pesan berdasarkan kesamaan teks atau ketiadaan marker; abaikan string marker masa depan yang tidak dikenal.

SDK 0.1.4 yang dipublikasikan tidak mendeklarasikan productFallback dalam ChatResponse, tetapi meneruskan field itu dalam objek JSON yang dikembalikan jika backend menyediakannya. Persempit nilainya dengan pemeriksaan yang aman sebelum digunakan. Tidak ada field umum wasAnswered atau status fallback, jadi jangan mengarang hasil terstruktur untuk jawaban yang tidak didukung.

SDK mengirim kunci API publik dalam body JSON, tetapi tidak mengirim konteks halaman (sourceUrl atau sourcePath) maupun opsi model. Validasi pesan tidak kosong dan maksimum 2.000 karakter setelah trim sebelum dikirim; backend menerapkan batas ini, tetapi kegagalan validasi internal saat ini muncul sebagai error HTTP 500 umum. sendMessage() headless tidak menyediakan streaming, retry otomatis, timeout, opsi AbortSignal, penyimpanan, atau state UI; implementasi fetch kustom dapat menyediakan kebijakan transport. Pernyataan tanpa retry ini berlaku untuk chat headless: SDK 0.1.4 yang dipublikasikan hanya mencoba ulang getWidgetConfig() sekali setelah HTTP 400, sedangkan v15 ter-host mencoba ulang GET saat startup. Respons publik tidak memiliki bidang wasAnswered atau status fallback yang 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; dengan menggunakan kembali conversationId yang sama, model menerima hingga 12 pesan terbaru yang tersimpan, masing-masing dipotong hingga 2.000 karakter. Ini konteks terbatas, bukan seluruh transkrip atau memori permanen; ulangi detail lama bila diperlukan.

Keamanan Retry​

const input = {
message: 'Where is the API reference?',
idempotencyKey: crypto.randomUUID(),
};
const result = await chattybox.sendMessage(input);
// If the response is lost, retry the same input, including its original conversationId.

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. Pada replay idempoten, respons dan marker asli yang tersimpan (jika ada) dikembalikan persis tanpa menjalankan ulang permintaan. Server saat ini menyertakan locale yang telah dinormalisasi dalam fingerprint request. Untuk retry, kirim input persis yang sama dengan conversationId dan uiLocale semula, termasuk jika field uiLocale tidak disertakan; jangan membuat kunci baru setelah kegagalan transport yang hasilnya tidak pasti.

SDK mengirim kunci sebagai header Idempotency-Key. Kunci berlaku dalam cakupan proyek, panjangnya 1–128 karakter, dan harus cocok dengan [A-Za-z0-9][A-Za-z0-9._:-]*. Replay tidak permanen: catatan selesai dan gagal kedaluwarsa 24 jam setelah reservasi, sedangkan catatan tertunda tidak diklaim ulang hanya berdasarkan waktu. Retry setelah catatan terminal kedaluwarsa dapat menjalankan permintaan lagi. Batasi rentang retry dan selidiki konflik yang terus berulang.

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; sebagian besar error API widget saat ini tidak memilikinya. Respons non-2xx, error berupa string tidak kosong meskipun HTTP 200, JSON tidak valid, dan JSON yang bukan objek menghasilkan ChattyboxError. Kegagalan jaringan/fetch diteruskan tanpa pembungkus. SDK 0.1.4 juga membungkus body respons yang tidak terbaca sebagai ChattyboxError dengan RESPONSE_BODY_READ_FAILED. Respons sukses dicast ke tipe yang dideklarasikan tanpa validasi runtime per bidang.

Hasil HTTP yang umum mencakup 400 untuk input atau locale terjemahan yang tidak valid, 401 untuk kegagalan kunci/origin, 403 untuk widget proyek yang dinonaktifkan (termasuk chat headless), 409 untuk konflik idempotensi, 413 untuk body chat lebih dari 65.536 byte, 429 untuk pembatasan laju, dan 500 untuk kegagalan internal. SDK tidak mengekspos header respons pada hasil maupun error.

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'),
]);

Tipe SDK dalam kode sumber saat ini mendeklarasikan properti opsional headerTitleIsDefault?: boolean dan welcomeMessageIsDefault?: boolean pada WidgetConfig. Masing-masing flag menjelaskan teks yang bersesuaian: true berarti teks default produk yang telah dilokalkan, sedangkan false berarti teks kustom yang harus dipertahankan. Jika flag tidak ada, termasuk pada respons lama, asal teks tidak diketahui; jangan pernah menyimpulkan asalnya dengan membandingkan teks dengan teks default. Ketersediaannya bergantung pada versi backend, bukan versi SDK. SDK 0.1.4 yang dipublikasikan tidak mendeklarasikan flag tersebut sebagai boolean, tetapi tipe Record<string, unknown> dan respons JSON yang diteruskan tanpa perubahan memungkinkan konsumen mempersempit tipe nilainya dengan aman saat flag disertakan. Respons sukses tidak divalidasi atau dikonversi per bidang.

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; klien headless dalam kode sumber saat ini dapat mengirim uiLocale secara terpisah untuk memilih bahasa fallback milik produk. Keduanya tidak mengubah keluaran AI atau menjamin kualitasnya.

getWidgetConfig() mengembalikan Promise<WidgetConfig> dan mengautentikasi dengan Authorization: Bearer. SDK 0.1.4 mencoba ulang tepat sekali dengan kunci yang dikodekan dalam query string hanya setelah HTTP 400, untuk perantara yang menghapus header; status lain tidak dicoba ulang. WidgetConfig adalah Record<string, unknown> dengan properti opsional bertipe untuk status aktif, warna, posisi, judul dan pesan sambutan, branding, ikon, dan pengaturan locale (localeMode: 'auto' | 'fixed', defaultLocale: string, dan allowLocaleOverride: boolean). Periksa tipe field lain yang belum diketahui sebelum digunakan. Lihat field dan default server saat ini di Kustomisasi widget ter-host. Permintaan konfigurasi yang berhasil juga menandai proyek sebagai widget terpasang, meskipun klien khusus tidak pernah merender widget.

getWidgetTranslations(locale) mengembalikan Promise<WidgetTranslations> dengan translations: Record<string, string>, dir: 'ltr' | 'rtl', dan locale: string yang dipilih server. Endpoint ini publik dan tidak menggunakan kunci API atau pengaturan locale proyek. Gunakan salah satu dari en, fr, de, pl, es, it, nl, pt, sv, id, et, fi, cy, atau cs. SDK mengodekan locale untuk URL tetapi tidak menormalkannya: fr-CA dan FR menghasilkan 400, berbeda dari normalisasi locale regional widget ter-host. String kosong memilih bahasa Inggris pada server. Semua katalog saat ini menggunakan arah kiri-ke-kanan dan dapat di-cache selama satu jam.

Untuk UI khusus yang mereproduksi perilaku widget ter-host, tentukan locale sendiri, patuhi allowLocaleOverride serta pengaturan Fixed/Auto proyek, dan sediakan fallback untuk kunci terjemahan yang hilang. Pengaturan ini tidak menjamin bahasa jawaban yang dihasilkan AI.

Langkah Berikutnya​