본문으로 건너뛰기
문서 메뉴메신저 위젯 설치

메신저베타

메신저 위젯 설치

스니펫을 붙이면 화면 오른쪽 아래에 메신저 버튼이 나타나요. 부팅 옵션으로 회원 정보를 넘기고, 메서드로 메신저를 열고 닫을 수 있어요.

설치

스니펫은 EntropyMessenger 대기열을 먼저 만들고 로더를 비동기로 불러와요. 로더가 오기 전에 호출한 메서드도 순서대로 실행돼요. 메신저 화면은 엔트로피 도메인의 iframe 안에서 열려서, 페이지의 CSS나 스크립트와 섞이지 않아요.

<script>
(function (w, d) {
  if (w.EntropyMessenger) return;
  var q = [];
  var f = function () { q.push(arguments); };
  f.q = q;
  w.EntropyMessenger = f;
  var s = d.createElement('script');
  s.async = true;
  s.src = 'https://entropy.ly/messenger/v1/loader.js';
  d.head.appendChild(s);
})(window, document);

EntropyMessenger('boot', {
  pluginKey: 'pk_live_xxxxxxxxxxxx',
  language: 'ko', // 'ko' | 'en' | 'ja'
});
</script>

</body> 바로 앞에 붙여 넣으세요. pluginKey는 공개 키라서 브라우저에 노출돼도 괜찮아요.

부팅 옵션

boot 옵션
옵션타입설명
pluginKeystring (필수)채널의 공개 키 pk_…예요.
memberIdstring로그인한 회원의 ID예요. memberHash와 함께 보내야 해요.
memberHashstring서버에서 계산한 hex(HMAC_SHA256(memberHashSecret, memberId))예요. 회원 연동
profile{ name?, email?, phone? }입력 칸을 미리 채워요. 인증을 대신하지는 않아요. 전화번호는 E.164 형식(+821012345678)이에요.
language"ko" | "en" | "ja"메신저 표시 언어예요. 빼면 브라우저 언어를 따르고, 지원하지 않는 언어면 한국어로 보여요.
hideLauncherboolean기본 버튼을 숨겨요. 직접 만든 버튼에서 open을 호출할 때 써요.
zIndexnumber위젯의 z-index예요. 기본값은 2147483000이에요.
launcherOffset{ right, bottom }데스크톱에서 버튼 위치(px)예요. 기본값은 오른쪽 30, 아래 30이에요.
mobileLauncherOffset{ right, bottom }모바일에서 버튼 위치(px)예요. 기본값은 오른쪽 16, 아래 15예요.

메서드

EntropyMessenger 메서드
호출설명
EntropyMessenger('boot', options)메신저를 시작해요. 두 번째 boot는 shutdown 전까지 무시돼요. 로그인·로그아웃 뒤에는 shutdown 후 다시 boot 하세요.
EntropyMessenger('shutdown')위젯을 내리고 세션을 지워요. 등록한 콜백도 지워져요. 로그아웃할 때 꼭 호출하세요.
EntropyMessenger('show') / ('hide')메신저 버튼을 보이거나 숨겨요. hide는 열린 창도 닫아요.
EntropyMessenger('open')메신저 창을 홈 화면으로 열어요.
EntropyMessenger('openConversation', id)특정 대화를 열어요.
EntropyMessenger('openNew', kind?)새 대화를 시작해요. kind는 'support'(기본) 또는 'feedback'이에요. 인증 전인 사용자는 본인인증부터 거쳐요.
EntropyMessenger('updateUser', profile)이름, 이메일, 전화번호 미리 채움 값을 바꿔요.

이벤트

EntropyMessenger 이벤트
호출콜백 인자
EntropyMessenger('onShow', cb)없음 — 창이 열린 뒤
EntropyMessenger('onHide', cb)없음 — 창이 닫힌 뒤
EntropyMessenger('onUnreadCountChanged', cb)count: number — 읽지 않은 메시지 수가 바뀔 때
직접 만든 버튼에 배지 달기
EntropyMessenger('boot', { pluginKey: 'pk_live_xxxxxxxxxxxx', hideLauncher: true });

const button = document.querySelector('#help-button');
button.addEventListener('click', () => EntropyMessenger('open'));
EntropyMessenger('onUnreadCountChanged', (count) => {
  button.dataset.badge = count > 0 ? String(count) : '';
});

화면 배치

  • 데스크톱: 56px 버튼이 오른쪽 아래(30px, 30px)에 떠요. 창은 너비 430px로 버튼 위에 열리고, 창이 열린 동안 버튼은 닫기 버튼이 돼요.
  • 모바일(모바일 기기 또는 화면 너비 480px 이하): 44px 버튼이 오른쪽 16px, 아래 15px에 떠요. 창은 전체 화면으로 열리고, 그동안 페이지 스크롤을 잠가요.
  • Esc를 누르면 창이 닫히고 포커스가 버튼으로 돌아가요. 창 바깥을 눌러도 닫히지 않아요.

이메일·문자 알림의 링크는 채널의 returnUrl에 ?entropy_open=<conversationId>를 붙인 주소예요. 메신저는 부팅할 때 이 값을 읽어 해당 대화를 바로 열어요. returnUrl 페이지에도 스니펫이 있어야 해요.

알림 링크 예
https://example.com/support?entropy_open=cv_01J8Z3K6W2

보안 정책(CSP)과 허용 도메인

Content-Security-Policy를 쓴다면 로더를 위해 script-src에, 메신저 iframe을 위해 frame-src에 https://entropy.ly을 추가하세요. 로더 주소는 https://entropy.ly/messenger/v1/loader.js이에요. API 요청은 iframe 안에서 나가서 페이지의 connect-src는 바꾸지 않아도 돼요.

CSP 예
Content-Security-Policy: script-src 'self' https://entropy.ly; frame-src https://entropy.ly

메신저 창은 채널의 allowedOrigins에 등록된 도메인에서만 열려요. 다른 사이트에 스니펫을 붙이면 브라우저가 iframe을 막아요(frame-ancestors). 개발 환경 주소도 따로 등록하세요.

위젯 API

위젯이 내부에서 쓰는 공개 API예요. 직접 상담 화면을 만들 때만 쓰세요. 부팅에는 pluginKey를, 그 뒤로는 Authorization: Bearer <sessionToken>을 보내요. 세션 토큰은 수명이 짧고, 채널과 연락처 하나에만 쓸 수 있어요.

위젯 공개 API
요청설명
POST /v1/messenger/boot{ pluginKey, memberId?, memberHash?, profile? } → { sessionToken, expiresAt, channel, contact, verified }
POST /v1/messenger/verification/start인증 코드 보내기. 본인인증 흐름
POST /v1/messenger/verification/confirm코드 확인과 약관 동의
GET /v1/messenger/conversations내 대화 목록
POST /v1/messenger/conversations{ kind?, body, clientMsgId, attachments? } — 인증된 연락처만
GET /v1/messenger/conversations/:id/messages?before=<cursor>&limit=30
POST /v1/messenger/conversations/:id/messages{ body, clientMsgId, attachmentIds? } — 같은 clientMsgId는 한 번만 저장돼요
POST /v1/messenger/conversations/:id/read읽음 처리
POST /v1/messenger/attachments업로드 주소 발급(이미지·PDF, 용량 제한)
POST /v1/messenger/stream-ticketEventSource용 짧은 수명의 티켓
GET /v1/messenger/stream실시간 이벤트(SSE)

실시간 이벤트

GET /v1/messenger/stream은 Server-Sent Events로 message.created, conversation.updated, typing, read를 보내요. 25초마다 하트비트가 오고, 연결이 끊기면 위젯은 폴링으로 바꿔요. 브라우저의 EventSource는 헤더를 못 붙이므로 POST /v1/messenger/stream-ticket으로 받은 티켓을 ?ticket=으로 넘기세요. 스트림이 연결된 동안 연락처는 온라인으로 표시돼요.