Widget yapılandırması

Web sitesi widget yapılandırmasını API üzerinden okuyun ve güncelleyin.

İsteğe bağlı örnek kontrolleri

Widget kod parçasını kontrol edin. Yapıştırılan kodu sağlanan Senaryo Kimliğine göre kontrol edin. Bu araç web sitenizi getirmez.

Uyumlu bir tarayıcıda bu kontroller site araçları olarak da kullanılabilir. Bağlantılar standart formları açar.

Widget, web sitenize eklediğiniz bir sohbet arayüzüdür. Sayfanın köşesinde yüzen bir bubble olarak görünür ve ziyaretçiler AI Temsilcinizle konuşma başlatmak için buna tıklayabilir. Widget tamamen özelleştirilebilir: renklerini, boyutunu, konumunu, karşılama mesajlarını ve davranışını kontrol edersiniz.

Bu ayarlar, aynı sohbet arayüzünün web sayfanızın düzenine doğrudan yerleştirebildiğiniz tam sayfa veya satır içi sürümü olan yerleştirmeyi de etkiler (yüzen bubble yerine). Widget ve yerleştirme; görünüm, mesajlar ve davranış için aynı yapılandırmayı paylaşır.

Bu uç noktalarla Quickchat AI’ın web sitenizde nasıl görüneceğini programatik olarak özelleştirebilirsiniz: marka renklerinizi eşleştirme, ziyaretçi bilgilerini toplamak için sohbet öncesi form hazırlama, yazma göstergelerini yapılandırma, ses girişini etkinleştirme ve daha fazlası. Kurulum talimatları için Web sitesi kanal kılavuzuna bakın.

Kapsam: 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()

Yanıt 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 }
  }
}

İçerik ve mesajlaşma

Alan	Açıklama
`welcome_message` dize	Widget açıldığında gösterilen birincil karşılama mesajı (HTML). Kontrol paneli: Kanallar > Web Siteniz > Metin içeriği > Karşılama mesajı
`welcome_message2` dize	Birincil selamlamanın altında gösterilen ikincil karşılama mesajı. API üzerinden kullanılabilir; kontrol panelinde düzenleme alanı yoktur.
`header` dize	Widget başlık çubuğunda gösterilen metin. Kontrol paneli: Kanallar > Web Siteniz > Metin içeriği > Başlık metni
`subtitle` dize	Başlığın altında gösterilen alt başlık metni. API üzerinden kullanılabilir; kontrol panelinde düzenleme alanı yoktur.
`input_placeholder` dize	Mesaj giriş alanındaki yer tutucu metin (örneğin “Mesajınızı yazın…”)
`conversation_starters` dize dizisi veya null	Widget açıldığında tıklanabilir düğmeler olarak gösterilen önerilen başlangıç istemleri. Her biri yaklaşık 100 karaktere kadar, en fazla 3 öğe
`background_disclaimer_text` dize veya null	Sohbet penceresinin altında gösterilen açıklama metni

Görünüm

Alan	Açıklama
`primary_color` dize	CSS rgb değeri olarak widget vurgu rengi (örneğin `"rgb(0, 122, 255)"`). Düğmeler, bağlantılar ve kullanıcı mesajı baloncuklarında kullanılır
`header_color` dize	CSS rgb değeri olarak başlık arka plan rengi
`header_text_color` mantıksal değer	Başlık metni parlaklığı. `true` = beyaz/açık metin (koyu başlıklar için), `false` = koyu metin (açık başlıklar için). Not: adına rağmen bu bir renk dizesi değil, mantıksal değerdir
`size` dize	Başlatıcı boyutu ön ayarı: `"small"`, `"medium"` veya `"large"` (kontrol panelinde Küçük, Yalnızca giriş ve Klasik olarak gösterilir)
`location` dize	Widget’ın sayfadaki konumu: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` veya `"bottom-right"`
`launcher_label` dize veya null	Küçük başlatıcı düğmesindeki metin (`size: "small"`), en fazla 25 karakter. `null` varsayılanı (`"Ask AI"`) kullanır; `""` yalnızca simgeli başlatıcı gösterir
`launcher_draggable` mantıksal değer	Ziyaretçilerin başlatıcıyı sayfada başka konuma sürüklemesine izin verir
`window_height` tamsayı	Piksel olarak widget yüksekliği (400-1200)
`window_width` tamsayı	Piksel olarak widget genişliği (300-700)
`avatar_image` dize veya null	Hem sohbet başlığında hem de yüzen bubble simgesi olarak gösterilen AI Temsilcisi Avatarının URL’si. PATCH ile base64 olarak yükleyin. `null`, avatarın silindiği ve widget’ın avatar göstermediği anlamına gelir
`bubble_icon_image` dize veya null	Kullanımdan kaldırıldı. Her zaman `avatar_image` değerini yansıtır. Bubble simgesi ile sohbet avatarı artık tek görseldir (bkz. AI Temsilcisi Avatarının birleştirilmesi)
`default_avatar_image` dize	Salt okunur. `use_default_avatar` ile geri yüklenen varsayılan AI Temsilcisi Avatarının URL’si
`theme` dize	Renk teması modu: `"light"` veya `"dark"` (sabit ön ayarlar) ya da `"custom"` (`widget_theme_custom` paletini uygular)
`widget_theme_custom` nesne	Tema özelleştirmesi. `colors` (başlık, vurgu, mesaj baloncuğu, AI metni, `link`, giriş, kenarlık ve diğerleri; hex veya `rgb()`/`rgba()` biçiminde) yalnızca `theme` değeri `"custom"` olduğunda uygulanır. `radius` (baloncuklar, giriş ve düğmeler için `"sm"`/`"base"`/`"lg"`/`"full"`), `font.size` (`"sm"`/`"base"`/`"lg"`) ve `transparency` her tema modunda uygulanır. `transparency.style`, `"none"` (opak, varsayılan) veya `"glass"` (arkadaki sayfa bulanıklaştırılarak saydam) olabilir. `transparency.opacity` (40–95, varsayılan 70), Cam tonunun yüzdesidir; widget hiçbir web sitesinde temanın metin okunabilirliği için gerekenden daha saydam gösterilmez (Açık modda 50, Koyu modda 65, Özel modda renklerden türetilir). Hiçbir opaklık Özel paletin metnini okunabilir tutmuyorsa widget opak gösterilir ve kayıtlı `transparency.style` değeri `"glass"` kalır. Sohbet Sayfası her zaman opak gösterilir. PATCH isteğinde tüm nesneyi gönderin: eksik anahtarlar varsayılanlara döner; dolayısıyla `transparency` içermeyen eski nesne bunu `"none"` değerine döndürür. `widget_theme_custom` ve her bölümü (`colors`, `radius`, `font`, `transparency`) nesne olmalıdır; `null` tüm temanın veya ilgili bölümün varsayılanlarını alır, diğer değerler 422 ile reddedilir. `colors.link` varsayılan olarak `null` değerindedir; bağlantılar çevredeki metin rengini devralır. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) yalnızca bağımsız Sohbet Sayfasının kenar çubuğunu temalandırır (bubble ve yerleştirme görünümlerinde yok sayılır); `text` ve `accent_text` varsayılan olarak `null` değerindedir, yani ilgili arka plandan okunabilir renk otomatik türetilir

Davranış

Alan	Açıklama
`popup_active` mantıksal değer	Ziyaretçileri konuşma başlatmaya teşvik etmek için widget bubble’ının yakınında açılır mesaj gösterir
`window_auto_open` mantıksal değer	Sayfa yüklendiğinde yalnızca bubble göstermek yerine widget’ı otomatik açar
`header_collapse` mantıksal değer	Daha fazla sohbet alanı için ziyaretçilerin başlık alanını daraltmasına izin verir
`typing` mantıksal değer	AI yanıt üretirken yazma göstergesi animasyonu gösterir
`streaming_active` mantıksal değer	AI yanıtlarını tüm mesajı tek seferde göstermek yerine kelime kelime akıtır
`voice_active` mantıksal değer	Ses girişini etkinleştirir; ziyaretçiler mikrofonlarıyla mesaj gönderebilir
`attachments_active` mantıksal değer	Ziyaretçilerin mesaja görsel veya belge eklemesine izin verir. Varsayılan `true`; ek düğmesini gizlemek ve yüklemeleri reddetmek için `false` ayarlayın
`link_tracking_active` mantıksal değer	Ziyaretçilerin AI yanıtlarındaki bağlantılara tıklamasını izler. İzlenen tıklamalar Konuşma Olaylarında `tracked_link` olayları olarak görünür
`white_label` mantıksal değer	Widget’tan “Powered by Quickchat” markalamasını kaldırır

Sohbet öncesi form

Alan	Açıklama
`prechat_active` mantıksal değer	Sohbet öncesi formu etkinleştirir. Etkinken ziyaretçiler sohbet etmeden önce formu doldurmalıdır
`prechat_header_text` dize veya null	Sohbet öncesi formun başlık metni
`prechat_button_text` dize veya null	Sohbet öncesi formun gönder düğmesi etiketi
`prechat_message_text` dize veya null	Sohbet öncesi formda gösterilen gövde metni/talimatlar (HTML)

Kapsam: write_all

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

İstek gövdesi: tüm alanlar isteğe bağlıdır. Yalnızca güncellemek istediğiniz alanları ekleyin.

avatar_image için base64 kodlanmış görsel verisi gönderin (en fazla 5 MB). Yanıt, saklanan görsel URL’sini döndürür. avatar_image: null göndermek avatarı siler (widget artık avatar göstermez); use_default_avatar: true göndermek varsayılan AI Temsilcisi Avatarını geri yükler.

AI Temsilcisi Avatarının birleştirilmesi

Sohbet avatarı (başlık logosu) ve yüzen bubble simgesi (başlatıcı), avatar_image içinde saklanan tek AI Temsilcisi Avatarı görselinde birleştirildi. Bubble simgesi her zaman onu yansıtır; artık bağımsız başlatıcı görseli yoktur. Bu uç noktayı doğrudan kullanıyorsanız şu davranış değişikliklerine dikkat edin:

bubble_icon_image üzerinden yükleme kullanımdan kaldırıldı: artık birleşik AI Temsilcisi Avatarını ayarlar ve sohbet başlığında gösterilen görseli de değiştirir. Bunun yerine avatar_image kullanın.
bubble_icon_image: null hiçbir işlem yapmaz. Eskiden başlatıcı simgesini temizlerdi; başlatıcı artık avatarı yansıttığı için silmek üzere avatar_image: null kullanın.
Avatarını hiç özelleştirmemiş temsilciler, hem başlıkta hem başlatıcıda varsayılan AI Temsilcisi Avatarını gösterir (yanıttaki default_avatar_image alanına bakın).

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()

Yanıt 200 OK: güncellenmiş widget yapılandırmasını döndürür (Widget yapılandırmasını alma yanıtıyla aynı şema).

Widget yapılandırması

İsteğe bağlı örnek kontrolleri