사내 포털, 고객 지원 페이지, 그룹웨어 등 외부 웹사이트에 Cloosphere 채팅을 삽입 하는 기능입니다. 한 줄의 스크립트 태그만으로 어떤 웹페이지에서든 AI 채팅을 제공할 수 있습니다.
왜 필요한가 기존 방식 임베드 위젯 사용자가 Cloosphere에 직접 접속해야 함 업무 시스템 안에서 바로 AI 채팅 별도 로그인 필요 토큰 전달 또는 위젯 내 자체 로그인 외부 시스템 연동 불가 AI가 호스트 페이지의 폼을 읽고 채우는 UI 브리지 지원
활용 시나리오:
사내 그룹웨어에 AI 비서를 배치하여 휴가 신청서를 대화로 작성
고객 지원 페이지에 FAQ 챗봇 삽입
관리 콘솔에 운영 지원 AI 탑재
위젯 생성 관리자 > 설정 > Embed Widgets 탭에서 위젯을 관리합니다.
위젯 추가
”+” 버튼 을 클릭하여 새 위젯을 생성합니다.
기본 정보 입력
필드 설명 이름 위젯 식별 이름 (헤더 기본 타이틀로도 사용) 설명 관리자용 메모 (외부에 노출되지 않음) 모델/에이전트 위젯에서 사용할 에이전트 , 플로우 , 또는 모델 선택 시스템 프롬프트 위젯 전용 시스템 프롬프트 (선택)
디자인 편집
“Design” 버튼 을 클릭하여 외형을 커스터마이징합니다 (아래 상세 설명).
활성화
위젯 목록에서 토글을 Active 로 설정합니다. 비활성화된 위젯은 외부에서 로드되지 않습니다.
표시 모드 위젯이 호스트 페이지에서 어떻게 보이는지 5가지 모드를 지원합니다.
모드 동작 기본 크기 Bubble 우하단(또는 좌하단) 플로팅 버튼 → 클릭 시 채팅 패널 팝업 400×600px Side Right 화면 우측에 고정 패널 (본문에 margin 자동 적용) 380px 너비 Side Left 화면 좌측에 고정 패널 380px 너비 Inline 지정한 HTML 요소 내부에 삽입 100%×500px Fullscreen 전체 화면 오버레이 100vw×100vh
Bubble 모드 가 가장 일반적인 선택입니다. 사용자가 필요할 때만 클릭하여 사용하며, 모바일(480px 이하)에서 자동으로 반응형 크기 조절됩니다. 다른 모드는 모바일 대응을 위해 width/height를 직접 지정하세요.
디자인 커스터마이징 Design 에디터에서 위젯의 외형을 세밀하게 조정할 수 있습니다. 실시간 미리보기로 변경 사항을 즉시 확인 가능합니다.
레이아웃 설정 설명 Mode 표시 모드 (5가지 중 선택) Position Bubble 모드의 버튼 위치 (우하단 / 좌하단) Width / Height 위젯 크기 (CSS 값, 예: 400px, 100%)
아이콘 설정 설명 Bubble Icon 플로팅 버튼 아이콘 (7종 프리셋 + 커스텀 업로드) Send Button Icon 전송 버튼 아이콘 (7종 프리셋 + 커스텀 업로드)
프리셋: Chat, Sparkles, Message, Robot, Support(Headset), Help(Question), Bolt
설정 설명 Show Header 헤더 표시 여부 Header Text 헤더 타이틀 (비우면 위젯 이름 사용) Show Avatar AI 아바타 표시 여부 Avatar URL 커스텀 AI 아바타 이미지 Bot Name AI 이름 (메시지 상단에 표시)
설정 적용 대상 Primary Color Bubble 버튼 배경 Bubble Icon Color Bubble 버튼 아이콘 Header Color 헤더 배경 Header Text Color 헤더 텍스트 Background Color 채팅 영역 배경 Message Text Color 메시지 텍스트 Send Button Color 전송 버튼 배경 Send Button Icon Color 전송 버튼 아이콘
채팅 설정 설정 설명 기본값 Theme 테마 (auto / light / dark). auto는 OS 설정을 따름 auto Welcome Message 채팅 시작 시 AI가 자동으로 보내는 환영 메시지 — Max Messages Per Session 세션당 최대 메시지 수. 0 = 무제한 0
기능 토글 설정 설명 기본값 File Upload 파일 첨부 허용 off Markdown 마크다운 렌더링 on Code Highlight 코드 블록 하이라이팅 on Web Search 웹 검색 기능 off
임베드 코드 위젯을 생성하면 호스트 페이지에 삽입할 스크립트 태그 가 제공됩니다.
< script src = "https://your-cloosphere.com/static/embed/embed.js" data-widget-id = "WIDGET_ID" > </ script >
이 한 줄로 위젯이 자동으로 로드됩니다. 추가 data-* 속성으로 설정을 오버라이드할 수 있습니다:
속성 설명 data-widget-id위젯 ID (필수) data-token사전 인증된 사용자 토큰 (선택 — 있으면 로그인 건너뜀) data-mode표시 모드 오버라이드 data-theme테마 오버라이드 (light / dark / auto) data-position버튼 위치 오버라이드 (bottom-right / bottom-left) data-primary-colorBubble 버튼 색상 오버라이드 data-targetInline 모드의 대상 CSS 셀렉터 data-width / data-height크기 오버라이드
< div id = "my-chat-container" style = "height: 600px;" ></ div > < script src = "https://your-cloosphere.com/static/embed/embed.js" data-widget-id = "WIDGET_ID" data-mode = "inline" data-target = "#my-chat-container" > </ script >
<!-- 호스트 페이지에서 사용자 토큰을 주입 --> < script src = "https://your-cloosphere.com/static/embed/embed.js" data-widget-id = "WIDGET_ID" data-token = "eyJhbGciOiJIUzI1NiIs..." > </ script >
토큰을 HTML에 직접 하드코딩하지 마세요. 서버 사이드에서 동적으로 렌더링하거나 JavaScript로 주입하는 것을 권장합니다.
JavaScript API Bubble 모드에서는 JavaScript로 위젯을 제어할 수 있습니다:
// 채팅 패널 열기 window . CloosphereEmbed . open (); // 채팅 패널 닫기 window . CloosphereEmbed . close (); // 런타임에 토큰 교체 window . CloosphereEmbed . updateToken ( "new-jwt-token" );
open() / close()는 Bubble 모드에서만 동작합니다. Side, Inline, Fullscreen 모드에서는 항상 표시되어 있으므로 호출해도 무시됩니다.
로그인 방식 위젯은 Cloosphere 인증이 필요합니다. 3가지 방법 중 하나로 사용자를 인증합니다:
우선순위 방식 설명 1 토큰 전달 data-token 속성 또는 updateToken() API로 JWT 주입2 세션 복원 이전에 위젯에서 로그인한 토큰이 sessionStorage에 남아 있으면 자동 사용 3 위젯 내 로그인 위 둘 다 없으면 로그인 화면 표시
위젯 내 로그인 화면 Cloosphere에 설정된 인증 방식에 따라 자동으로 로그인 화면이 구성됩니다:
OAuth 공급자 : Cloosphere에 Google, Microsoft, GitHub, OIDC(SSO) 등이 설정되어 있으면 해당 버튼이 자동으로 표시됩니다. OAuth는 팝업 방식 으로 진행됩니다.이메일/비밀번호 : 기본 로그인 폼 (OAuth만 설정되어 있으면 숨겨짐)
Private/Incognito 모드에서는 sessionStorage가 차단될 수 있어 매 세션마다 재로그인 이 필요합니다. SSO 환경에서는 data-token으로 서버 사이드 토큰 주입을 권장합니다.
도메인 허용 목록 보안을 위해 위젯이 로드될 수 있는 도메인 을 제한할 수 있습니다.
위젯 설정의 allowed_domains에 허용할 도메인 패턴을 등록합니다:
패턴 매칭 대상 example.com정확히 example.com만 *.example.comsub.example.com, portal.example.com 등 (비워두면) 모든 도메인 허용
운영 환경에서는 반드시 허용 도메인을 명시적으로 설정하세요. 빈 목록은 테스트용으로만 사용하시기 바랍니다.
UI 조작 브리지 임베드 위젯의 가장 강력한 기능 — AI가 호스트 페이지의 DOM을 직접 조작 할 수 있습니다.
예를 들어 사용자가 “오늘 날짜로 휴가 신청해줘”라고 말하면, AI가 호스트 페이지의 휴가 신청 폼에 값을 자동으로 채울 수 있습니다.
사용 가능한 도구 에이전트에 UI 조작 도구가 자동으로 연결되며, 다음 작업이 가능합니다:
도구 기능 fill_form 폼 내 복수 필드를 한 번에 입력 fill_form_field 개별 입력 필드에 값 설정 read_form 폼의 현재 값을 JSON으로 읽기 click_element 버튼이나 링크 클릭 highlight_element 요소를 파란 테두리로 강조 + 스크롤 (2.5초 후 해제) get_page_info 현재 페이지 URL, 제목, 폼 목록 조회 navigate_to 호스트 페이지 이동
보안: 셀렉터 허용 목록 위젯 설정의 allowed_selectors로 AI가 조작할 수 있는 HTML 요소 범위를 제한합니다.
설정 동작 ["*"] (기본값)모든 요소 조작 가능 ["form#leave-form *"]특정 폼 내 요소만 허용 ["#name", "#date", ".btn-submit"]지정한 셀렉터만 허용
운영 환경에서는 allowed_selectors를 명시적으로 제한["*"]는 AI가 페이지의 모든 요소를 조작할 수 있어 의도치 않은 동작이 발생할 수 있습니다.
navigate_to 호출 후 호스트 페이지가 이동하면 iframe이 리로드되어 대화 맥락이 소실 됩니다. AI 프롬프트에서 “navigate_to 호출 후 추가 도구를 사용하지 마세요”와 같은 지침을 포함하는 것이 좋습니다.동일 origin 내에서는 소프트 네비게이션 을 먼저 시도합니다. SPA(Single Page Application)에서 cloosphere:navigate 이벤트를 처리하면 페이지 전환 없이 라우팅이 가능합니다.
제한사항 항목 내용 세션 지속성 위젯을 닫았다 열면 새 세션으로 시작 (이전 대화 복원 안 됨) 채팅 제목 자동 제목/태그 생성이 꺼져 있어, Cloosphere 내 채팅 목록에 Embed: {위젯명}으로 표시 UI 브리지 타임아웃 호스트 페이지 응답이 15초 내에 없으면 도구 실패 모바일 반응형 Bubble 모드만 자동 반응형. 나머지 모드는 width/height 수동 조정 필요 sessionStorage Private/Incognito 모드에서 토큰 저장이 차단될 수 있음
관련 페이지
에이전트 위젯에 연결할 AI 에이전트 생성 및 설정
