Konfigurasi Widget

Baca dan perbarui konfigurasi widget situs web melalui API.

Pemeriksaan contoh opsional

Periksa cuplikan Widget. Periksa kode yang ditempel terhadap Scenario ID yang diberikan. Pemeriksaan ini tidak mengambil situs web Anda.

Di browser yang kompatibel, pemeriksaan ini juga tersedia sebagai tool situs. Tautannya membuka formulir standar.

Widget adalah antarmuka chat yang Anda sematkan di situs web. Widget muncul sebagai bubble mengambang di sudut halaman yang dapat diklik pengunjung untuk membuka percakapan dengan Agen AI Anda. Widget dapat disesuaikan sepenuhnya: Anda mengatur warna, ukuran, posisi, pesan sambutan, dan perilakunya.

Pengaturan ini juga memengaruhi embed, yaitu versi layar penuh atau inline dari antarmuka chat yang sama yang dapat Anda tempatkan langsung dalam tata letak halaman web (sebagai alternatif bubble mengambang). Widget dan embed menggunakan konfigurasi tampilan, pesan, dan perilaku yang sama.

Dengan endpoint ini, Anda dapat menyesuaikan tampilan Quickchat AI di situs web secara terprogram: mencocokkan warna merek, menyiapkan formulir sebelum chat untuk mengumpulkan informasi pengunjung, mengonfigurasi indikator mengetik, mengaktifkan masukan suara, dan lainnya. Untuk petunjuk penyiapan, lihat panduan saluran Situs Web.

Cakupan: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell
Python

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Respons 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"],
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "attachments_active": true,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "launcher_label": "Ask AI",
  "launcher_draggable": false,
  "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "theme": "light",
  "widget_theme_custom": {
    "colors": {
      "background": "#ffffff",
      "header": "#ffffff",
      "header_text": "#030712",
      "accent": "#27272a",
      "accent_hover": "#374151",
      "accent_text": "#ffffff",
      "bubble": "#27272a",
      "bubble_text": "#ffffff",
      "ai_bubble_text": "#030712",
      "tertiary": "#afafb2",
      "link": null,
      "input_background": "#ffffff",
      "input_text": "#030712",
      "input_placeholder": "#9ca3af",
      "border": "#e5e7eb",
      "sidebar": {
        "background": "#f5f5f5",
        "text": null,
        "accent": "#e5e5e5",
        "accent_text": null
      }
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" },
    "transparency": { "style": "none", "opacity": 70 }
  }
}

Konten & Pesan

Bidang	Deskripsi
`welcome_message` string	Pesan sambutan utama yang ditampilkan saat widget dibuka (HTML). Dashboard: Saluran > Situs Web Anda > Konten teks > Pesan sambutan
`welcome_message2` string	Pesan sambutan tambahan di bawah sapaan utama. Tersedia melalui API; tidak ada bidang editor untuknya di Dashboard.
`header` string	Teks pada bilah header widget. Dashboard: Saluran > Situs Web Anda > Konten teks > Teks header
`subtitle` string	Teks subjudul di bawah header. Tersedia melalui API; tidak ada bidang editor untuknya di Dashboard.
`input_placeholder` string	Teks placeholder di bidang masukan pesan (misalnya, “Ketik pesan Anda…”)
`conversation_starters` array of strings atau null	Saran pembuka percakapan yang ditampilkan sebagai tombol saat widget dibuka. Maksimal 3 entri, masing-masing sekitar 100 karakter
`background_disclaimer_text` string atau null	Teks penafian di bagian bawah jendela chat

Tampilan

Bidang	Deskripsi
`primary_color` string	Warna aksen widget sebagai nilai CSS rgb (misalnya, `"rgb(0, 122, 255)"`). Digunakan untuk tombol, tautan, dan bubble pesan pengguna
`header_color` string	Warna latar belakang header sebagai nilai CSS rgb
`header_text_color` boolean	Kecerahan teks header. `true` = teks putih/terang (untuk header gelap), `false` = teks gelap (untuk header terang). Catatan: meskipun namanya demikian, nilainya adalah boolean, bukan string warna
`size` string	Preset ukuran launcher: `"small"`, `"medium"`, atau `"large"` (ditampilkan di dashboard sebagai Kecil, Hanya Input, dan Klasik)
`location` string	Posisi widget pada halaman: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"`, atau `"bottom-right"`
`launcher_label` string atau null	Teks pada tombol launcher kecil (`size: "small"`), maksimal 25 karakter. `null` menggunakan default (`"Ask AI"`); `""` menampilkan launcher dengan ikon saja
`launcher_draggable` boolean	Mengizinkan pengunjung menyeret launcher ke posisi lain pada halaman
`window_height` integer	Tinggi widget dalam piksel (400-1200)
`window_width` integer	Lebar widget dalam piksel (300-700)
`avatar_image` string atau null	URL Avatar Agen AI, yang ditampilkan di header chat dan sebagai ikon bubble mengambang. Unggah melalui PATCH sebagai base64. `null` berarti avatar dihapus dan widget tidak menampilkan avatar
`bubble_icon_image` string atau null	Tidak digunakan lagi. Selalu mencerminkan `avatar_image`; ikon bubble dan avatar chat kini merupakan satu gambar (lihat penyatuan Avatar Agen AI)
`default_avatar_image` string	Hanya baca. URL Avatar Agen AI default yang dipulihkan oleh `use_default_avatar`
`theme` string	Mode tema warna: `"light"` atau `"dark"` (preset tetap), atau `"custom"` (menerapkan palet `widget_theme_custom`)
`widget_theme_custom` object	Penyesuaian tema. `colors` (header, aksen, bubble pesan, teks AI, `link`, masukan, batas, dan lainnya, dalam hex atau `rgb()`/`rgba()`) hanya berlaku saat `theme` bernilai `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` untuk bubble, masukan, dan tombol), `font.size` (`"sm"`/`"base"`/`"lg"`), dan `transparency` berlaku dalam setiap mode tema. `transparency.style` bernilai `"none"` (solid, default) atau `"glass"` (tembus pandang dengan halaman di belakangnya diburamkan); `transparency.opacity` (40–95, default 70) adalah persentase tint Kaca, dan widget tidak pernah merendernya lebih transparan daripada yang dibutuhkan teks tema pada situs web apa pun (50 pada Terang, 65 pada Gelap, diturunkan dari warna pada Kustom). Jika tidak ada opasitas yang membuat teks palet Kustom terbaca, widget dirender solid, sementara `transparency.style` yang tersimpan tetap `"glass"`. Halaman Chat selalu dirender solid. Pada PATCH, kirim seluruh objek: kunci yang tidak disertakan kembali ke default, sehingga objek lama tanpa `transparency` mengembalikannya ke `"none"`. `widget_theme_custom` dan setiap bagiannya (`colors`, `radius`, `font`, `transparency`) harus berupa objek; `null` menggunakan default seluruh tema atau bagian tersebut, dan nilai lainnya ditolak dengan 422. Default `colors.link` adalah `null`, yang berarti tautan mewarisi warna teks di sekitarnya. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) hanya mengatur tema sidebar Halaman Chat mandiri (diabaikan pada tampilan bubble dan embed); default `text` dan `accent_text` adalah `null`, yang berarti warna terbaca ditentukan otomatis dari latar belakang yang sesuai

Perilaku

Bidang	Deskripsi
`popup_active` boolean	Menampilkan pesan popup di dekat bubble widget untuk mengajak pengunjung memulai percakapan
`window_auto_open` boolean	Membuka widget secara otomatis saat halaman dimuat (alih-alih hanya menampilkan bubble)
`header_collapse` boolean	Mengizinkan pengunjung menutup bagian header untuk menyediakan lebih banyak ruang chat
`typing` boolean	Menampilkan animasi indikator mengetik saat AI membuat respons
`streaming_active` boolean	Mengalirkan respons AI kata demi kata alih-alih menampilkan seluruh pesan sekaligus
`voice_active` boolean	Mengaktifkan masukan suara, sehingga pengunjung dapat mengirim pesan menggunakan mikrofon
`attachments_active` boolean	Mengizinkan pengunjung melampirkan gambar atau dokumen pada pesan. Default `true`; atur ke `false` untuk menyembunyikan tombol lampiran dan menolak unggahan
`link_tracking_active` boolean	Melacak saat pengunjung mengeklik tautan dalam respons AI. Klik yang dilacak muncul sebagai peristiwa `tracked_link` di Peristiwa Percakapan
`white_label` boolean	Menghapus merek “Powered by Quickchat” dari widget

Formulir Sebelum Chat

Bidang	Deskripsi
`prechat_active` boolean	Mengaktifkan formulir sebelum chat. Saat aktif, pengunjung harus mengisi formulir sebelum mengobrol
`prechat_header_text` string atau null	Teks header formulir sebelum chat
`prechat_button_text` string atau null	Label tombol kirim formulir sebelum chat
`prechat_message_text` string atau null	Teks isi/petunjuk pada formulir sebelum chat (HTML)

Cakupan: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Isi Permintaan. Semua bidang bersifat opsional. Sertakan hanya bidang yang ingin Anda perbarui.

Untuk avatar_image, kirim data gambar berformat base64 (maksimal 5 MB). Respons mengembalikan URL gambar yang disimpan. Mengirim avatar_image: null menghapus avatar (widget kemudian tidak menampilkan avatar), dan mengirim use_default_avatar: true memulihkan Avatar Agen AI default.

Penyatuan Avatar Agen AI

Avatar chat (logo header) dan ikon bubble mengambang (launcher) digabung menjadi satu gambar, Avatar Agen AI, yang disimpan dalam avatar_image. Ikon bubble selalu mencerminkannya; tidak ada lagi gambar launcher terpisah. Jika Anda mengintegrasikan endpoint ini secara langsung, perhatikan perubahan perilaku berikut:

Pengunggahan melalui bubble_icon_image tidak digunakan lagi: kini pengunggahan tersebut mengatur Avatar Agen AI terpadu, yang juga mengganti gambar di header chat. Gunakan avatar_image.
bubble_icon_image: null tidak melakukan perubahan. Sebelumnya nilai ini menghapus ikon launcher; karena launcher mencerminkan avatar, hapus melalui avatar_image: null.
Agen yang avatarnya belum pernah disesuaikan menampilkan Avatar Agen AI default (lihat default_avatar_image dalam respons) pada header dan launcher.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Respons 200 OK. Mengembalikan konfigurasi widget yang diperbarui (skema sama dengan respons Dapatkan Konfigurasi Widget).

Konfigurasi Widget

Pemeriksaan contoh opsional