위젯 개요

위젯은 웹사이트에 붙이는 상담 창이에요. 방문자는 페이지를 떠나지 않고 에이전트와 채팅하거나 통화하거나 전화를 요청하고, 그 내용은 고객에 방문자별로 쌓여요.

위젯으로 할 수 있는 일

위젯 하나에 유형을 하나 정해요. 방문자가 무엇을 하러 오는지에 맞추세요.

채팅

영업시간 밖에도 질문에 답하고 문의를 받아요. 문의가 많고 글로 충분할 때 고르세요.

음성

번호를 찾아 걸지 않고 브라우저에서 바로 통화하고, 통화 중에 텍스트도 보낼 수 있어요. 말로 설명하는 게 빠른 문의에 고르세요.

전화 콜백

방문자가 번호를 남기면 에이전트가 전화를 걸어요. 지금 통화하기 어려운 방문자까지 놓치지 않으려면 고르세요.

어느 유형이든 설치 코드로 방문자 ID와 페이지 값을 넘길 수 있어요. 재방문 고객을 알아보거나 상품 정보를 프롬프트에 넣은 채로 상담을 시작하세요.

설치하고 게시하기

위젯 만들기

배포 > 위젯에서 위젯 만들기를 누르고 위젯 제목, 위젯 유형, 에이전트를 고른 뒤 만들기를 누르세요. 제목은 위젯 창 위쪽에 보여요. 전화 콜백은 발신에 쓸 전화번호가 있어야 하니 위젯 유형의 준비할 것을 먼저 보세요. 색, 위치, 인사 메시지, 자동 열기는 모양과 메시지에서 바꾸고 화면 아래 미리보기로 확인하세요.

설치 코드 붙여 넣기

오른쪽 위 임베드 코드를 눌러 복사하고 웹페이지의 <head>나 <body>에 붙여 넣으세요. 아래는 형식 예시이고, data-widget-id에는 복사한 코드의 공개 ID가 들어 있어요. API 키나 에이전트 ID는 넣지 않아도 돼요.

<script
  src="https://www.tryvox.co/widget-v1.js"
  data-widget-id="wgt_..."
  async
></script>

모바일에서 위젯이 전체 화면으로 열리려면 페이지 <head>에 <meta name="viewport" content="width=device-width, initial-scale=1">가 있어야 해요. 없으면 브라우저가 페이지를 데스크톱 폭으로 잡고 축소해 위젯도 같이 작아져요. 스크립트는 iframe 안이 아니라 최상위 문서에 넣으세요. iframe 안에 넣으면 위젯이 그 iframe 크기 안에서만 열려요.

설치 도메인 확인하기

설치 도메인은 위젯이 동작할 사이트예요. 대시보드에서 만든 위젯은 기본값 *로 모든 도메인에서 동작하니 처음에는 그대로 둬도 돼요. example.com처럼 특정 도메인만 넣으면 그 사이트와 하위 도메인에서만 동작하므로, 개발 중에는 localhost와 127.0.0.1을 함께 넣어야 로컬에서 보여요. 목록을 비우면 게시해도 어느 사이트에서도 보이지 않아요.

게시하기

사이트에 게시를 켜면 설치한 웹사이트에 위젯이 나타나요. 게시하기 전에는 스크립트를 설치해도 보이지 않고, 이미 열어 둔 페이지는 다시 열어야 보여요.

연결 확인

설치한 웹페이지를 새로 열어 위젯이 나타나고 상담 창이 열리는지 확인하세요.
채팅 유형이라면 시험 메시지를 보내 에이전트의 답변을 확인하세요.
시험 채팅을 마친 뒤 기록의 채팅 탭에서 보낸 메시지와 답변이 남았는지 확인하세요.

게시본 바꾸기

게시 중인 위젯을 고치고 저장하면 게시 검토 창이 열려 지금 게시본과 새 버전의 차이를 보여 줘요. 저장하고 버전 3 게시처럼 새 버전 번호가 붙은 버튼을 누르면 설치한 모든 사이트에 적용되고, 방문자에게는 페이지를 다시 열 때부터 반영돼요.

사이트에 게시를 끄고 확인 창에서 게시 해제를 누르면 새로 페이지를 여는 방문자부터 위젯이 보이지 않아요. 설정은 남아 있어서 다시 켜면 새 버전으로 게시돼요. 목록의 삭제는 되돌릴 수 없고, 설치한 사이트에서 바로 동작을 멈춰요.

방문자와 페이지 정보 넘기기

재방문 고객을 알아볼 때: 서비스가 관리하는 사용자 키를 data-visitor-id로 넘기세요. 채팅과 브라우저 통화가 같은 고객으로 이어져요. 규칙은 방문자 식별에 있어요.
상품이나 주문 정보를 프롬프트에 넘길 때: 에이전트 프롬프트의 {{변수}}에 들어갈 값을 data-dynamic으로 페이지마다 넘기세요. 위젯의 동적 변수에 등록한 키만 반영되고 값은 문자열만 돼요. 전화 콜백 폼에 방문자가 입력한 값이 있으면 그 값이 먼저예요. 변수 정의는 동적 변수에 있어요.

<script
  src="https://www.tryvox.co/widget-v1.js"
  data-widget-id="wgt_..."
  data-visitor-id="u_8f3c2a9d"
  data-dynamic='{"product_name":"프리미엄 요금제"}'
  async
></script>

설치 페이지와 연동하기

게시한 위젯이면 따로 설정하지 않아도 페이지 스크립트에서 바로 제어할 수 있어요.

페이지 버튼으로 위젯을 열 때: window.VoxWidget.open()을 부르세요. 이미 열려 있으면 그대로예요. 닫을 때는 window.VoxWidget.close()를 쓰세요.
위젯 상태에 따라 페이지 요소를 바꿀 때: vox:widget 이벤트를 받으세요. 열리거나 닫힐 때마다 한 번 와요.

<button id="help">상담하기</button>
<div id="promo">프로모션 배너</div>
<script>
  document.getElementById("help").addEventListener("click", () => {
    window.VoxWidget.open();
  });

  window.addEventListener("vox:widget", (event) => {
    if (event.detail.type === "open") {
      document.getElementById("promo").hidden = true;
    }
  });
</script>

detail.type은 open이나 close이고, detail.widget_id는 설치 코드의 공개 ID예요.

설치 속성

속성	필수	설명
`data-widget-id`	예	위젯마다 발급되는 공개 ID예요. `wgt_`로 시작해요
`data-visitor-id`	아니요	서비스가 관리하는 방문자 ID예요. 빼면 브라우저마다 자동으로 만들어요
`data-dynamic`	아니요	페이지에서 덮어쓸 동적 변수예요. JSON 객체이고 값은 문자열만 돼요

문제가 생겼을 때

위젯이 사이트에 보이지 않아요

사이트에 게시가 켜져 있는지, 설치 도메인에 그 사이트가 들어 있는지 확인하세요. 방문자에게는 페이지를 다시 열 때부터 반영되니 게시 직후라면 페이지를 새로 여세요.

방문자에게 잠시 뒤 다시 시도하라는 안내가 떠요

정상 사용에서도 걸리면 남용 방지의 시작 한도를 직접 설정으로 올리세요. 한 방문자가 1분 동안 시작할 수 있는 대화와 통화 수를 넘긴 경우예요. 표준은 분당 5회, 엄격은 분당 2회이고, 직접 설정은 1~30회로 정해요. 반대로 한 방문자가 너무 자주 시작하면 엄격으로 낮추세요.

설치 코드의 data-dynamic 값이 반영되지 않아요

키 이름이 동적 변수에 등록한 변수와 같은지, 값이 문자열인지 확인하세요. 등록하지 않은 키와 잘못된 JSON은 무시하고 게시된 기본값을 써요.

시작하기

구축

배포

발신

모니터링

설정

정책

위젯으로 할 수 있는 일

채팅

음성

전화 콜백

설치하고 게시하기

연결 확인

게시본 바꾸기

방문자와 페이지 정보 넘기기

설치 페이지와 연동하기

설치 속성

문제가 생겼을 때

관련 문서

​위젯으로 할 수 있는 일

채팅

음성

전화 콜백

​설치하고 게시하기

​연결 확인

​게시본 바꾸기

​방문자와 페이지 정보 넘기기

​설치 페이지와 연동하기

​설치 속성

​문제가 생겼을 때

​관련 문서

위젯으로 할 수 있는 일

설치하고 게시하기

연결 확인

게시본 바꾸기

방문자와 페이지 정보 넘기기

설치 페이지와 연동하기

설치 속성

문제가 생겼을 때

관련 문서