위젯 API

개발자나 자체 버튼으로 채팅을 열고 싶은 분들을 위한 기능입니다.

설치하기

<script src="https://keyda.in/business/widget.js"
        data-key="kb_live_your_key_here" async></script>

스크립트 태그에는 src와 data-key만 있으면 됩니다. 색상, 위치, 인사말, 언어 등 그 외 모든 설정은 대시보드에서 관리하므로 변경할 때마다 사이트를 다시 배포할 필요가 없습니다.

위젯은 설치 → 봇이 사용하는 언어에서 설정한 언어로 표시됩니다: 버튼, 입력 안내, 알림뿐 아니라 레이아웃 방향(아랍어와 우르두어는 오른쪽에서 왼쪽)까지 포함됩니다. 문구는 위젯 설정과 함께 전달되므로 별도의 요청이 필요 없고 직접 번역할 것도 없습니다.

모드

플로팅(기본값). 모서리에 있는 런처 버튼을 누르면 채팅창이 열립니다.

인라인. 페이지에 빈 컨테이너를 배치하면 채팅창이 그 안을 채웁니다:

<div data-keyda-bot style="height:520px"></div>

컨테이너에는 높이 값이 필요합니다. 인라인 모드에서는 채팅창이 항상 표시되므로 열거나 닫을 요소가 없습니다.

JavaScript API

스크립트가 로드되면 window.KeydaBot에서 사용 가능:

예시 — 직접 만든 "문의하기" 버튼으로 채팅창 열기:

<button onclick="KeydaBot.open()">Chat with us</button>

페이지에서의 동작 방식

• 패널은 런처 버튼 위쪽으로 열리며, 런처 버튼은 제자리에 유지되어 닫기 컨트롤 역할을 합니다. 버튼을 다시 누르거나, 헤더의 ✕를 누르거나, Escape 키를 누르면 채팅이 닫힙니다.
• 방문자는 헤더에서 패널을 확장할 수 있습니다. 창 높이에 맞춰 최대 760px 너비까지 커지며, 브라우저가 이 설정을 기억합니다. 모바일에서는 패널이 전체 화면으로 표시되므로 해당 제어 버튼은 나타나지 않습니다.
• 로고 크기 설정은 버튼이 아니라 로고를 변경합니다. 런처는 크기를 그대로 유지한 채 내부의 로고만 커집니다. 버튼 자체의 크기 — 소형, 중형, 대형 — 를 조정하는 것은 버튼 크기(설치 → 외관)이며, 어떤 모양이든 적용됩니다.
• 버튼 모양은 4가지입니다: 라벨이 있는 알약형, 원형 버블, 둥근 사각형, 꼬리가 달린 말풍선형입니다. 꼬리는 페이지를 향한 쪽에 위치합니다.
• 모든 요소가 shadow root 내에서 렌더링되므로 귀하의 CSS가 위젯을 손상시키거나 위젯의 CSS가 귀하의 사이트에 영향을 줄 수 없습니다.
• 패널은 방문자가 열 때만 로드되므로 페이지 속도가 느려지지 않습니다.
• 방문자가 다시 돌아오면 대화는 24시간 동안 이어지며, 그 이후에는 새로 시작됩니다. 패널을 다시 열면 파일을 포함한 이전 대화 내용이 복원되며, 답변을 기다리던 환영 플로우 질문도 그대로 이어집니다.
• 입력창의 클립 아이콘을 사용하면 방문자가 메시지당 사진이나 문서를 최대 3개까지 첨부할 수 있습니다(크기와 형식은 제한 및 보안 참고). 사진은 업로드 전에 브라우저에서 크기가 축소되므로, 1200만 화소 사진도 수백 킬로바이트 수준으로 전송됩니다. 설치에서 파일 전송 기능을 끄면 버튼이 사라집니다.
• 환영 플로우는 일반적인 말풍선 형태로 진행됩니다: 선택지는 말풍선 아래 버튼으로 표시되고, 선택 사항인 단계에서는 건너뛰기 버튼이 나타나며, 입력창의 안내 문구가 질문으로 바뀝니다. 완료된 플로우는 방문자의 브라우저에 30일간 기억됩니다.
• 어시스턴트에 연결할 수 없는 경우, 위젯은 짧은 메시지를 표시하며 페이지에 오류를 발생시키지 않습니다.

앱 SDK 내부에서

동일한 채팅이 모든 SDK에서 작동하므로 첨부 파일과 환영 플로우 기능은 앱을 새로 배포하지 않아도 적용됩니다 — 단, 한 가지 예외가 있습니다. 웹뷰에서 파일 선택 화면을 여는 것은 호스트 앱의 역할입니다. iOS, React Native, Ionic 패키지는 이미 이를 지원하며, Android와 Flutter는 SDK 0.1.4 이상이 필요합니다. 이전 버전에서는 위젯이 해당 환경을 인식해 동작하지 않는 버튼을 표시하는 대신 클립 아이콘을 숨깁니다.