SDK 참조
모든 Telybot SDK(Android, iOS, React Native, Flutter, Ionic)는 동일한 작은 계약을 구현합니다. 하나를 사용해 보셨다면 모두 사용하실 수 있습니다.
API
| 전화 | 주요 기능 |
|---|---|
init / initialize | Client ID를 저장합니다. 유효성을 검사하며 형식이 잘못된 경우 오류를 알립니다. |
show | 앱 위에 채팅을 표시합니다. 메시지 입력란에 넣을 질문을 선택적으로 받습니다 (0.2.0). |
dismiss | 닫기. |
isShowing | 현재 표시 여부. |
| 임베드 채팅 | 도움말 탭처럼 직접 만든 화면 안에 들어가는 채팅 (0.2.0). |
onShow / onDismiss | 채팅이 열리고 닫힐 때 알려줍니다. Android와 iOS에서 (0.2.0). |
setVisitor | 로그인한 고객의 이름, 전화번호, 이메일을 채팅의 양식에 제안합니다 (0.2.0). |
hasUnreadReply / onReply | 고객이 아직 보지 않은 팀의 답장 (0.2.0). |
질문과 함께 열기. show에 질문을 전달하면 채팅의 메시지 입력란에 들어갑니다. 고객이 읽고 보내기를 누릅니다. 질문은 링크의 #fragment에 담겨 전달되므로 서버 로그에는 절대 남지 않습니다. 한 줄로 최대 500자.
직접 만든 화면 안의 채팅. Android KeydaBotView, iOS KeydaBot.makeChatViewController 또는 SwiftUI KeydaBotView, React Native <KeydaBotChat />, Flutter KeydaBotChat, 그리고 Ionic 패키지의 embedWidget(). 닫기 버튼이 없습니다. 화면의 내비게이션이 나가는 길입니다. Android에서 뒤로 가기는 열려 있는 항목이나 장바구니를 먼저 닫습니다. 채팅이 맨 앞 화면인 동안에는 React Native와 Flutter가 대신 처리하고, 네이티브 KeydaBotView에서는 뒤로 가기 처리에서 그 goBack()를 호출합니다.
로그인한 고객. 고객의 이름, 전화번호 또는 이메일을 SDK에 전달하면 앱이 이미 알고 있는 정보를 채팅이 채워 넣습니다. 정보는 제안만 되고 전송되지는 않습니다. “상담원과 대화” 양식, 주문, 예약, 이름·전화·이메일을 묻는 환영 질문에 표시되고, 제출은 고객이 합니다. 정보는 링크의 #fragment에 담겨 전달되며, 검증된 신원이 아니라 앱의 주장입니다. 채팅이 거부할 값은 제외됩니다. 80자를 넘는 이름, 8~15자리가 아닌 전화번호, 올바른 도메인이 없는 이메일 주소입니다. Ionic의 전체 화면 채팅은 주소를 기록에 남기는 시스템 브라우저에서 열리므로 이 정보를 받지 않습니다. 임베드 위젯은 받습니다.
채팅이 닫혀 있는 동안의 답장. 고객이 상담원을 요청하고 채팅을 닫으면, 대시보드에서 보낸 답장은 대화 안에서 기다립니다. Android, iOS, React Native, Flutter SDK는 앱이 포그라운드로 돌아올 때 이를 확인하고 앱에 알려주므로, 고객이 채팅을 열기 전까지 채팅 버튼에 점을 표시할 수 있습니다. 지난 14일 안에 고객이 상담원을 요청한 채팅만 확인합니다. 백그라운드의 도움말 탭처럼 앱이 보이지 않는 곳에 로드해 둔 채팅은 읽은 것으로 치지 않습니다. 고객이 볼 때까지 점은 남아 있습니다. 푸시 알림이 아닙니다. 답장은 앱이 열릴 때 확인됩니다.
그 외에는 의도적으로 아무것도 없습니다. 메시지 전송 API도, 사용자 신원 호출도 없습니다. 둘 다 아직 끝까지 동작하지 않기 때문이며, 동작하지 않는 메서드는 없는 메서드보다 나쁩니다.
모든 SDK가 여는 URL
{baseUrl}/chat/{clientId}baseUrl은 https://telybot.com로 기본 설정되며, 스테이징이나 자체 호스팅 설치 시 플랫폼별로 재설정할 수 있습니다.
웹 뷰를 사용하는 이유와 비용
플랫폼에서 제공하는 단일 채팅 인터페이스를 모든 환경에서 불러옵니다.
제공 기능: 대시보드에서 소유자가 변경한 사항(강조 색상, 환영 메시지, 봇 이름, 라이브 전환 등)은 별도의 릴리스 없이 모든 앱에 즉시 적용됩니다. 수정 사항이 한 번에 모든 곳에 반영됩니다. 채팅은 모든 플랫폼에서 동일하게 유지됩니다.
비용 안내: 채팅을 위해서는 연결이 필요합니다. 오프라인 모드는 지원하지 않으며, 푸시 알림은 아직 제공되지 않습니다.
나중에 발견하는 것보다 배포 전에 미리 아시는 것이 좋습니다.
각 SDK가 보장하는 사항
- 외부 링크 연결. 다른 출처로 연결되는 링크는 채팅창을 대체하지 않고 시스템 브라우저에서 열립니다. 이 기능이 없으면 푸터 링크를 한 번만 눌러도 대화가 종료되어 돌아올 방법이 없습니다.
- 대화 연속성. DOM 스토리지가 활성화되어 있어 앱을 닫았다가 다시 돌아온 고객은 이전 대화 내용을 그대로 이어서 볼 수 있습니다(24시간 유지).
- 키보드가 입력창을 가리지 않습니다.
- 안전 영역 준수 — 노치나 홈 표시기 아래에 채팅이 그려지지 않습니다.
- 앱 충돌이 발생하지 않습니다. 로드 실패 시 재시도 화면이 표시됩니다.
- 분석 도구, 기기 식별자, 타사 종속성이 없습니다. Telybot SDK를 추가해도 앱에 추적기가 추가되지 않습니다.
- 뒤로 가기는 고객이 보고 있는 것을 먼저 닫습니다. Android에서 열려 있는 항목, 장바구니, 예약 위에서 뒤로 가기를 누르면 그것이 먼저 닫히고, 그다음에 채팅이 닫힙니다 (SDK 0.2.0 이상).
채팅 안에서
이 모든 것은 호스팅된 페이지에서 오기 때문에 SDK 업데이트 없이 모든 앱에 적용됩니다:
- 제안 버튼이 있는 환영 메시지, 봇에 설정된 언어로 표시됩니다.
- 대화는 기기에 24시간 보관되며, 채팅은 방문자 ID를 만들지 않습니다. 웹사이트에서는 대화가 브라우저 탭 하나만큼 지속됩니다. (Ionic SDK의 전체 화면 채팅에서는 0.2.0이 필요합니다.)
- 주문과 예약, 업체가 받는 경우: 장바구니, 예약 날짜와 시간, 주문이나 예약이 너무 오래 기다렸을 때 업체에 전화할 수 있는 링크, 확정된 예약의 “캘린더에 추가”.
- 첨부 파일: 사진(JPEG, PNG, WebP, GIF)과 PDF, DOCX, TXT, CSV, MD 파일. 첨부 버튼에는 Android와 Flutter SDK 0.1.4 이상이, 문서에는 Flutter 0.2.0이 필요합니다.
- “캘린더에 추가”는
.ics파일로 연결되는 링크입니다. iOS는 이를 구독할 캘린더로 캘린더 앱에서 엽니다. Android는 휴대폰의 캘린더 앱이.ics파일을 가져올 수 있으면 그 앱을 제안하고(현재 Google 캘린더는 가능합니다), 그렇지 않으면 브라우저가 파일을 다운로드합니다.
Client id 형식
kb_live_ followed by 8-48 hexadecimal characters그 외의 모든 것은 초기화 단계에서 거부되며 고객에게 404 오류를 표시하지 않습니다. Client ID는 설계상 공개되어 있으며 위젯이 포함된 모든 웹사이트에서 볼 수 있습니다. 이는 계정을 읽거나 변경할 수 있는 권한을 포함하지 않습니다. 제한 및 보안을 확인하세요.
출처
공개, MIT 라이선스: github.com/telybotai/telybot-Sdks. 모든 패키지가 준수해야 하는 공통 계약은 해당 저장소 상단의 CONTRACT.md에 있습니다.