Widget 설정

API로 웹사이트 Widget 설정을 읽고 수정하세요.

선택적으로 사용할 수 있는 예시 검사

Widget 코드 검사하기. 붙여 넣은 코드를 입력한 Scenario ID와 비교합니다. 웹사이트를 가져오지는 않습니다.

호환되는 브라우저에서는 이 검사를 사이트 도구로도 사용할 수 있습니다. 링크는 일반 양식을 엽니다.

Widget은 웹사이트에 삽입하는 채팅 인터페이스입니다. 페이지 모서리에 떠 있는 bubble을 방문자가 클릭하여 AI 에이전트와 대화를 시작합니다. 색상, 크기, 위치, 환영 메시지, 동작을 모두 맞춤 설정할 수 있습니다.

이 설정은 떠 있는 bubble 대신 웹페이지 레이아웃에 직접 넣는 전체 페이지 또는 인라인 채팅 버전인 Embed에도 적용됩니다. Widget과 Embed는 외형, 메시지, 동작 설정을 공유합니다.

이 엔드포인트로 브랜드 색상, 방문자 정보 수집용 채팅 전 양식, 입력 표시, 음성 입력 등 웹사이트에서 Quickchat AI가 표시되는 방식을 프로그램으로 설정하세요. 설치 방법은 웹사이트 채널 가이드를 참고하세요.

권한 범위: 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()

응답 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 }
  }
}

콘텐츠 및 메시지

필드	설명
`welcome_message` 문자열	Widget을 열 때 표시하는 기본 환영 메시지(HTML). 대시보드: 채널 > 내 웹사이트 > 텍스트 콘텐츠 > 환영 메시지
`welcome_message2` 문자열	기본 인사말 아래 표시하는 보조 환영 메시지. API로 사용하며 대시보드 편집 필드는 없습니다.
`header` 문자열	Widget 헤더의 텍스트. 대시보드: 채널 > 내 웹사이트 > 텍스트 콘텐츠 > 헤더 텍스트
`subtitle` 문자열	헤더 아래 부제. API로 사용하며 대시보드 편집 필드는 없습니다.
`input_placeholder` 문자열	메시지 입력 필드의 자리표시자(예: “메시지를 입력하세요…”)
`conversation_starters` 문자열 배열 또는 null	Widget을 열 때 클릭 가능한 버튼으로 표시하는 추천 시작 문구. 최대 3개, 각각 약 100자 이내
`background_disclaimer_text` 문자열 또는 null	채팅 창 하단의 안내 문구

외형

필드	설명
`primary_color` 문자열	CSS rgb 값의 Widget 강조색(예: `"rgb(0, 122, 255)"`). 버튼, 링크, 사용자 메시지 bubble에 사용
`header_color` 문자열	CSS rgb 값의 헤더 배경색
`header_text_color` 불리언	헤더 글자 밝기. `true` = 밝은 글자(어두운 헤더용), `false` = 어두운 글자(밝은 헤더용). 이름과 달리 색상 문자열이 아닌 불리언입니다.
`size` 문자열	실행 버튼 크기 프리셋: `"small"`, `"medium"`, `"large"`(대시보드의 작게, 입력만, 클래식)
`location` 문자열	페이지 내 위치: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"`, `"bottom-right"`
`launcher_label` 문자열 또는 null	작은 실행 버튼(`size: "small"`)의 텍스트, 최대 25자. `null`이면 기본값 `"Ask AI"`, `""`이면 아이콘만 표시
`launcher_draggable` 불리언	방문자가 실행 버튼을 페이지의 다른 위치로 드래그하도록 허용
`window_height` 정수	Widget 높이(400-1200픽셀)
`window_width` 정수	Widget 너비(300-700픽셀)
`avatar_image` 문자열 또는 null	채팅 헤더와 떠 있는 bubble 아이콘에 표시하는 AI Agent 프로필 사진 URL. PATCH로 base64를 업로드합니다. `null`이면 삭제되어 아바타를 표시하지 않습니다.
`bubble_icon_image` 문자열 또는 null	사용 중단. 항상 `avatar_image`와 같습니다. bubble 아이콘과 채팅 아바타는 이제 하나의 이미지입니다(AI Agent 아바타 통합 참고).
`default_avatar_image` 문자열	읽기 전용. `use_default_avatar`로 복원하는 기본 AI Agent 아바타 URL
`theme` 문자열	색상 테마: 고정 프리셋 `"light"`, `"dark"` 또는 `widget_theme_custom` 팔레트를 적용하는 `"custom"`
`widget_theme_custom` 객체	테마 맞춤 설정. `colors`(헤더, 강조색, 메시지 bubble, AI 텍스트, `link`, 입력, 테두리 등의 hex 또는 `rgb()`/`rgba()` 값)는 `theme`이 `"custom"`일 때만 적용됩니다. `radius`(bubble, 입력, 버튼의 `"sm"`/`"base"`/`"lg"`/`"full"`), `font.size`(`"sm"`/`"base"`/`"lg"`), `transparency`는 모든 테마에 적용됩니다. `transparency.style`은 기본 불투명 `"none"` 또는 뒤의 페이지를 흐리게 비추는 `"glass"`입니다. `transparency.opacity`(40–95, 기본 70)는 Glass 색조의 백분율입니다. 어떤 웹사이트에서도 텍스트 가독성에 필요한 값보다 낮게 표시하지 않습니다(라이트 50, 다크 65, 사용자 지정은 색상에서 계산). 어떤 불투명도에서도 사용자 지정 텍스트가 읽기 어렵다면 불투명하게 표시하되 저장된 `transparency.style`은 `"glass"`로 유지합니다. 채팅 페이지는 항상 불투명합니다. PATCH에는 전체 객체를 보내세요. 누락한 키는 기본값으로 초기화되므로 `transparency` 없는 이전 객체를 보내면 `"none"`으로 돌아갑니다. `widget_theme_custom`과 각 섹션(`colors`, `radius`, `font`, `transparency`)은 객체여야 합니다. `null`은 전체 또는 해당 섹션의 기본값을 적용하며 다른 값은 422로 거부합니다. `colors.link`의 기본값은 `null`로 주변 글자색을 상속합니다. `colors.sidebar`(`background`, `text`, `accent`, `accent_text`)는 독립 채팅 페이지 사이드바에만 적용되고 bubble과 Embed에서는 무시됩니다. `text`와 `accent_text`는 기본값 `null`일 때 대응하는 배경에서 읽기 쉬운 색상을 자동 계산합니다.

동작

필드	설명
`popup_active` 불리언	Widget bubble 근처에 팝업을 표시하여 대화 시작 유도
`window_auto_open` 불리언	페이지 로드 시 bubble만 보이는 대신 Widget을 자동으로 열기
`header_collapse` 불리언	채팅 공간을 넓히도록 헤더 접기 허용
`typing` 불리언	AI가 응답을 생성할 때 입력 표시 애니메이션 제공
`streaming_active` 불리언	완성된 메시지를 한 번에 표시하는 대신 단어 단위로 스트리밍
`voice_active` 불리언	마이크로 메시지를 보내는 음성 입력 활성화
`attachments_active` 불리언	방문자의 이미지 또는 문서 첨부 허용. 기본값은 `true`이며 `false`로 설정하면 첨부 버튼을 숨기고 업로드를 거부합니다.
`link_tracking_active` 불리언	AI 응답의 링크 클릭 추적. 대화 이벤트에 `tracked_link` 이벤트로 표시
`white_label` 불리언	Widget의 “Powered by Quickchat” 브랜딩 제거

채팅 전 양식

필드	설명
`prechat_active` 불리언	채팅 전 양식 활성화. 켜면 방문자가 채팅 전에 작성해야 함
`prechat_header_text` 문자열 또는 null	채팅 전 양식 헤더 텍스트
`prechat_button_text` 문자열 또는 null	채팅 전 양식 제출 버튼 라벨
`prechat_message_text` 문자열 또는 null	채팅 전 양식의 본문/안내(HTML)

권한 범위: write_all

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

요청 본문: 모든 필드는 선택 사항입니다. 수정할 필드만 포함하세요.

avatar_image에는 base64 인코딩 이미지 데이터(최대 5MB)를 보내세요. 응답은 저장된 이미지 URL을 반환합니다. avatar_image: null은 아바타를 삭제하여 표시하지 않게 하고 use_default_avatar: true는 기본 AI Agent 아바타를 복원합니다.

AI Agent 아바타 통합

채팅 아바타(헤더 로고)와 떠 있는 bubble 아이콘(실행 버튼)은 avatar_image에 저장하는 AI Agent 프로필 사진 하나로 통합되었습니다. bubble 아이콘은 항상 같은 이미지를 사용하며 별도 실행 버튼 이미지는 없습니다. 직접 연동한다면 다음 변경을 확인하세요.

bubble_icon_image 업로드는 사용 중단되었습니다. 이제 통합 아바타를 설정하여 채팅 헤더 이미지도 교체합니다. avatar_image를 사용하세요.
bubble_icon_image: null은 아무 작업도 하지 않습니다. 이전에는 실행 아이콘을 지웠지만 이제 아바타를 공유하므로 avatar_image: null로 삭제하세요.
아바타를 맞춤 설정하지 않은 에이전트는 헤더와 실행 버튼 모두 기본 AI Agent 아바타(응답의 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()

응답 200 OK: 수정된 Widget 설정을 반환합니다(Widget 설정 조회와 같은 스키마).

Widget 설정

선택적으로 사용할 수 있는 예시 검사

Widget 설정

Widget 설정 조회

콘텐츠 및 메시지

외형

동작

채팅 전 양식

Widget 설정 수정

AI Agent 아바타 통합

시작하기

AI 에이전트

액션

대화

채널

웹사이트

헬프데스크 및 CRM

메신저 앱

계정 및 결제

시작하기

설정

지식 베이스

대화