Kakao i Web Chatbot::Web Chatbot 메서드

페이지 이동경로

기능별 메서드 목록

Kakao i Web Chatbot SDK의 전체 메서드 목록은 다음과 같습니다.

기능별 메서드 목록
카테고리 Namespace 메서드 설명
초기 설정 init() Chatbot 서비스 관련 사항 설정
Skill Server 필요 상태값 관리 Store setVendorState() Skill Server에서 비즈니스 로직을 구현할 때 필요한 상태값(State)을 설정
Store getVendorState() Vendor State에 등록된 상태값을 조회
Store deleteVendorState() Vendor State에 등록된 상태값을 제거
채팅 관리 Chat send() 사용자가 입력한 텍스트를 Chatbot에 전송
Chat excludeChatBot() 사용자와 Chatbot의 대화 기능을 비활성
Chat includeChatBot() excludeChatBot() 메서드로 비활성화한 Chatbot과의 대화 기능을 다시 활성화
Chat getHistories() 채팅창의 대화 이력을 확인
Chat disableAutomaticRead() 사용자 보낸 메시지 자동 읽음 비활성화
Chat enableAutomaticRead() disableAutomaticRead() 메서드로 비활성화한 자동 읽음을 다시 활성화
Chat markAsRead() disableAutomaticRead() 메서드 호출 후 메시지 수동 읽음 처리
UI 관리 UI createChat() 채팅창 화면을 생성
UI renderUserChat() 채팅창 화면에 사용자 메시지를 추가
UI renderBotChat() 채팅창 화면에 Bot의 메시지를 추가
UI submitChat() 사용자가 Bot에 메시지를 전송하고, 채팅창 화면에 Bot의 응답을 추가
UI clickCloseButton() 채팅창 우측 상단에 표시되는 닫기 버튼의 클릭 이벤트를 발생
UI clickFloatingButton() 플로팅 버튼의 클릭 이벤트를 발생
UI setChatTitle() 채팅창 화면의 타이틀을 변경
UI setChatSubTitle() 채팅창 화면의 서브 타이틀을 변경
UI showUploadButton() Chatbot 좌측 하단에 [파일 업로드] 버튼 노출
UI hideUploadButton() showUploadButton()을 통해 노출시킨 [파일 업로드] 버튼을 다시 숨김
UI showExitCounselingButton() Chatbot 좌측 하단에 [상담 종료] 버튼 표시
UI hideExitCounselingButton() showExitCounselingButton()을 통해 노출시킨 [상담 종료] 버튼을 다시 숨김
UI showAutoComplete() 자동완성 영역 노출
UI hideAutoComplete() 자동완성 영역 숨김
UI setProfileImageUrl() 채팅창 내 Bot 프로필 이미지 변경
UI showDimmedNotice() 채팅창에 레이어 팝업 노출
벤더 로그인 사용자 ID 관리 Store setVendorLoginId() 벤더 사용자 로그인 ID 설정
Store releaseVendorLoginId() 벤더 사용자 로그인 ID 설정 해제 및 대화 이력 삭제

초기 설정

init()

디케이테크인 담당자로부터 사전에 전달받은 서비스 관련 정보와 서비스 트래커 정보를 입력해야 합니다.

코드예제init() Syntax

Kakaoi.init({
    serviceName: "string",
    serviceKey: "string",
    vertebra: {
        serviceId: "string",
        serviceName: "string",
        svcDomain: "string",
        developmentMode: boolean
    },
    sdkType : "string"
});

init() Parameter
파라미터 타입 필수 여부 설명
serviceName String 필수 디케이테크인 담당자로부터 전달받은 서비스명 정보
serviceKey String 필수 디케이테크인 담당자로부터 전달받은 서비스키값
Object 필수 디케이테크인 담당자로부터 전달받은 트래커 정보
serviceId String 필수 디케이테크인 담당자로부터 전달받은 트래커 서비스 ID
serviceName String 필수 디케이테크인 담당자로부터 전달받은 트래커 서비스명
svcDomain String 필수 디케이테크인 담당자로부터 전달받은 트래커 서비스 도메인
developmentMode Boolean 선택 트래커를 통계가 기록되지 않는 개발자 모드로 설정
sdkType String 필수 디케이테크인 담당자로부터 전달받은 타입 정보

코드예제init() Sample Code

Kakaoi.init({
    serviceName: "service name",
    serviceKey: "service key",
    vertebra: {
        serviceId: "vertebra service id",
        serviceName: "vertebra service name",
        svcDomain: "vertebra service domain",
        developmentMode: true
    },
    sdkType : "kakao"
});

Skill Server 필요 상태값 관리

Vendor State는 Skill Server에서 비즈니스 로직을 구현할 때 필요한 상태(state) 정보를 관리합니다.

  • Skill Server는 Chatbot에 구현된 비즈니스 로직을 처리하는 API(Skill)가 구현되어 있는 서버입니다.

Skill Server에서 비즈니스 로직을 구현할 때 필요한 상태값(State)을 설정합니다. 이 상태값은 SDK에서 자체적으로 보유하고 있다가 매 채팅 요청 시 Skill Server로 함께 전달되는 값입니다.

코드예제setVendorState() Syntax

Kakaoi.Store.setVendorState("{key}", "{value}");

setVendorState() Parameter
파라미터 타입 필수 여부 설명
key String 필수 고객사 정의 항목
- 디케이테크인 담당자와 협의 필요
value String 필수 고객사 정의 항목
- 디케이테크인 담당자와 협의 필요

코드예제setVendorState() Sample Code

Kakaoi.Store.setVendorState("token", "Abci3930sKIR2");

getVendorState()

Vendor State에 등록된 상태값을 조회합니다.

코드예제getVendorState() Syntax

Kakaoi.Store.getVendorState("{key}");

getVendorState() Parameter
파라미터 타입 필수 여부 설명
key String 필수 조회하려는 Value에 해당하는 Key 값

코드예제getVendorState() Sample Code

Kakaoi.Store.getVendorState("token");

deleteVendorState()

Vendor State에 등록된 상태값을 제거합니다.

코드예제deleteVendorState() Syntax

Kakaoi.Store.deleteVendorState("{key}");

deleteVendorState() Parameter
파라미터 타입 필수 여부 설명
key String 필수 제거하려는 Value에 해당하는 Key 값

코드예제deleteVendorState() Sample Code

Kakaoi.Store.deleteVendorState("token");

채팅 관리

Chatbot에게 텍스트를 전송하는데 사용합니다.

send()

사용자가 입력한 텍스트를 Chatbot에 전송합니다. 채팅 관리 모듈에는 해당 메서드가 내장되어 있어, 별도의 처리 없이 Chatbot과 대화를 가능하게 합니다.

코드예제send() Syntax

Kakaoi.Chat.send({
	message: "{message}",
	onSuccess: function(payloads){
		// 응답 수신
	},
	onError: function(err){
		// 오류 발생
	},
});

send() Parameter
파라미터 타입 필수 여부 설명
Object 필수 메시지 전달의 성공 여부와 성공 시에 전달되는 메시지
message String 필수 사용자가 입력한 메시지
Function 선택 Chatbot에서 정상 응답 수신 확인 시 onSuccess() 콜백 메서드 실행
Object[] 필수 응답 수신 시 응답 정보 인자 배열
payload Object 필수 자세한 정보는 payload 참고
Function 선택 Chatbot에서 응답 오류 수신 확인 시 onError() 콜백 메서드 실행
err: 에러 코드와 에러 메시지 제공
Object 선택 오류 발생 시 에러 정보 인자
error code String 필수 오류 코드
NOT_AUTHORIZED: 인증 작업이 정상적으로 처리되지 않음
EXPIRED_AUTHORIZE: 챗봇 세션 만료
UNEXPECTED: 예상치 못한 오류 발생
error message String 필수 오류 메시지

코드예제send() Sample Code

Kakaoi.Chat.send({
	message: "배송 정보 알려줘",
	onSuccess: function(message){
		console.log(message);
	},
	onError: function(err){
		console.error(err);
	},
});

payload

코드예제payload Syntax

{
     "instruction": {
             "header": {
                     "type": "string",
                     "messageId": "string"
             },
             "body": {
                     "token": "string",
                     "style": "string",
                     "ttl": number,
                     "mood": "string",
                     "text": "string",
                     "data?": DataType
             },
             "meta": {
                     "ts": number,
                     "topic": "string",
                     "botId": "string",
                     "botName": "string",
                     "intentId": "string",
                     "intentName": "string"
             }
     }
}

excludeChatBot()

Chatbot의 대화 기능을 사용하지 않는 기능으로, 사용자가 Chatbot에 메시지를 입력해도 Chatbot은 응답하지 않습니다.

  • excludeChatBot() 메서드를 호출한 후 다시 Chatbot과의 대화 기능을 활성화하기 위해서는 includeChatBot() 메서드를 호출해야 합니다.

코드예제excludeChatBot() Syntax

Kakaoi.Chat.excludeChatBot();

includeChatBot()

excludeChatBot() 메서드를 호출하여 비활성했던 Chatbot과 대화 기능을 다시 활성화할 때 호출합니다. 메서드를 호출한 적이 없을 경우, Chatbot과의 대화 기능은 기본적으로 활성화되어 있습니다.

코드예제includeChatBot() Syntax

Kakaoi.Chat.includeChatBot();

getHistories()

채팅창의 대화 이력을 확인하는 기능입니다.

코드예제getHistories() Syntax

Kakaoi.Chat.getHistories();

getHistories() Response Elements
파라미터 타입 필수 여부 설명
Object[] 필수
isBot Boolean 필수 발화 주체를 표시
true: Chatbot의 발화
false: 사용자가 입력한 발화
text String 필수 상세 발화 내용

코드예제getHistories() Response Sample Code

result : [
  { isBot: true, text: 안녕하세요 챗봇입니다. 무엇을 도와드릴까요? },
  { isBot: false, text: 배송조회해줘 }
]

disableAutomaticRead()

사용자가 보낸 메시지를 자동으로 읽음 처리하지 않는 기능으로, 다시 자동 읽음을 활성화하기 위해서는 enableAutomaticRead() 메서드를 호출해야 합니다.

  • disableAutomaticRead() 메서드를 호출하고 메시지를 ‘읽음’ 표시하기 위해서는 상담원의 메시지 확인 후 markAsRead() 메서드로 직접 읽음 처리해야 합니다.

코드예제disableAutomaticRead() Syntax

Kakaoi.Chat.disableAutomaticRead();

enableAutomaticRead()

disableAutomaticRead() 메서드를 호출하여 비활성화했던 메시지 자동 읽음을 다시 활성화할 때 호출합니다. 메서드를 호출한 적이 없을 경우, 자동 읽음 기능은 기본적으로 활성화되어 있습니다.

코드예제enableAutomaticRead() Syntax

Kakaoi.Chat.enableAutomaticRead();

markAsRead()

disableAutomaticRead() 메서드를 호출하여 사용자의 메시지 자동 읽음 기능을 비활성한 후, 메시지를 수동으로 읽음 처리할 때 호출합니다. 메서드를 호출한 적이 없을 경우, 자동 읽음 기능은 기본적으로 활성화되어 있습니다.

  • 상담원이 확인한 시점 이전의 메시지를 읽음 처리하기 위해 요청 파라미터로 new Date()를 포함하여 호출합니다.

코드예제markAsRead() Syntax

Kakaoi.Chat.markAsRead(new Date());

markAsRead() Parameters
파라미터 타입 필수 여부 설명
new Date() Date 필수 상담원의 메시지 확인 시점

UI 관리

채팅창 화면을 생성하고 UI 요소를 관리합니다.

createChat()

채팅창 화면을 생성합니다.

안내
선택 메서드를 별도로 입력하지 않을 경우에는 SDK의 기본 동작이 수행됩니다.

코드예제createChat() Syntax

Kakaoi.UI.createChat({
    title: "string",
    subTitle: "string",
    profileName: "string",
    profileImageUrl: "string",
    profileImageBorderLess: boolean,
    backgroundColor: "string",
    backgroundImageUrl: "string",
    chatHeight: number,
    notice: {
            message: "string",
            link: "string",
            backgroundColor: "string",
            textColor: "string"
    },
    tooltip: "툴팁 메시지를 입력하세요",
    inputPlaceholder: "발화를 입력하세요",
    bubbleTextColor: "string",
    bubbleBackgroundColor: "string",
    activeKeyword: "string",
    quickReplyColor: "string",
    quickReplyButtonBorderColor: "string",
    quickReplyButtonTextColor: "string",
    textMasking: boolean,
    useCustomFloatingButton: boolean,
    useChatAutomaticRead: boolean,
    customMenus: [{
            id: number,
            title: "string",
            icon: "string",
            type: "string",
            message: "string",
            blockId: "string",
            url: "string",
    }, ...],
    customMenuTextColor: "string",
    customMenuBackgroundColor: "string",
    errorMessage: "string",
    customStyle: {
            color: {
                readMark: "string",
                autocompleteWord: "string",
                customMenuButton: "string",
                sendMessageButton: "string",
                carouselMoveButton: "string"
        }
    },
    onCustomMenuClick: (id) => {
    },
    onChatSend: (text) => {
    },
    onChatReceive: (payloads) => {
    },
    blockButtonClickPreInterceptor: (buttonInfo) => {
    },
    blockButtonClickInterceptor: (buttonInfo) => {
    },
    noticeClickInterceptor: (noticeInfo) => {
    },
    closeButtonClickInterceptor: (e) => {
    },
    floatingButtonClickInterceptor: (e) => {
    },
    onFileUpload: (inputElement) {
    },
    onExitCounselingButtonClick: () => {
    },
    onKeyDownUserChat(text) => {
    }
});

createChat() Parameter
메서드 타입 필수 여부 설명
Method 필수 채팅창 생성
title String 선택 채팅창 타이틀 영역에 표시되는 텍스트
- 띄어쓰기 포함 15자 이내
- 이모지 및 특수기호 가능
subTitle String 선택 Chatbot의 상태를 표시하는 텍스트
- 봇과 대화중 / 상담사와 대화중으로만 표시
profileName String 선택 Bot의 이름
- 띄어쓰기 포함 15자 이내
- 이모지 및 특수기호 가능
profileImageUrl String 선택 프로필로 사용할 URL 또는 Base64 이미지
profileImageBorderLess Boolean 선택 프로필 이미지 테두리 적용 여부
true: 프로필 이미지 테두리 미적용
false(기본값): 이미지 테두리 적용
backgroundColor String 선택 채팅창 배경색
- Hex Code(#ffbbcc)
backgroundImageUrl String 선택 채팅창 배경으로 사용할 URL 또는 Base64 이미지
- 배경 이미지 사이즈: 1440*2960px 이상 권장
chatHeight Number 선택 채팅창 높이
- 단위: vh
- 범위: 10~100
Object 선택 채팅창 상단 공지사항 설정
message String 선택 공지사항 메시지
link String 선택 공지사항 클릭시 이동할 URL
- 새창 열기로 이동
backgroundColor String 선택 공지사항 배경색
- Hex Code(#ffbbcc)
textColor String 선택 공지사항 텍스트색
- Hex Code(#ffbbcc)
tooltip String 선택 채팅창 활성화 버튼의 툴팁 메시지
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 선택 플로팅 버튼 커스텀 여부
- 자세한 사항은 Custom Floating Button 적용하기 참고
true: 고객사 커스텀 플로팅 버튼 사용
false(기본값): 기본 제공 버튼 사용
useChatAutomaticRead 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: 서류 아이콘
type String 필수 커스텀 메뉴 타입
message: 메시지 전송
block: 블록 연결
link: URL 이동
message String 선택 customMenus의 type 값이 message(메시지 전송)인 경우 전송할 메시지
blockId String 선택 customMenus의 type 값이 block(블록 연결)인 경우 연결할 블록 id
- 블록 연결시 title 값(커스텀 메뉴명)을 봇에 전달
url String 선택 customMenus의 type 값이 link(URL 이동)인 경우 이동할 URL 주소
customMenuTextColor String 선택 커스텀 메뉴 텍스트색
- Hex Code(#ffbbcc)
customMenuBackgroundColor String 선택 커스텀 메뉴 배경색
- Hex Code(#ffbbcc)
errorMessage String 선택 Bot 응답에 오류 발생 시 확인할 수 있는 에러 메시지 직접 설정
Object 선택 채팅창 세부 구성 요소 커스텀 설정
Object 선택 채팅창 요소 커스텀 색상
readMark String 선택 말풍선 읽음 여부 텍스트색
- Hex Code(#ffbbcc)
autocompleteWord String 선택 자동 완성 단어 텍스트색
- Hex Code(#ffbbcc)
customMenuButton String 선택 커스텀 메뉴 활성화 시 변경될 [메뉴] 아이콘색
- Hex Code(#ffbbcc)
sendMessageButton String 선택 [메시지 전송] 아이콘색
- Hex Code(#ffbbcc)
carouselMoveButton String 선택 캐러셀 좌우 이동 버튼색
- Hex Code(#ffbbcc)
onCustomMenuClick() Method 선택 커스텀 메뉴 클릭 시 customMenus의 id 값을 반환하는 콜백 메서드
onChatSend() Method 선택 사용자 발송 텍스트를 고객사가 구독하는 리스너
ex 1) 고객사의 로그 시스템에 대화 내용을 적재
ex 2) 고객사의 상담 시스템에 전송
onChatReceive() Method 선택 Bot의 응답 정보를 고객사가 구독하는 리스너
blockButtonClickPreInterceptor() Method 선택 Bot 응답 구성요소 중 버튼 블록 클릭 시 동작을 수행하기 전에 커스터마이징 된 동작을 먼저 실행
ex) 퀵리플라이버튼 클릭 시 봇 전환이 발생하고, 바뀐 봇으로부터 특정 블록 호출 가능
true: 메서드 실행 종료 후 이어서 기본 동작(링크 연결, 채팅 자동 입력 등) 수행
false: 기본 동작을 수행하지 않음
blockButtonClickInterceptor() Method 선택 Bot 응답 구성요소 중 버튼 블록 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
- 버튼 블록의 속성(label, linkUrl 등)은 buttonInfo에서 확인 가능
true: 메서드 실행 종료 후 이어서 기본 동작(링크 연결, 채팅 자동 입력 등) 수행
false: 기본 동작을 수행하지 않음
noticeClickInterceptor() Method 선택 공지사항 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
true: 기본 동작(공지사항 링크 이동)을 실행시켜주는 반환값
false: 고객사가 구현한 동작을 실행
closeButtonClickInterceptor() Method 선택 창닫기 버튼 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
true: 기본 동작(채팅창 닫힘)을 실행 시켜주는 반환값
false: 고객사가 구현한 동작을 실행
floatingButtonClickInterceptor() Method 선택 플로팅 버튼 클릭 시 수행할 동작을 커스터마이징
ex) 인앱 브라우저에서 부모 앱에 특정 요청을 전송하고, 웹에서는 기본 동작을 수행하는 등의 요구사항에 대해 분기 처리 가능
true: 기본 동작(채팅창 열림)을 실행 시켜주는 반환값
false: 고객사가 구현한 동작을 실행
onFileUpload() Method 선택 파일 업로드를 구독하는 리스너
- showUploadButton() 참고
onExitCounselingButtonClick() Method 선택 [상담 종료] 버튼 클릭을 구독하는 리스너
- showExitCounselingButton() 참고
onKeyDownUserChat() Method 선택 사용자 발화 입력값을 반환하는 메서드

Custom Floating Button 적용하기

onCustomMenuClick()

커스텀 메뉴를 클릭 시 createChat()의 customMenus 파라미터에 설정한 메뉴별 id 값을 반환합니다. 해당 id 값을 이용하여 커스텀 메뉴별로 고객사가 정의한 동작을 실행할 수 있습니다.

코드예제onCustomMenuClick() Syntax

customMenus: [
  {
    id: 1,
    title: "아이콘1",
    icon: "box",
  },
  {
    id: 2,
    title: "아이콘2",
    icon: "point",
  },
  {
    id: 3,
    title: "아이콘3",
    icon: "profile",
  },
],
onCustomMenuClick: (id) => {
  switch (id) {
    case 1:
      doFunction1()
      break
    case 2:
      doFunction2()
      break
    case 3:
      doFunction3()
      break
  }
},

onChatSend()

사용자가 채팅창에 입력한 메시지를 구독합니다.
다음 예시와 같이 사용자가 채팅창에 메시지를 입력했을 때, 고객사 로그 서버에 적재하거나, 고객사 상담 시스템에 텍스트를 전송하는 등 비즈니스 환경과 목적에 맞게 고객사 외부 시스템과 다양하게 활용할 수 있습니다.

예시 1. 고객사 로그 서버에 적재

그림예시 1. 고객사 로그 서버에 적재

예시 2. 고객사 상담 시스템에 전송

그림예시 2. 고객사 상담 시스템에 전송

onChatReceive()

Bot이 전송한 응답 정보를 구독합니다.
응답 정보는 Bot과 인텐트의 정보를 포함하며, 고객사가 응답 내용과 인텐트를 별도로 관리하고자 할 경우에 활용할 수 있습니다.

코드예제onChatReceive() Syntax

onChatReceive: (payload) => {
  if (payload.intentName === "폴백블록") {
		Logger.addError(payload.botId, payload.botName);
	}
}

onChatReceive() Parameter
파라미터 타입 필수 여부 설명
Object 필수 봇 응답 전송 시 응답 정보
botId String 필수 현재 봇 ID
botName String 필수 현재 봇 이름
intentId String 필수 봇 응답의 인텐트 ID
intentName String 필수 봇 응답의 인텐트 이름

blockButtonClickPreInterceptor()

사용자가 Bot 응답 내 버튼 요소를 클릭 시, SDK 기본 동작을 수행하기 전에 고객사가 정의한 커스텀 동작을 수행할지 정의할 수 있습니다. 메서드가 true를 반환하도록 정의하면 메서드 수행 후 기본 동작이 수행되며, false를 반환하도록 정의하면 커스텀 동작만을 수행합니다. 커스텀 동작을 정의할 때 buttonInfo에 전달되는 버튼 정보에는 Bot 빌더/Skill(API) 서버가 생성하는 응답에 따라 url, link, text, block 타입을 사용할 수 있으며, 타입별 구조는 blockButtonClickInterceptor() 메서드와 같습니다.

코드예제blockButtonClickPreInterceptor() Syntax

blockButtonClickPreInterceptor: (buttonInfo) => {
  // 커스텀 동작 코드 직접 작성 필요
  if (buttonInfo.message === "봇 전환") {
    Kakaoi.Bot.changeBot({
      serviceKey: buttonInfo.data.extra.serviceKey,
      blockId: buttonInfo.data.extra.blockId,
    })
    return false   // 커스텀 동작만 수행
  } else {
    return true    // 이어서 기본 동작 수행
  }
},

blockButtonClickInterceptor()

사용자가 Bot 응답 내 버튼 요소를 클릭 시, SDK 기본 동작을 수행할지 또는 고객사가 정의한 커스텀 동작을 수행할지 정의할 수 있습니다.
메서드가 true를 반환하도록 정의하면 기본 동작 수행 후 커스텀 메서드가 수행되며, false를 반환하도록 정의하면 커스텀 동작만을 수행합니다. 커스텀 동작을 정의할 때 buttonInfo에 전달되는 버튼 정보에는 Bot 빌더/Skill(API) 서버가 생성하는 응답에 따라 url, link, text, block 타입을 사용할 수 있으며, 타입별 구조는 다음과 같습니다.

코드예제blockButtonClickInterceptor() 타입별 구조

//타입이 url일 경우
type: "url"
label: string
url: string

//타입이 link일 경우
type: "link"
androidStoreUrl: string
iosStoreUrl: string
androidUrl: string
iosUrl: string
label: string
macCustomScheme: string
moUrl: string
pcCustomScheme: string
pcUrl: string

//타입이 text일 경우
type: "text"
label: string
message: string

//타입이 block일 경우
type: "block"
blockId: string
label: string
message: string

타입별 구조
type 타입 필수 여부 설명
type String 필수 버튼 타입
url: Bot 빌더에서 설정한 URL 링크 버튼
link: Skill 응답으로 설정한 URL 링크 버튼
text: 일반 메시지 입력용 버튼
block: 블록 연결 버튼
label String 필수 버튼명
url String 선택 이동시킬 URL 주소
- type이 url인 경우 필수
androidStoreUrl String 선택 안드로이드 스토어 URL
- type이 link일 경우 설정 가능
androidUrl String 선택 안드로이드용 URL
- type이 link일 경우 설정 가능
iosStoreUrl String 선택 앱스토어용 URL
- type이 link일 경우 설정 가능
iosUrl String 선택 iOS용 URL
- type이 link일 경우 설정 가능
macCustomScheme String 선택 mac용 스킴
- type이 link일 경우 설정 가능
moUrl String 선택 모바일용 URL
- type이 link일 경우 설정 가능
pcCustomScheme String 선택 Windows용 스킴
- type이 link일 경우 설정 가능
pcUrl String 선택 PC용 URL
- type이 link일 경우 설정 가능
message String 선택 채팅창에 전송할 메시지
- type이 text 또는 block일 경우에만 필수로 설정
blockId String 선택 블럭 식별값(ID)
- type이 block일 경우에만 필수로 설정

코드예제blockButtonClickInterceptor() Syntax

	blockButtonClickInterceptor: (buttonInfo) -> {
    const isMobile = true; // 조건 직접 작성 필요
		if(isMobile && buttonInfo.type === "link"){
			location.href = buttonInfo.moUrl;
			return false; // 기본 동작이 아닌 커스텀 동작 수행
		}
		return true; // SDK 기본 동작 수행
	},

안내
Bot 응답 타입별 구조 및 자세한 설명은 챗봇 관리자센터 도움말 문서를 참고하시기 바랍니다.

noticeClickInterceptor()

사용자가 공지사항을 클릭할 시, SDK 기본 동작(공지사항 링크로 이동)을 수행할지 또는 커스텀 동작을 수행할지 정의할 수 있습니다.
메서드가 true를 반환하도록 정의하면 메서드 수행 후 기본 동작이 수행되며, false를 반환하도록 정의하면 커스텀 동작만을 수행합니다.

코드예제noticeClickInterceptor() Syntax

noticeClickInterceptor: (noticeInfo) => {
	// true: SDK 기본 동작 수행
	// false: 기본 동작이 아닌 커스텀 동작 수행
	return false
},

closeButtonClickInterceptor()

사용자가 채팅창 닫기 버튼을 클릭 시, SDK 기본 동작(채팅창을 닫는 행위)을 수행할지 또는 커스텀 동작을 수행할지 정의할 수 있습니다.
메서드가 true를 반환하도록 정의하면 메서드 수행 후 기본 동작이 수행되며, false를 반환하도록 정의하면 커스텀 동작만을 수행합니다.

코드예제closeButtonClickInterceptor() Syntax

closeButtonClickInterceptor: (e) -> {
    const isMobile = true; // 조건 직접 작성 필요
	if(isMobile){
		window.parent.postMessage("AndroidAppclose");
		return false; // 기본 동작이 아닌 커스텀 동작 수행
	}
	return true; // SDK 기본 동작 수행
},

floatingButtonClickInterceptor()

사용자가 플로팅 버튼을 클릭 시, SDK 기본 동작(채팅창을 여는 행위)을 수행할지 또는 커스텀 동작을 수행할지 정의할 수 있습니다.
메서드가 true를 반환하도록 정의하면 메서드 수행 후 기본 동작이 수행되며, false를 반환하도록 정의하면 커스텀 동작만을 수행합니다.

코드예제floatingButtonClickInterceptor() Syntax

floatingButtonClickInterceptor: (e) -> {
    const isMobile = true; // 조건 직접 작성 필요
	if(isMobile){
		window.parent.postMessage("AndroidPushChat");
		return false; // 기본 동작이 아닌 커스텀 동작 수행
	}
	return true; // SDK 기본 동작 수행
},

onFileUpload()

showUploadButton()를 통해 사용자의 파일 업로드 버튼을 노출했을 경우, 업로드된 파일을 구독하는 리스너 함수입니다.

코드예제onFileUpload() Syntax

onFileUpload: (input) => {
    console.log(input.files);
}

onExitCounselingButtonClick()

showExitCounselingButton()를 통해 [상담 종료] 버튼을 노출했을 경우, 사용자가 해당 버튼을 클릭한 내역을 구독하는 리스너 함수입니다.

코드예제onExitCounselingButtonClick() Sample Code

onExitCounselingButtonClick: () => {
    console.log("exit clicked");
    Kakaoi.UI.setChatSubTitle("봇과 대화중");
    Kakaoi.UI.hideExitCounselingButton();
}

onKeyDownUserChat()

사용자가 채팅창에 입력한 값을 실시간으로 반환합니다.

코드예제onKeyDownUserChat() Syntax

onKeyDownUserChat: (text) => {
    console.log(text);
}

renderUserChat()

채팅창 화면에 사용자 메시지를 추가합니다.

코드예제renderUserChat() Syntax

Kakaoi.UI.renderUserChat("{text}");

renderUserChat() Parameter
파라미터 타입 필수 여부 설명
text String 필수 사용자가 입력한 메시지

코드예제renderUserChat() Sample Code

Kakaoi.UI.renderUserChat("상담 부탁드립니다.");

renderBotChat()

채팅창 화면에 Bot의 메시지를 추가합니다.

코드예제renderBotChat() Syntax

Kakaoi.UI.renderBotChat("{text}");

renderBotChat() Parameter
파라미터 타입 필수 여부 설명
text String 필수 Bot 응답으로 추가되는 메시지

코드예제renderBotChat() Sample Code

Kakaoi.UI.renderBotChat("안녕하세요. 무엇을 도와드릴까요?");

submitChat()

사용자가 Bot에게 메시지를 전송하고, 채팅창 화면에 Bot의 응답을 추가합니다. 이때 인자로 사용된 메시지는 별도로 렌더링 되지 않기 때문에, 필요할 경우 renderUserChat()을 호출하여 그려줄 수 있습니다.

코드예제submitChat() Syntax

Kakaoi.UI.submitChat("{text}");

submitChat() Parameter
파라미터 타입 필수 여부 설명
text String 필수 Bot 응답으로 추가되는 메시지

코드예제submitChat() Sample Code

Kakaoi.UI.submitChat("안녕하세요. 배송조회 알려주세요");

clickCloseButton()

채팅창 우측 상단에 표시되는 닫기 버튼의 클릭 이벤트를 발생시킵니다. 이때 기본 동작으로 채팅창을 숨기는 동작이 실행되며, createChat()에서 closeButtonClickInterceptor()를 통해 커스텀 로직을 정의한 경우에는 반환값에 따라 기본 동작이 수행되지 않도록 구현할 수 있습니다.

코드예제clickCloseButton() Syntax

Kakaoi.UI.clickCloseButton();

clickFloatingButton()

플로팅 버튼의 클릭 이벤트를 발생시킵니다. 이때 기본 동작으로 채팅창을 활성화하는 동작이 실행되며, createChat()에서 floatingButtonClickInterceptor()를 통해 커스텀 로직을 정의한 경우에는 반환값에 따라 기본 동작이 수행되지 않도록 구현할 수 있습니다.

코드예제clickFloatingButton() Syntax

Kakaoi.UI.clickFloatingButton();

setChatTitle()

채팅창 화면의 타이틀을 변경합니다.

코드예제setChatTitle() Syntax

Kakaoi.UI.setChatTitle("{title}");

setChatTitle() Parameter
파라미터 타입 필수 여부 설명
title String 필수 변경하고자 하는 채팅창 타이틀
- 띄어쓰기 포함 15자 이내
- 이모지 및 특수기호 가능

코드예제setChatTitle() Sample Code

Kakaoi.UI.setChatTitle("dk techin 몰");

setChatSubTitle()

채팅창 화면의 서브 타이틀을 변경합니다.

코드예제setChatSubTitle() Syntax

Kakaoi.UI.setChatSubTitle("{subTitle}");

setChatSubTitle() Parameter
파라미터 타입 필수 여부 설명
subTitle String 필수 변경하고자 하는 서브 타이틀
- 봇과 대화중 또는 상담사와 대화중으로만 변경 가능

코드예제setChatSubTitle() Sample Code

Kakaoi.UI.setChatSubTitle("상담사와 대화중");

showUploadButton()

Chatbot의 좌측 하단에 [파일 업로드] 버튼을 표시합니다.

코드예제showUploadButton() Syntax

Kakaoi.UI.showUploadButton();

hideUploadButton()

showUploadButton()을 통해 노출시킨 [파일 업로드] 버튼을 다시 숨깁니다.

코드예제hideUploadButton() Syntax

Kakaoi.UI.hideUploadButton();

showExitCounselingButton()

Chatbot의 좌측 하단에 [상담 종료] 버튼을 노출합니다.

코드예제showExitCounselingButton() Syntax

Kakaoi.UI.showExitCounselingButton();

hideExitCounselingButton()

showExitCounselingButton() 메서드를 통해 노출시킨 [상담 종료] 버튼을 다시 숨깁니다.

코드예제hideExitCounselingButton() Syntax

Kakaoi.UI.hideExitCounselingButton();

showAutoComplete()

사전에 등록된 단어를 바탕으로 사용자 입력값이 포함된 질의어를 추천해주는 자동완성 영역을 활성화합니다. hideAutoComplete() 메서드로 숨긴 자동완성 영역을 다시 노출시킵니다.

코드예제showAutoComplete() Syntax

Kakaoi.UI.showAutoComplete(["{items}", ...]);

showAutoComplete() Parameter
파라미터 타입 필수 여부 설명
items Array 필수 자동완성 영역에 노출할 단어 목록
- 최대 10개 단어 입력 가능
- 사용자 입력값과 2자 이상 일치하는 글자에 색상 효과 적용
- 자동완성 영역 노출 시 퀵리플라이, 커스텀 메뉴 숨김 처리

코드예제showAutoComplete() Sample Code

Kakaoi.UI.showAutoComplete(["선물하기", "여성 선물 추천", "남성 선물 추천", "스승의 날 선물"]);

hideAutoComplete()

showAutocomplete() 메서드로 노출시킨 자동완성 영역을 숨깁니다.

코드예제hideAutoComplete() Syntax

Kakaoi.UI.hideAutoComplete();

setProfileImageUrl()

채팅창 화면의 Bot 프로필 이미지를 일시적으로 변경합니다. 예를 들어, 상담원 연결 시 Chatbot의 프로필 이미지가 다르게 표시되도록 활용할 수 있습니다.
요청 파라미터를 입력하지 않은 경우 Web Chatbot SDK에서 제공하는 기본 프로필 이미지로 설정됩니다.

코드예제setProfileImageUrl() Syntax

Kakaoi.UI.setProfileImageUrl("{url}")
Kakaoi.UI.setProfileImageUrl("") // 웹 챗봇 SDK가 제공하는 기본 프로필 이미지로 설정

setProfileImageUrl() Parameters
파라미터 타입 필수 여부 설명
url String 선택 변경할 채팅창 봇 프로필 이미지 url
- 미입력시 웹 챗봇 기본 프로필 이미지 적용

showDimmedNotice()

채팅창 하단에 레이어 팝업을 노출합니다. 팝업 강조를 위해 채팅창은 음영 처리(dimmed)됩니다. 아래 예시와 같이 챗봇 점검을 비롯한 공지사항을 표시하는 데 활용할 수 있습니다.

챗봇 공지사항 레이어 팝업 예시 그림챗봇 공지사항 레이어 팝업 예시

코드예제showDimmedNotice() Syntax

Kakaoi.UI.showDimmedNotice({
	title: "{title}",
	subTitle: "{subtitle}"
});

showDimmedNotice() Parameter
파라미터 타입 필수 여부 설명
title String 선택 팝업 제목
- 띄어쓰기 포함 40자 이내(40자 초과하는 경우 말줄임표 적용)
- \n 사용하여 줄바꿈 가능
- 최대 2줄
subTitle String 선택 팝업 부제목
- 띄어쓰기 포함 40자 이내(40자 초과하는 경우 말줄임표 적용)
- \n 사용하여 줄바꿈 가능
- 최대 2줄

코드예제showDimmedNotice() Sample Code

Kakaoi.UI.showDimmedNotice({
	title: "불편을 드려 죄송합니다.\n챗봇 점검중입니다.",
	subTitle: "점검시간\n2023.01.01 17:00 - 20:00"
});

벤더 로그인 사용자 ID 관리

고객사의 자체 로그인 정보를 주입할 수 있습니다. Chatbot에 접속한 사용자의 로그인 정보를 식별하고자 할 경우, 다음 메서드를 필수적으로 호출해야 합니다.

setVendorLoginId()

벤더 로그인 사용자 ID를 설정합니다. 벤더 로그인 사용자 ID란 Chatbot과 대화 중인 사용자를 구별하기 위한 정보로, 고객사가 자체적으로 정의할 수 있습니다. 배송 조회 등 개인화된 답변이 필요한 경우 고객사의 웹 사이트 미로그인 사용자에 로그인을 요청하고, 해당 로그인 ID 정보를 획득합니다.

주의
메서드 호출 시 동일한 사용자의 ID를 변경하여 전달할 경우, 추가적인 과금의 소지가 있어 주의가 필요합니다.

코드예제setVendorLoginId() Syntax

Kakaoi.Store.setVendorLoginId("{idString}");

setVendorLoginId() Parameter
파라미터 타입 필수 여부 설명
idString String 필수 고객사 자체 로그인 정보
- 사용자의 UID 또는 이를 암호화하여 입력

releaseVendorLoginId()

벤더 사용자 로그인 ID 설정을 해제합니다. 그와 동시에 저장된 대화 이력이 모두 삭제됩니다.

코드예제releaseVendorLoginId() Syntax

Kakaoi.Store.releaseVendorLoginId();

Sample Code

코드예제Sample Code

Kakaoi.UI.createChat({
    title: "dk techin 챗봇",
    subTitle: "봇과 대화중",
    profileName: "dktechin 봇",
    profileImageBorderLess: "true",
    bubbleTextColor: "#FFFFFF",
    bubbleBackgroundColor: "#173D2C",
    quickReplyColor: "#DED6D2",
    quickReplyButtonBorderColor: "#F3F3F3",
    quickReplyButtonTextColor: "#161616",
    backgroundColor: "#FFFFFF",
    chatHeight: 800,
    notice: {
        message: "공지사항 영역",
        link: "https://dktechin.com/",
        backgroundColor: "#FFFFFF",
        textColor: "#DED6D2"
    },
    inputPlaceholder: "궁금한 것은 무엇이든 물어보세요!",
    errorMessage: "문제가 발생했어요~",
    onChatSend: (text) => {
        if (text === "상담원 연결") {
            Kakaoi.UI.setChatSubTitle("상담원과 대화중");
            Kakaoi.UI.showExitCounselingButton();
        }
        return true
    },
    blockButtonClickInterceptor: (buttonInfo) => {
        if (buttonInfo.message === "상담원 연결") {
            Kakaoi.UI.setChatSubTitle("상담원과 대화중");
            Kakaoi.UI.showExitCounselingButton();
        }
        return true
    },
    onExitCounselingButtonClick: () => {
        Kakaoi.UI.hideExitCounselingButton();
        Kakaoi.UI.setProfileImageUrl("");
        return true;
    },
    onKeyDownUserChat: (text) => {
        if (text.includes("디케이테크인")) {
            Kakaoi.UI.showAutoComplete(["디케이테크인", "디케이테크인 웹챗봇", "디케이테크인 카카오워크"]);
        } else {
            Kakaoi.UI.hideAutoComplete();
        }
    }
});

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

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.