JavaScript API: 페이지에서 위젯 제어

window.ReactiveChat의 모든 명령: 열기·닫기, 메시지 전송, 사용자 식별, 안내 말풍선·홍보 카드 제어, 투어 시작, 세션 조회의 매개변수, 반환값과 로드 전 큐.

위젯은 전역 객체 window.ReactiveChat 하나를 제공합니다. 모든 명령을 함수 형식으로 호출합니다.

ReactiveChat('command', argument1, argument2);

기본 명령 이름은 일반 채팅 위젯을 따릅니다(boot, shutdown, open, identify, update, track 등). 따라서 전환 작업이 적습니다.

로드 전 큐

로더가 먼저 ReactiveChat을 만듭니다. 코어 로드 전에는 모든 호출을 ReactiveChat.q에 기록하며 이후 코어가 순서대로 처리합니다. 호출은 사라지지 않습니다.

코드가 로더 태그 전에 실행될 수 있으면 앞에 다음 줄을 넣습니다.

window.ReactiveChat = window.ReactiveChat || function () {
  (window.ReactiveChat.q = window.ReactiveChat.q || []).push(arguments);
};

두 가지 결과가 있습니다.

로드 전 모든 반환값은 undefined입니다. 반환값이 있는 getSession, isOpen, tour 등의 명령은 ready 후 사용합니다(이벤트 참조).
명령은 로드를 유발합니다. boot, update, track, identify 이외의 명령은 모두 command 트리거로 코어를 즉시 로드합니다. 따라서 identify를 미리 호출해도 로드 비용은 없습니다.

명령은 예외를 던지지 않습니다. 오류는 undefined를 반환하며 알 수 없는 명령은 무시합니다(data-rc-debug="true"이면 콘솔에 표시).

ReactiveChat('on', 'ready', function () {
  var s = ReactiveChat('getSession');
  console.log('Visitor', s && s.visitorId);
});

시작과 종료

boot (cfg?: object) – 첫 호출은 script 태그 속성과 같은 필드(camel case, 예: { siteKey, locale, theme, position, brand })로 설정하고 시작합니다. 이후 호출은 locale, theme, dnd, autoOpen, strings, position만 반영합니다. 큐에 boot가 없으면 코어가 직접 호출합니다.
shutdown () – 이 페이지에서 창, 연결과 관찰자를 제거하고 ReactiveChat을 단순 큐로 초기화합니다. 페이지 새로고침 없는 재시작은 의도하지 않았습니다.

ReactiveChat('boot', { locale: 'en', theme: 'dark' });

창

open (opts?) – 창을 엽니다. opts는 옆에 창을 표시할 요소 또는 객체입니다.
anchor(요소, 선택 사항) – 이 요소 옆에 엽니다. 없으면 일반 위치입니다.
message(문자열, 선택 사항) – 입력란에 최대 200자를 넣으며 전송하지 않습니다.
tab(msg | home | help, 선택 사항) – 탭 선택. anchor 자체에 data-rc-message나 data-rc-tab이 있으면 적용하고 호출의 명시적 값이 우선합니다. 로드 전에는 요청을 기억합니다.
close () – 창을 닫습니다.
toggle () – 열림·닫힘을 전환합니다.
isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Question about my order', tab: 'msg' });
});

메시지와 대화

sendMessage (text: string) – 방문자가 작성한 것처럼 대신 전송합니다. 같은 제한을 적용합니다. 방문자의 행동 후에만 사용하고 요청 없이 보내지 않습니다.
newConversation () – 새 대화를 시작합니다.
leaveMessage () – 상담 가능한 사람이 없을 때 메시지 남기기 양식을 엽니다.
startConversation (text: string, suche?: string) – 새 대화를 시작하고 준비되는 즉시 text를 보냅니다. Smart Answer가 검색 질문을 채팅으로 이어갈 때 사용합니다.
continueConversation (id: string, text: string) – 기존 대화에 text를 이어갑니다. id는 [0-9A-Za-z_-]{1,64}에 일치해야 하며 아니면 새 대화를 시작합니다. Smart Answer 인계에도 사용합니다.

방문자와 맥락

identify ({ userId, email, name, userHash, exp }) – 로그인 사용자를 알리고 다른 필드는 폐기합니다. 서버에서 계산한 유효한 userHash가 없으면 미확인입니다. 이름과 이메일은 상담원 화면에 보이지만 고객 데이터나 다른 사람의 대화 기록에 접근할 권한은 주지 않습니다. 서명은 방문자 식별에 있습니다.
update (attrs: object) – MousePlayer 연결에 속성을 전달합니다(MousePlayer 사용 시만 해당).
track (name: string, meta?: object) – 주요 진행 시점을 알립니다. meta의 맥락 목록에 있는 url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock 등은 어시스턴트와 상담원에게 페이지 맥락으로 전달합니다. 그 밖의 필드는 폐기합니다. 방문자 식별과 맥락 전달 참조.
getSession () → { sessionId, visitorId, tabId } 또는 null.
getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – 위젯의 연결 출처이며 같은 주소가 필요한 자체 스크립트용입니다.
portal (basis?: string) → boolean – 새 탭으로 고객 포털을 열고 확인된 신원을 전달합니다. 확인된 사용자가 없으면 false입니다. basis는 선택적인 자체 https:// 출처입니다.

ReactiveChat('track', 'produkt_angesehen', {
  page_type: 'product', product_id: 'SKU-4711', price: 49.9, currency: 'EUR', in_stock: true
});

언어와 테마

setLocale (locale: 'de' | 'en' | 'pl') – 언어 전환. 브라우저에서 선택을 기억합니다.
setTheme ('light' | 'dark' | 'auto').

안내 말풍선, 홍보 카드와 투어

showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – 채팅 버튼에 작은 말풍선을 표시합니다. quickReplies는 최대 3개, ttlMs는 0–120000(기본값 15000)입니다. 창 열림, 버튼 숨김, 방해 금지, 대화 진행 중 또는 빈도 제한이면 표시하지 않고 false입니다.
show (text | object) → boolean – 짧은 형식: ReactiveChat('show', 'Questions about shipping?').
hideTeaser / hide () – 말풍선 숨김.
promo (false | true | object) – 이 페이지의 홍보 카드를 숨기거나 다시 표시하거나 자체 필드(titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe)로 덮어씁니다.
tour (id: string) → boolean – 계정에서 만든 제품 투어를 시작하고 알 수 없는 ID면 false입니다. 설정은 사용자 지정에 있습니다.
tourStop () – 진행 중 투어 종료.

A/B 테스트

abVariant () → { test, variant, qa } 또는 null – 방문자가 보는 실험안.
abGoal () – 실행 중 테스트의 목표 달성을 알립니다(예: 감사 페이지).

ReactiveChat('on', 'ready', function () { ReactiveChat('abGoal'); });

실행 중 디자인 변경

setBrand (marke: object) – 재구성 없이 색상·형태를 덮어씁니다. null로 값을 제거합니다.
brandCheck () → 측정된 대비 목록 { paar, ist, soll }.
brandTokens () → 실제 적용된 디자인 값.
setStart (startseite: object) – 실행 중 시작 화면 설정(미리보기용).

객체 필드는 사용자 지정에 있습니다.

이벤트

on (name, callback) / off (name, callback) – 이벤트 구독·해제. 목록과 페이로드는 이벤트에 있습니다.

객체에서 직접 사용

로드 후 일부 명령은 ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation() 메서드로도 사용할 수 있습니다. ReactiveChat.version은 코어 버전입니다. 로드 전에는 이 메서드가 없으므로 함수 형식이 안전합니다.

제공되지 않는 명령

destroy, reset, setUser, send, setConsent, trackPage, navigate 명령은 없습니다. 동의는 동의 플랫폼 또는 data-rc-consent로 제어하며(개인정보 보호 연동), 페이지 변경은 자동 감지합니다(SPA). 로그아웃은 방문자 식별을 참조합니다.

다음: 이벤트

최종 업데이트: 2026-10-25