ChatKit의 테마와 커스터마이징

ChatKit quickstart를 따라 했다면, 이제 채팅 embed의 테마를 바꾸고 커스터마이징을 추가하는 법을 배워 볼게요. 라이트·다크 테마, 액센트 색상, 밀도, 둥근 모서리 설정으로 앱의 미학과 맞출 수 있어요.

출처: 문서

본문

개요 (Overview)

높은 수준에서 options 객체를 전달해 테마를 커스터마이즈해요. ChatKit quickstart를 따라 프론트엔드에 ChatKit을 삽입했다면 아래 React 문법을 쓰면 돼요.

React: useChatKit({...})에 options를 전달해요.
고급 통합: chatkit.setOptions({...})로 options를 설정해요.

두 통합 유형 모두에서 options 객체의 모양은 동일해요.

커스터마이제이션 옵션 탐색하기

ChatKit Studio를 방문하면 ChatKit의 동작 구현과 인터랙티브 빌더를 볼 수 있어요. 읽는 것보다 직접 해보면서 만드는 걸 좋아한다면 이 리소스가 좋은 출발점이에요.

ChatKit UI 탐색하기

chatkit.world: ChatKit의 인터랙티브 데모를 조작해 볼 수 있어요.
Widget builder: 사용 가능한 위젯을 둘러볼 수 있어요.
ChatKit playground: 인터랙티브 데모로 직접 배워볼 수 있어요.

동작 예시 보기

GitHub 샘플: ChatKit의 동작 예시를 보고 영감을 얻어요.
Starter 앱 repo: 완전히 동작하는 템플릿으로 시작할 수 있게 repo를 클론해요.

테마 바꾸기

색상, 타이포그래피 등을 지정해 제품의 느낌과 분위기를 맞춰요. 아래에서는 다크 모드로 설정하고, 색상을 바꾸고, 모서리를 둥글게 하고, 정보 밀도를 조정하고, 폰트를 설정해요.

모든 테마 옵션은 API reference를 참고하세요.

const options = {
  theme: {
    colorScheme: "dark",
    color: {
      accent: {
        primary: "#2D8CFF",
        level: 2,
      },
    },
    radius: "round",
    density: "compact",
    typography: { fontFamily: "'Inter', sans-serif" },
  },
};

시작 화면 텍스트 커스터마이즈하기

작성기(composer)의 placeholder 텍스트를 바꿔 사용자가 무엇을 물어볼지 알게 하거나 첫 입력을 안내할 수 있어요.

const options = {
  composer: {
    placeholder: "Ask anything about your data…",
  },
  startScreen: {
    greeting: "Welcome to FeedbackBot!",
  },
};

새 스레드용 스타터 프롬프트 보여주기

대화를 시작할 때 프롬프트 아이디어를 제안해 사용자가 무엇을 물어보거나 할지 안내해요.

const options = {
  startScreen: {
    greeting: "What can I help you build today?",
    prompts: [
      {
        name: "Check on the status of a ticket",
        prompt: "Can you help me check on the status of a ticket?",
        icon: "search",
      },
      {
        name: "Create Ticket",
        prompt: "Can you help me create a new support ticket?",
        icon: "write",
      },
    ],
  },
};

헤더에 커스텀 버튼 추가하기

커스텀 헤더 버튼은 통합과 관련된 내비게이션, 컨텍스트, 액션을 추가하는 데 도움이 돼요.

const options = {
  header: {
    customButtonLeft: {
      icon: "settings-cog",
      onClick: () => openProfileSettings(),
    },
    customButtonRight: {
      icon: "home",
      onClick: () => openHomePage(),
    },
  },
};

파일 첨부 활성화하기

첨부는 기본적으로 비활성화돼 있어요. 활성화하려면 attachments 구성을 추가하세요. 커스텀 백엔드를 만들지 않는다면 반드시 hosted 업로드 전략을 사용해야 해요. 커스텀 백엔드를 쓸 때 다른 업로드 전략이 어떻게 동작하는지는 Python SDK 문서를 참고하세요.

사용자가 메시지에 첨부할 수 있는 파일의 개수, 크기, 유형을 제어할 수도 있어요.

const options = {
  composer: {
    attachments: {
      uploadStrategy: { type: "hosted" },
      maxSize: 20 * 1024 * 1024, // 20 MB per file
      maxCount: 3,
      accept: { "application/pdf": [".pdf"], "image/*": [".png", ".jpg"] },
    },
  },
};

작성기에서 @멘션과 엔티티 태그 활성화하기

사용자가 @멘션으로 커스텀 "엔티티"를 태그할 수 있게 해요. 이렇게 하면 더 풍부한 대화 컨텍스트와 상호작용이 가능해져요.

onTagSearch로 입력 쿼리에 기반한 엔티티 목록을 반환해요.
onClick으로 엔티티의 클릭 이벤트를 처리해요.

const options = {
  entities: {
    async onTagSearch(query) {
      void query;
      return [
        {
          id: "user_123",
          title: "Jane Doe",
          group: "People",
          interactive: true,
        },
        {
          id: "document_123",
          title: "Quarterly Plan",
          group: "Documents",
          interactive: true,
        },
      ];
    },
    onClick: (entity) => {
      navigateToEntity(entity.id);
    },
  },
};

엔티티 태그 표시 방식 커스터마이즈하기

위젯을 사용해 마우스오버 시 엔티티 태그의 표시 방식을 커스터마이즈할 수 있어요. 사용자가 엔티티 태그 위에 마우스를 올리면 명함, 문서 요약, 이미지 같은 풍부한 미리보기를 보여줄 수 있어요.

const options = {
  entities: {
    async onTagSearch() {
      return [];
    },
    onRequestPreview: async (entity) => ({
      preview: {
        type: "Card",
        children: [
          { type: "Text", value: `Profile: ${entity.title}` },
          { type: "Text", value: "Role: Developer" },
        ],
      },
    }),
  },
};

작성기에 커스텀 툴 추가하기

작성기 막대에서 사용자가 앱 특정 액션을 트리거할 수 있게 해 생산성을 높여요. 선택한 툴은 모델에 툴 선호도(tool preference)로 전송돼요.

const options = {
  composer: {
    tools: [
      {
        id: "add-note",
        label: "Add Note",
        icon: "write",
        pinned: true,
      },
    ],
  },
};

UI 영역과 기능 토글하기

헤더에서 제공되는 옵션보다 더 많은 커스터마이제이션이 필요하고 직접 구현하고 싶다면 주요 UI 영역과 기능을 비활성화할 수 있어요. history를 비활성화하는 것은 지원 챗봇처럼 스레드와 히스토리 개념이 의미가 없는 경우에 유용해요.

const options = {
  history: { enabled: false },
  header: { enabled: false },
};

로케일 재정의하기

앱 전역 언어 설정이 있다면 기본 로케일을 재정의할 수 있어요. 기본적으로 로케일은 브라우저의 로케일로 설정돼요.

const options = {
  locale: "de-DE",
};

ChatKit의 테마와 커스터마이징