Widget Configuration

API を使ってウェブサイトウィジェットの設定を読み取り・更新します。

ウィジェット は、ウェブサイトに埋め込むチャットインターフェースです。ページの隅にフローティングのバブルとして表示され、訪問者はそれをクリックして AI Agent との会話を開始できます。ウィジェットは完全にカスタマイズ可能で、色、サイズ、位置、挨拶メッセージ、動作を制御できます。

これらの設定は embed にも影響します。embed は同じチャットインターフェースのフルページ版またはインライン版で、（フローティングのバブルとは異なり）ウェブページのレイアウトに直接配置できます。ウィジェットと embed はどちらも、外観、メッセージ、動作について同じ設定を共有します。

これらのエンドポイントを使うと、Quickchat AI がウェブサイト上にどのように表示されるかをプログラムからカスタマイズできます。ブランドカラーに合わせたり、訪問者情報を収集するプリチャットフォームを設定したり、入力中インジケーターを構成したり、音声入力を有効にしたりできます。セットアップ手順については Website channel ガイドを参照してください。

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

Response 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,
  "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" }
  }
}

Content & Messaging

Field	Description
`welcome_message` string	ウィジェットを開いたときに表示されるメインのウェルカムメッセージ（HTML）。Dashboard: Website > Greeting
`welcome_message2` string	メインの挨拶の下に表示されるサブのウェルカムメッセージ
`header` string	ウィジェットのヘッダーバーに表示されるテキスト。Dashboard: Website > Header
`subtitle` string	ヘッダーの下に表示されるサブタイトルのテキスト。Dashboard: Website > Subtitle
`input_placeholder` string	メッセージ入力欄のプレースホルダーテキスト（例：「Type your message…」）
`conversation_starters` array of strings or null	ウィジェットを開いたときにクリック可能なボタンとして表示される、おすすめの開始プロンプト。最大 3 件、それぞれ約 100 文字まで
`background_disclaimer_text` string or null	チャットウィンドウ下部に表示される免責事項のテキスト

Appearance

Field	Description
`primary_color` string	CSS rgb 値で指定するウィジェットのアクセントカラー（例：`"rgb(0, 122, 255)"`）。ボタン、リンク、ユーザーのメッセージバブルに使用されます
`header_color` string	CSS rgb 値で指定するヘッダーの背景色
`header_text_color` boolean	ヘッダーテキストの明度。`true` = 白 / 明るいテキスト（暗いヘッダー用）、`false` = 暗いテキスト（明るいヘッダー用）。注意：名前に反して、これは色文字列ではなくブール値です
`size` string	ランチャーのサイズプリセット：`"small"`、`"medium"`、`"large"`（Dashboard では Small、Input Only、Classic として表示されます）
`location` string	ページ上のウィジェットの位置：`"top-left"`、`"top-right"`、`"bottom-left"`、または `"bottom-right"`
`launcher_label` string or null	small ランチャーボタン（`size: "small"`）上のテキスト。最大 25 文字。`null` はデフォルト（`"Ask AI"`）を使用し、`""` はアイコンのみのランチャーを表示します
`launcher_draggable` boolean	訪問者がランチャーをページ上の別の位置にドラッグできるようにします
`window_height` integer	ウィジェットの高さ（ピクセル単位、400-1200）
`window_width` integer	ウィジェットの幅（ピクセル単位、300-700）
`avatar_image` string or null	AI Agent Avatar の URL。チャットヘッダーとフローティングバブルのアイコンの両方に表示されます。PATCH で base64 としてアップロードします。`null` はアバターが削除されたことを意味し、ウィジェットにはアバターが表示されません
`bubble_icon_image` string or null	非推奨。常に `avatar_image` を反映します。バブルアイコンとチャットアバターは現在 1 つの画像になりました（AI Agent Avatar unification を参照）
`default_avatar_image` string	読み取り専用。`use_default_avatar` が復元するデフォルトの AI Agent Avatar の URL
`theme` string	カラーテーマモード：`"light"` または `"dark"`（固定プリセット）、または `"custom"`（`widget_theme_custom` パレットを適用）
`widget_theme_custom` object	`theme` が `"custom"` のときに適用されるカスタムパレット。`colors`（header、accent、メッセージバブル、AI テキスト、`link`、input、border など、hex または `rgb()`/`rgba()` 形式）、`radius`（バブル、input、ボタン用の `"sm"`/`"base"`/`"lg"`/`"full"`）、`font.size`（`"sm"`/`"base"`/`"lg"`）を含みます。PATCH ではオブジェクト全体を送信してください。欠落したキーはデフォルトにリセットされます。`colors.link` のデフォルトは `null` で、リンクは周囲のテキストカラーを継承します。`colors.sidebar`（`background`、`text`、`accent`、`accent_text`）は独立した Chat Page のサイドバーのみをテーマ設定します（バブルおよび embed ビューでは無視されます）。その `text` と `accent_text` のデフォルトは `null` で、対応する背景から読みやすい色が自動的に導出されます

Behavior

Field	Description
`popup_active` boolean	ウィジェットバブルの近くにポップアッププロンプトを表示し、訪問者に会話の開始を促します
`window_auto_open` boolean	ページ読み込み時にウィジェットを自動的に開きます（バブルのみを表示する代わりに）
`header_collapse` boolean	訪問者がヘッダー領域を折りたたんでチャットスペースを広げられるようにします
`typing` boolean	AI が応答を生成している間、入力中インジケーターのアニメーションを表示します
`streaming_active` boolean	完成したメッセージを一度に表示する代わりに、AI の応答を 1 語ずつストリーミングします
`voice_active` boolean	音声入力を有効にします。訪問者はマイクを使ってメッセージを送信できます
`link_tracking_active` boolean	訪問者が AI の応答内のリンクをクリックしたときに追跡します。追跡されたクリックは Conversation Events で `tracked_link` イベントとして表示されます
`white_label` boolean	ウィジェットから「Powered by Quickchat」のブランディングを削除します

Pre-chat Form

Field	Description
`prechat_active` boolean	プリチャットフォームを有効にします。有効な場合、訪問者はチャットする前にフォームに入力する必要があります
`prechat_header_text` string or null	プリチャットフォームのヘッダーテキスト
`prechat_button_text` string or null	プリチャットフォームの送信ボタンのラベル
`prechat_message_text` string or null	プリチャットフォームに表示される本文 / 説明文（HTML）

Scope: write_all

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

Request Body — すべてのフィールドは任意です。更新したいフィールドのみを含めてください。

AI Agent Avatar unification

チャットアバター（ヘッダーロゴ）とフローティングバブルのアイコン（ランチャー）は、1 つの画像である AI Agent Avatar に統合され、avatar_image に保存されます。バブルアイコンは常にそれを反映します。独立したランチャー画像はもうありません。このエンドポイントと直接連携する場合は、以下の動作変更に注意してください：

bubble_icon_image 経由でのアップロードは 非推奨 です。これは現在、統合された AI Agent Avatar を設定し、チャットヘッダーに表示される画像も置き換えます。代わりに avatar_image を使用してください。
bubble_icon_image: null は 何もしません。以前はランチャーアイコンをクリアしていましたが、ランチャーはアバターを反映するため、代わりに avatar_image: null で削除してください。
アバターをカスタマイズしたことがない Agent は、ヘッダーとランチャーの両方にデフォルトの AI Agent Avatar（レスポンスの default_avatar_image を参照）を表示します。

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

Response 200 OK — 更新された widget configuration を返します（Get Widget Configuration のレスポンスと同じスキーマ）。

Widget Configuration