Kakao i Web Chatbot::SDK 개발 프로세스

페이지 이동경로

사전 작업

Kakao i Web Chatbot SDK를 사용하기 전에 필요한 작업은 다음과 같습니다.

안내
사전 작업 수행과 관련한 자세한 설명은 카카오엔터프라이즈 담당자에게 문의하시기 바랍니다.
Kakao i Web Chatbot SDK 사전 작업
구분 항목
① 기본 정보 생성 대표계정 생성
서비스명(serviceName) 및 앱 이름 정의
Bot 생성 및 API(Skill) 개발
- Skill은 Bot의 비즈니스 로직을 수행하는 API를 의미함
Bot Builder에서 수행 작업 채널 생성
서비스 ID 생성
Bot 만들기 권한 설정
시나리오 생성
Kakao Developers에서 수행 작업 앱 등록 및 앱 패키지 생성
앱 키 획득
- 앱 등록 후, 앱 키는 자동 생성됨(Kakao Developers > 앱설정 > 요약정보)
④ 앱 서버 등록 카카오엔터프라이즈 앱 서버에 서비스 추가

개발 가이드

Web Chatbot을 구현하기 위한 전체 개발 프로세스는 다음과 같습니다.

Chatbot 구성하기

카카오엔터프라이즈 담당자와 협의를 통해 Web Chatbot 관련 사전 협의를 진행 후 Chatbot을 구성합니다. Chatbot 구성이 완료되면, 카카오엔터프라이즈 담당자는 고객사에게 SDK 초기화 시 필요한 서비스명(serviceName) 정보를 전달합니다.

SDK 스크립트 추가하기

다음의 HTML 스크립트 태그를 추가하여 SDK를 설치합니다. SDK Version은 SemVer 양식으로 작성됩니다.

안내
2022년 7월부터 반드시 아래 경로로 변경하여 사용하시기 바랍니다.

코드예제SDK 스크립트 추가

<script type="text/javascript" src="https://s.kakaoicdn.net/webchatbot/prod/js/latest/kakaoi.js?1"></script>

SDK 스크립트 추가
항목 설명
script type text/javascript로 고정
src 설치할 SDK 저장 경로
- 경로 뒤에 붙은 ‘?1’은 SDK 업데이트 시 이전 캐시를 제거하기 위한 Revision number
안내
SDK 스크립트 추가 과정에서 403 에러가 발생하는 경우 CORS header 설정을 해제하면 정상적으로 호출됩니다.

SDK 초기화하기

다음 메서드를 호출하여 SDK를 초기화합니다. 이때, 카카오엔터프라이즈 담당자로부터 사전에 전달받은 serviceName(서비스명)을 입력해야 합니다.

코드예제SDK 초기화

Kakaoi.init({
	serviceName: "string", 
})

SDK 초기화
파라미터 타입 필수 여부 설명
serviceName String 필수 카카오엔터프라이즈 담당자로부터 전달받은 서비스명 정보

코드예제SDK 초기화 Sample Code

Kakaoi.init({
	serviceName: "service name", 
})

Chatbot UI 활성화하기

Web Chatbot을 사용하기 위해, createChat() 메서드를 호출하여 채팅 UI를 활성화합니다. createChat() 메서드로 생성되는 UI에는 토큰 발급, 채팅 전송 등 Chatbot을 사용하는데 필요한 기능들이 내장되어있습니다.

코드예제Chatbot UI 활성화


Kakaoi.UI.createChat({
	title: "string", 
	subTitle: "string",
	profileName: "string",
	profileImageUrl: "string",
	profileImageBorderLess: boolean,
	backgroundImageUrl: "string",
	inputPlaceholder: "발화를 입력하세요", 
	bubbleTextColor: "string",
	bubbleBackgroundColor: "string",  
	activeKeyword: "string", 
	quickReplyColor: "string",
	quickReplyButtonBorderColor: "string",
	quickReplyButtonTextColor: "string",
    textMasking: boolean,
	useCustomFloatingButton: boolean,
	customMenus: [{
        id: number,
		title: "string",
		icon: "string",
	}, ...],
	customMenuTextColor: "string",
	customMenuBackgroundColor: "string",
	onCustomMenuClick: (id) => {
    },
	onChatSend: (text) => {
	},
	onChatReceive: (payloads) => {
	},
    blockButtonClickInterceptor: (buttonInfo) => { 
	},
	closeButtonClickInterceptor: (e) => {
	},
	floatingButtonClickInterceptor: (e) => {
	},
    onFileUpload: (inputElement) {
	},
    onExitCounselingButtonClick: () => {
    },
	onKeyDownUserChat(text) => {
	} 
});

Chat UI 활성화 메서드 목록
메서드 타입 필수 여부 설명
Method 필수 채팅방 생성
title String 선택 채팅방 타이틀 영역에 표시되는 텍스트
- 띄어쓰기 포함 15자 이내
- 이모지 및 특수기호 가능
subTitle String 선택 Chatbot의 상태를 표시하는 텍스트
- 봇과 대화중 / 상담사와 대화중으로만 표시
profileName String 선택 Bot의 이름
- 띄어쓰기 포함 15자 이내
- 이모지 및 특수기호 가능
profileImageUrl String 선택 프로필로 사용할 URL 또는 Base64 이미지
profileImageBorderLess Boolean 선택 프로필 이미지 테두리 적용 여부
true: 프로필 이미지 테두리 미적용
false(기본값): 이미지 테두리 적용
backgroundImageUrl String 선택 채팅방 배경으로 사용할 URL 또는 Base64 이미지
inputPlaceholder String 선택 사용자 채팅 입력 필드 내의 도움말
- 기본값: 발화를 입력하세요
bubbleTextColor String 선택 사용자 말풍선 텍스트색
- Hex Code(#ffbbcc)
bubbleBackgroundColor String 선택 사용자 말풍선 배경색
- Hex Code(#ffbbcc)
activeKeyword String 선택 채팅창 활성화 시 웰컴 블록 호출로 사용할 키워드
- 카카오엔터프라이즈와 협의 필요
quickReplyColor String 선택 퀵리플라이 영역 배경색
- Hex Code(#ffbbcc)
quickReplyButtonBorderColor String 선택 퀵리플라이 버튼 테두리색
- Hex Code(#ffbbcc)
quickReplyButtonTextColor String 선택 퀵리플라이 버튼 텍스트색
- Hex Code(#ffbbcc)
textMasking Boolean 선택 개인 민감정보 마스킹
- 민감정보 마스킹 적용 여부
- 주민등록번호, 이메일, 전화번호, 계좌번호 해당
- 6자~20자의 연속된 숫자
true: 민감정보 마스킹 적용
false(기본값): 마스킹 미적용
useCustomFloatingButton Boolean 선택 플로팅 버튼 커스텀 여부
true: 고객사 커스텀 플로팅 버튼 사용
false(기본값): 기본 제공 버튼 사용
Array 선택 커스텀 메뉴 항목
- 메뉴 세 개 또는 여섯 개 구성만 선택 가능
id Number 필수 커스텀 메뉴 클릭 이벤트 구분을 위한 ID 값
title String 선택 커스텀 메뉴명
- 띄어쓰기 포함 6자 이내
- 이모지 및 특수기호 가능
icon String 선택 커스텀 메뉴 아이콘 타입
- 색상 흰색(#ffffff), 검정(#000000) 중 선택
- 실제 아이콘은 부록. 커스텀 메뉴 아이콘 참고
box: 택배 박스 아이콘
point: 캐시 포인트 아이콘
my: 사용자 아이콘
home: 집 아이콘
download: 다운로드 아이콘
headset: 헤드셋 아이콘
call: 전화 아이콘
site: 지구본 아이콘
faq: i(인포메이션) 아이콘
noti: 확성기 아이콘
coupon: 쿠폰 아이콘
event: 선물 아이콘
movie: 재생 버튼 아이콘
buy: 쇼핑백 아이콘
cart: 쇼핑카트 아이콘
delivery: 택배차 아이콘
news: 신문 아이콘
menu: 메뉴판 아이콘
storeinfo: 가게 + i 아이콘
stamp: 도장 아이콘
botorder: 봇 아이콘
time: 시계 아이콘
location: 위치핀 아이콘
membership: 바코드 아이콘
qr: QR 인식 아이콘
more: 더보기 아이콘
push: 알림종 아이콘
recommend: 알전구 아이콘
category: 카테고리 아이콘
ranking: 트로피 아이콘
setting: 톱니바퀴 아이콘
popular: 하트 아이콘
reservation: 체크 아이콘
like: 별 아이콘
sale: % 아이콘
product: 상품 태그 아이콘
info: 연필 아이콘
service: 물음표 아이콘
new: N 아이콘
cash: 동전 아이콘
document: 서류 아이콘
customMenuTextColor String 선택 커스텀 메뉴 텍스트색
- Hex Code(#ffbbcc)
customMenuBackgroundColor String 선택 커스텀 메뉴 배경색
- Hex Code(#ffbbcc)
onCustomMenuClick() Method 선택 커스텀 메뉴 클릭 시 customMenus의 id 값을 반환하는 콜백 메서드
onChatSend() Method 선택 사용자 발송 텍스트를 고객사가 구독하는 리스너
ex 1) 고객사의 로그 시스템에 대화 내용을 적재
ex 2) 고객사의 상담 시스템에 전송
onChatReceive() Method 선택 Bot이 발송한 응답을 고객사가 구독하는 리스너
blockButtonClickInterceptor() Method 선택 Bot 응답 구성요소 중 버튼 블록 클릭 시 수행할 동작을 커스터마이징하는 메서드
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
- 버튼 블록의 속성(label, linkUrl 등)은 buttonInfo에서 확인 가능
true: 메서드 실행 종료 후 기본 동작(링크 연결, 채팅 자동 입력 등) 수행
false: 기본 동작을 수행하지 않음
closeButtonClickInterceptor() Method 선택 창닫기 버튼 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
true: 기본 동작(채팅방 닫힘)을 실행시켜주는 반환값
false: 고객사가 구현한 동작을 실행
floatingButtonClickInterceptor() Method 선택 플로팅 버튼 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
true: 기본 동작(채팅창 열림)을 실행시켜주는 반환값
false: 고객사가 구현한 동작을 실행
onFileUpload() Method 선택 파일 업로드를 구독하는 리스너
- showUploadButton() 참고
onExitCounselingButtonClick() Method 선택 [상담 종료] 버튼 클릭을 구독하는 리스너
- showExitCounselingButton() 참고
onKeyDownUserChat() Method 선택 사용자 발화 입력값을 반환하는 메서드

Sample Code

다음은 Kakao i Web Chatbot SDK를 사용하여 구현한 Web Chatbot 화면과 이때 사용된 코드 예제입니다.

Chatbot 화면

그림Chatbot 화면

코드예제Chatbot UI Sample Code

Kakaoi.UI.createChat({
	title: "챗봇", 
	subTitle: "봇과 대화중",
	profileName: "KakaoEnterprise", 
	profileImageUrl: "https://daum.net/some.png", 
	bubbleBackgroundColor: "#aabbcc", 
	bubbleTextColor: "#aabbcc", 
	activeKeyword: "시작", 
	blockButtonClickInterceptor: (buttonInfo) { 
	},
	onChatSend: (text) {
	},
	onChatReceive: (payloads) {
	},
	closeButtonClickInterceptor: (e) {
	},
	floatingButtonClickInterceptor: (e) {
	},
});
안내
SDK에서 제공하는 메서드를 호출하여 다양한 UI 구성 요소를 변경하는 방법은 Web Chatbot 메서드 문서를 참고하시기 바랍니다.

부록. 커스텀 메뉴 아이콘

실제 커스텀 메뉴 아이콘은 다음과 같습니다.

커스텀 메뉴 아이콘 목록 그림커스텀 메뉴 아이콘 목록

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.