SDK JavaScript

Paket npm adalah cara yang direkomendasikan untuk mengintegrasikan ChattyBox. Impor satu klien ke aplikasi Anda, konfigurasikan kunci publik dan URL API, lalu pasang antarmuka terkelola di tempat yang diperlukan aplikasi Anda atau gunakan metode headless dengan komponen Anda 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();

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

Panggil mountWidget() dalam kode browser dari komponen atau layout tempat antarmuka terkelola harus tersedia. Anda dapat meneruskan { locale: 'fr' } untuk locale khusus rute.

Dapatkan Konfigurasi Publik Anda

1. Buat proyek dan indeks konten Anda.
2. Uji pertanyaan representatif di dasbor.
3. Buka Public Keys, buat kunci browser, dan batasi origin yang diizinkan.
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. Batasi kunci browser ke domain yang diizinkan memanggil chatbot Anda. Paket ini adalah klien ESM untuk aplikasi Node.js terkini dan browser yang menyediakan fetch.

Pasang Widget Ter-host dari Kode

Gunakan ini jika Anda menginginkan antarmuka ChattyBox yang dikelola sambil mengontrol tempat pemasangannya 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();

// Optional cleanup for a component lifecycle:
widget.remove();

Widget memuat UI terkelola satu kali dan tidak tersedia selama rendering server.

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	Jawaban yang dihasilkan.
conversationId	string	Pengenal yang digunakan untuk melanjutkan percakapan ini.
sources	string[]	URL sumber yang diambil untuk jawaban.

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.

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);
  }
}

ChattyboxError.status berisi status HTTP. code tersedia saat API mengembalikan kode error terstruktur.

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.

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, jawaban fallback, sitasi, dan perilaku seluler dengan daftar periksa peluncuran.