JavaScript 한 줄 없이 WebChat 임베드하기

원문: Embedding WebChat Without Writing a Single Line of JavaScript 게시일: 2026-01-26 · 저자: Adi Leibowitz

새 라이브러리를 만들었어요. 미니멀리즘이 핵심이에요. 그 정신에 따르자면, 이 글은 아마 여기서 끝나야 할 거예요.

아니면 하이쿠로 표현할 수도 있겠네요.

데이터 속성이여
JavaScript는 필요 없네
WebChat이 그저 나타나네

하지만 이번 것은 너무 신이 나서 여기서 멈출 수가 없어요. 그래서 전체 그림을 소개할게요.

요약하자면: 이제 HTML만으로 완전한 기능을 갖춘 Copilot Studio 채팅 위젯을 어떤 웹사이트에든 임베드할 수 있어요. 작성할 JavaScript도 없고, 빌드 단계도 없어요. 데이터 속성 몇 개가 달린 <div> 하나와 스크립트 태그 하나면 충분해요.

기존 WebChat 임베딩 방식의 문제

BotFramework WebChat을 임베드하는 표준 방식은 대략 이래요.

const tokenEndpointURL = 'https://your-token-endpoint';
const res = await fetch(tokenEndpointURL);
const { token } = await res.json();

window.WebChat.renderWebChat(
  {
    directLine: window.WebChat.createDirectLine({ token }),
    styleOptions: {
      accent: '#0078d4',
      bubbleBorderRadius: 12,
      // ... many more options
    }
  },
  document.getElementById('webchat')
);

이를 위해서는 다음이 필요해요.

async/await와 fetch에 대한 이해
Direct Line 토큰의 동작 방식에 대한 지식
styleOptions 수동 구성
토큰 실패에 대한 오류 처리
채팅 컨테이너 요소 관리

그리고 이건 고정된 채팅 창을 위한 것일 뿐이에요. 최소화하고 확장되는 플로팅 버블을 원하시나요? 그러면 이제 다음도 만들어야 해요.

상태 관리가 있는 토글 버튼
표시·숨김 애니메이션
최소화 및 재시작 컨트롤이 있는 헤더
플로팅 컨테이너의 위치 지정 로직

개발자라면 다 가능한 일이지만, 마케팅 사이트에 채팅 위젯 하나 추가하고 싶은 사람에게는 고역이에요.

botframework-webchat-embed 등장

botframework-webchat-embed는 위의 모든 걸 대신 처리해 주는 WebChat의 경량 래퍼예요. 모든 것을 HTML 데이터 속성으로 구성하면, 토큰 가져오기, 위젯 렌더링, 플로팅 버블 UI를 알아서 처리해요.

전체 통합 코드는 이렇게 생겼어요.

<!-- 1. Add a container with your token endpoint -->
<div
  style="position: fixed; bottom: 20px; right: 20px; width: 380px; height: 550px;"
  data-webchat-token-url="https://your-copilot-studio-token-endpoint">
</div>

<!-- 2. Load the script -->
<script src="https://cdn.jsdelivr.net/npm/botframework-webchat-embed@latest"></script>

이게 전부예요. 요소 두 개. 스크립트가 data-webchat-token-url이 있는 요소를 자동으로 찾아, 다음을 모두 갖춘 완전한 기능의 채팅 위젯을 렌더링해요.

클릭하면 확장되는 플로팅 채팅 버블
최소화 및 재시작 버튼이 있는 헤더
사이트의 CSS 변수로부터 자동 스타일 상속
지연 로딩(사용자가 위젯을 열 때만 WebChat이 로드됨)

위젯 구성하기

먼저 Copilot Studio 토큰 엔드포인트가 필요해요. 설정(Settings) → **채널(Channels)**로 이동해 이메일(Email) 채널을 선택하고 토큰 엔드포인트(Token Endpoint) URL을 복사하세요.

주의: 이 라이브러리는 인증되지 않은 에이전트만 지원해요. 에이전트에 Entra ID 인증이 필요하다면 전체 WebChat SDK를 써야 해요.

외관

헤더와 버블 텍스트를 커스터마이징할 수 있어요.

<div
  data-webchat-token-url="https://your-token-endpoint"
  data-webchat-title="Support"
  data-webchat-bubble-text="Need help?">
</div>

스타일링

위젯은 사이트의 CSS 변수(--primary-color, --accent-color, --brand-color)를 자동으로 감지하고 컨테이너로부터 font-family를 상속받아요. 서로 다른 사이트의 두 위젯인데도, 명시적 스타일링은 전혀 없어요.

--primary-color: #6366f1을 사용하는 사이트

--primary-color: #f97316을 사용하는 사이트

명시적으로 제어하려면 data-webchat-style-* 속성(모든 WebChat styleOption의 kebab-case 버전)을 쓰세요.

<div
  data-webchat-token-url="..."
  data-webchat-style-accent-color="#ff6b6b"
  data-webchat-style-bubble-border-radius="8"
  data-webchat-style-hide-upload-button="true">
</div>

동작

여기서부터가 재미있는 부분이에요. 앞서 말했던 상태 관리, 지연 로딩, 환영 메시지 로직을 기억하시나요? 이 모든 게 속성 몇 개로 처리돼요.

속성	기본값	동작
`data-webchat-minimized`	`true`	플로팅 버블 상태로 시작
`data-webchat-preload`	`false`	최소화 상태에서도 WebChat을 즉시 로드
`data-webchat-send-start-event`	`true`	로드 시 Conversation Start 토픽 트리거
`data-webchat-mock-welcome`	`false`	에이전트 호출 대신 클라이언트 사이드 환영 메시지 표시

마지막 항목이 제가 제일 좋아하는 기능이에요. 에이전트를 실제로 트리거하지 않고 친근한 인사말을 표시하고 싶으신가요? 불리언 하나만 바꾸면 돼요. Redux 미들웨어도, 액티비티 주입도, 타이밍 꼼수도 필요 없어요. 이게 왜 중요한지 설명하는 모킹된 환영 메시지에 대한 글을 통째로 쓴 적이 있는데, 여기서는 그저… 속성 하나예요.

완전한 예제

다크 테마 사이트에서는 이런 모습이에요.

<!DOCTYPE html>
<html>
<head>
  <style>
    :root { --primary-color: #6366f1; }
    body { font-family: 'Inter', sans-serif; }
    .chat-widget {
      position: fixed;
      bottom: 20px;
      right: 20px;
      width: 380px;
      height: 550px;
    }
  </style>
</head>
<body>
  <div
    class="chat-widget"
    data-webchat-token-url="https://your-token-endpoint"
    data-webchat-title="Support"
    data-webchat-bubble-text="Chat with us">
  </div>
  <script src="https://cdn.jsdelivr.net/npm/botframework-webchat-embed@latest"></script>
</body>
</html>

제한 사항

이 라이브러리는 의도적으로 다음을 지원하지 않아요.

Entra ID로 인증되는 에이전트
Direct Line 시크릿
커스텀 미들웨어 또는 액티비티 인터셉터

이 중 하나라도 필요하다면 전체 BotFramework WebChat SDK를 쓰세요.

핵심 요약

HTML 데이터 속성만으로 WebChat 임베드
CSS 변수로부터 자동 스타일 상속
최소화·재시작 기능이 내장된 플로팅 버블 UI
인증되지 않은 Copilot Studio 에이전트 전용

속성이란 무엇인가
코드가 아닌, 선언된 의도
그리고 그것은 이루어지네

여러분의 사이트에 WebChat을 임베드해 보셨나요? 여러분의 사용 사례가 궁금해요. 아래에 댓글을 남겨 주세요!