CLOSER Webhook 연동 가이드

CLOSER에서 전송하는 webhook의 자료 형태와 설정 방법등을 안내합니다.

CLOSER에서는 메시지 수신/발신, 고객 추가/삭제에 대한 이벤트들을 전달하는 webhook을 제공합니다.

Webhook 연동에 도움이 필요하시다면 [e-mail]로 문의해주세요.

Webhook 설정 단계

1. 본 문서에서는 Webhook의 포맷에 따라 목적에 맞는 API를 개발하세요.

2. CLOSER Bot에서 개발하신 API의 URL을 등록합니다.

3. CLOSER의 Bot을 사용시 발생하는 이벤트를 개발하신 API로 전송합니다.

Web Builder 에서 Webhook 전송 설정

• Builder > 봇 설정 > Webhook 관리에서 Webhook URL을 등록/수정/삭제 하실 수 있습니다

• 등록하신 Webhook URL이 동작하지 않는 경우 Builder에서 Webhook 전송이 자동으로 비활성화 됩니다

CLOSER에서 전송하는 Webhook 포맷

Webhook HTTP Headers

Key	Value
user-agent	CLOSER/webhook
content-type	application/json

Webhook POST body Example

일반

{
     "id": "00000000-0000-0000-0000-000000000000",
     "webhookId": "00000000-0000-0000-0000-000000000000",
     "webhookUrl": "http://your.webhook.com",
     "messages": [{
         "id": "00000000-0000-0000-0000-000000000000",
         "sourceId": "Bxxxxx",
         "sourceType": "bot",
         "event": "bot.end_user.updated",
         "data": {
             "endUser": {
                 "createdAt": "2018-09-04T07:06:53.047Z",
                 "deletedAt": null,
                 "id": "00000000-0000-0000-0000-000000000000",
                 "botId": "Bxxxxx",
                 "lastMessageId": "00000000-0000-0000-0000-000000000000",
                 "params": {
                 },
                 "platform": "web",
                 "userKey": "userKey",
                 "lastConversationId": "00000000-0000-0000-0000-000000000000",
                 "updatedAt": "2018-09-05T06:45:19.087Z"
             }
         },
         "timestamp": 1536129919092
     }, {
         "id": "00000000-0000-0000-0000-000000000001",
         "sourceId": "Bxxxxx",
         "sourceType": "bot",
         "event": "bot.conversation.created",
         "data": {
             "conversation": {
                 "endUserId": "00000000-0000-0000-0000-000000000000",
                 "createdAt": "2018-09-05T06:45:19.102Z",
                 "navigation": {},
                 "context": {
                     "navigation": {},
                     "conversationId": "00000000-0000-0000-0000-000000000000",
                     "botId": "Bxxxxx",
                     "params": {
                     },
                     "platform": "web",
                     "userKey": "userKey"
                 },
                 "id": "00000000-0000-0000-0000-000000000000",
                 "botId": "Bxxxxx",
                 "params": {
                 },
                 "userKey": "userKey",
                 "platform": "web",
                 "updatedAt": "2018-09-05T06:45:19.102Z"
             }
         },
         "timestamp": 1536129919116
     }]
 }

상담원 메시지

{
    "id": "00000000-0000-0000-0000-000000000000",
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "webhookUrl": "http://your.webhook.com",
    "messages": [{
        "id": "00000000-0000-0000-0000-000000000000",
        "sourceId": "Bxxxxx",
        "sourceType": "bot",
        "event": "bot.message.sent",
        "data": {
            "message": {
                "endUserId": "00000000-0000-0000-0000-000000000000",
                "data": {
                    "text": "상담원 메시지",
                    "type": "text"
                },
                "requestId": "00000000-0000-0000-0000-000000000000",
                "meta": {
                    "sender": {
                        "userKey": "Uxxxxx",
                        "platform": "closer-chat"
                    }
                },
                "conversationId": "00000000-0000-0000-0000-000000000000",
                "id": "00000000-0000-0000-0000-000000000000",
                "isUser": false,
                "timestamp": 1536130434645
            }
        },
        "timestamp": 1536130434656
    }]
}

봇 메시지

{
     "id": "00000000-0000-0000-0000-000000000000",
     "webhookId": "00000000-0000-0000-0000-000000000000",
     "webhookUrl": "http://your.webhook.com",
     "messages": [{
         "id": "00000000-0000-0000-0000-000000000000",
         "sourceId": "Bxxxxx",
         "sourceType": "bot",
         "event": "bot.message.sent",
         "data": {
             "message": {
                 "endUserId": "00000000-0000-0000-0000-000000000000",
                 "data": {
                     "text": "테스트용 봇 메시지",
                     "type": "text"
                 },
                 "conversationId": "00000000-0000-0000-0000-000000000000",
                 "meta": null,
                 "id": "00000000-0000-0000-0000-000000000000",
                 "isUser": false,
                 "timestamp": 1536129919339
             }
         },
         "timestamp": 1536129919373
     }]
 }

고객 메시지

{
     "id": "00000000-0000-0000-0000-000000000000",
     "webhookId": "00000000-0000-0000-0000-000000000000",
     "webhookUrl": "http://your.webhook.com",
     "messages": [{
         "id": "00000000-0000-0000-0000-000000000000",
         "sourceId": "Bxxxxx",
         "sourceType": "bot",
         "event": "bot.message.received",
         "data": {
             "message": {
                 "endUserId": "00000000-0000-0000-0000-000000000000",
                 "data": {
                     "text": "고객 메시지",
                     "type": "text"
                 },
                 "requestId": "00000000-0000-0000-0000-000000000000",
                 "conversationId": "00000000-0000-0000-0000-000000000000",
                 "meta": null,
                 "id": "00000000-0000-0000-0000-000000000000",
                 "isUser": true,
                 "timestamp": 1536130242636
             }
         },
         "timestamp": 1536130243609
     }]
 }

Objects

DELIVERY

키	타입	필수	설
id	UUID	Y	Delivery ID
webhookId	UUID	Y	Webhook ID
webhookUrl	String	Y	Webhook URL
messages	Array(Object(EVENT))	Y	Event 오브젝트의 배열. 일정 시간동안 발생한 이벤트를 배열로 묶어 전달합니다.

EVENT

키	타입	필수	설명
id	UUID	Y	Event ID
event	String(EVENT_TYPE)	Y	Event 구분
sourceType	String('bot')	Y	Event를 발행한 소스
sourceId	String(BOT.id)	Y	Event 발행한 타입의 아이디. 'bot'인 경 Bot ID
timestamp	UNIX Timestamp with milliseconds	Y	Event 발생 시간
data	Object(EVENT.DATA)	Y	Event의 데이터

EVENT.DATA

키	타입	필수	설명
bot	Object(BOT)	C	event가 bot인 경우 필수
endUser	Object(ENDUSER)	C	event가 bot.end_user인 경우 필수
conversation	Object(CONVERSATION)	C	event가 bot.conversation인 경우 필
message	Object(MESSAGE)	C	event가 bot.message인 경우 필수

BOT

키	타입	필수	설명
id	String	Y	Bot의 ID
title	String(30)	Y	Bot의 이름
description	String(100)	N	Bot의 설명
integration	Object(BOT.INTEGRATION)	N	Bot의 연동 정보
preference	Object(BOT.PREFERENCE)	N	Bot의 설정 정보
data	Object(BOT.DATA)	N	Bot 동작에 필요한 데이터
createdAt	String(DateTime)	Y	생성 날짜
updatedAt	String(DateTime)	Y	업데이트 날짜
deletedAt	String(DateTime)	N	삭제 날짜

ENDUSER

키	타입	필수	설명
id	UUID	Y	EndUser의 ID
botId	String(BOT.id)	Y	Bot의 ID
platform	String(PLATFORM_TYPE)	Y	메신저 타입
userKey	String(90)	Y	사용자 고유 키값
params	Object(Dictionary)	N	대화에서 사용하는 파라미터
lastMessageId	UUID(MESSAGE.id)	N	마지막 메시지의 ID
lastConversationId	UUID(CONVERSATION.id)	N	마지막 대화의 ID
lastConversation	Object(CONVERSATION)	N	마지막 대화 Object
createdAt	String(DateTime)	Y	생성 날짜
updatedAt	String(DateTime)	Y	업데이트 날짜
deletedAt	String(DateTime)	N	삭제 날짜

CONVERSATION

키	타입	필수	설명
id	UUID	Y	Conversation의 ID
botId	String(BOT.id)	Y	Bot의 ID
endUserId	UUID(ENDUSER.id)	Y	EndUser의 ID
platform	String(PLATFORM_TYPE)	Y	메신저 타입
userKey	String(90)	Y	사용자의 고유 키값
params	Object(Dictionary)	N	대화에서 사용하는 파라미터
context	Object(CONTEXT)	N	대화의 정보
navigation	Object(CONTEXT.NAVIGATION)	N	대화의 위치
createdAt	String(DateTime)	Y	생성 날짜
updatedAt	String(DateTime)	Y	업데이트 날짜

MESSAGE

키	타입	필수	설명
id	UUID	Y	Message의 ID
endUserId	UUID(ENDUSER.id)	Y	EndUser의 ID
conversationId	UUID(CONVERSATION.id)	Y	Conversation의 ID
isUser	Boolean	Y	true인 경우 고객, false인 경우 봇이나 상담원
meta	Object(MESSAGE.META)	N	상담원이 경우 meta에 상담원 정보가 포함됨
data	Object(MESSAGE.DATA)	Y	메시지의 데이터
timestamp	UNIX Timestamp with milliseconds	Y	메시지 발행 시간

MESSAGE.DATA

키	타입	필수	설명
type	String(MESSAGE_TYPE)	Y	MESSAGE의 타입
text	String(1000)	C	text 타입인 경우 필수
media	Object(MESSAGE.DATA.MEDIA)	C	media 타입인 경우 필수
cards	Array(Object(MESSAGE.DATA.CARD))	C	cards 타입인 경우 필수
location	Object(MESSAGE.DATA.LOCATION)	C	location 타입인 경우 필수
button	Object(MESSAGE.DATA.BUTTON)	N	메시지에 포함된 버튼으로 KEYBOARD.BUTTON과는 형식과 동작이 다름. 링크 삽입 가능

MESSAGE.META

키	타입	필수	설명
sender	Object(MESSAGE.META.SENDER)	N	메시지를 전송한 전송자의 정보

MESSAGE.DATA.MEDIA

키	타입	필수	설명
contentType	'image', 'video', 'audio', 'link'	Y	이미지, 동영상, 오디오, 링크
uri	String	Y	이미지, 동영상, 오디오, 링크의 URL

MESSAGE.DATA.BUTTON

키	타입	필수	설명
label	String(255)	Y	버튼 인터페이스에 노출할 이름
uri	String	N	버튼이 링크로 동작 시 URL, 없으면 키보드 입력 동작

MESSAGE.DATA.CARD

키	타입	필수	설명
title	String(50)	Y	카드의 제목
description	String(500)	N	카드의 설명
media	Object(MESSAGE.DATA.MEDIA)	N	카드에 포함될 미디어
uri	String	N	카드 선택시 이동할 링크 URL
buttons	Array(Object(MESSAGE.DATA.BUTTON))	N	카드에 포함된 버튼 리스트

MESSAGE.DATA.LOCATION

키	타입	필수	설명
title	String(50)	N	위치의 이름
latitude	Number	Y	GPS Latitude
longitude	Number	Y	GPS longitude

MESSAGE.META.SENDER

키	타입	필수	설명
userKey	String(90)	Y	SENDER 사용 시 필수. 전송자의 ID
platform	String(100)	Y	SENDER 사용 시 필수. 전송자의 플랫폼

KEYBOARD

• CLOSER의 입력 Object로, 사용자의 입력 타입을 표현합니다.

• text인 경우 사용자는 text를 입력할 수 있고, number인 경우 제약조건을 포함합니다.

• buttons는 사용자의 입력을 button으로 받을 수 있도록 필요한 데이터를 포함합니다.

KEYBOARD의 사용자 입력 전송 방식

• text : 사용자가 입력한 텍스트를 그대로 메시지에 전송합니다.

• buttons : 사용자가 선택한 button의 label의 텍스트를 메시지에 전송합니다.

• number : text와 동일하지만, 조건을 Front에서 검증하도록 개발할 수 있습니다.

키	타입	필수	설명
type	'text', 'number', 'buttons'	Y	텍스트, 숫자, 버튼 입력
min	Number	C	number 타입인 경우에 필수, 최소값
max	Number	C	number 타입인 경우에 필수, 최대값
parse	Boolean	N	false인 경우 숫자만 입력 가능, true인 경우 주어진 문자열에서 숫자만 읽어들임
integer	Boolean	N	false인 경우 Integer만 입력 가능
buttons	Array(Object(KEYBOARD.BUTTON))	C	buttons 타입인 경우에 필수

KEYBOARD.BUTTON

키	타입	필수	설명
label	String(255)	Y	버튼 인터페이스에 노출할 이름
params	Object(Dictionary)	N	버튼 선택 시 저장되는 파라미터. key - value dictionary 타입

CONTEXT

CLOSER에서 대화를 진행하는데 필요한 정보입니다. SDK의 WebChatClient가 Open되면 Context를 message listener에 전송합니다.

키	타입	필수	설명
botId	String	Y	Bot의 ID
conversationId	UUID	Y	대화의 ID. CLOSER에서 자동으로 생성됨
endUserId	UUID	Y	최종사용자의 ID. CLOSER에서 자동으로 생성됨
navigation	Object(CONTEXT.NAVIGATION)	N	현재 대화의 위치를 표현하는 오브젝트
params	Object(Dictionary)	N	현재 대화에서 사용하고 있는 파라미터
platform	String(PLATFORM_TYPE)	Y	플랫폼 타입
userKey	String(90)	Y	최종사용자 식별 키. SDK Open시 주입한 값

CONTEXT.NAVIGATION

키	타입	필수	설명
current	Object(CONTEXT.NAVIGATION.NODE)	Y	현 노드의 정보
prev	Object(CONTEXT.NAVIGATION.NODE)	N	이전 노드의 정보

CONTEXT.NAVIGATION.NODE

키	타입	필수	설명
flowId	Number	Y	현재 노드의 플로우 ID
nodeId	Number	Y	현재 노드의 ID
visitCount	Number	N	최종사용자가 노드에 방문한 수

AGENT

키	타입	필수	설명
id	String	Y	상담원의 User ID
profile	Object(AGENT.PROFILE)	N	상담원의 profile 정보

AGENT.PROFILE

키	타입	필수	설명
displayName	String(30)	N	상담원의 DisplayName
picture	URL	N	상담원의 프로필 이미지 URL

Types

EVENT_TYPE

타입	설명
bot.updated	Bot의 정보 업데이트
bot.deleted	Bot이 삭제됨
bot.end_user.created	새로운 EndUser 생성
bot.end_user.updated	EndUser의 정보 업데이트
bot.end_user.deleted	EndUser가 삭제됨(친구삭제 등)
bot.conversation.created	새로운 Conversation 생성
bot.conversation.updated	Conversation의 정보 업데이트
bot.conversation.deleted	Conversation이 삭제됨(대화 만료)
bot.conversation.agent_call_requested	상담원에게 상담 요청
bot.conversation.agent_call_connected	상담 시작
bot.conversation.agent_call_cancelled	상담원에게 상담요청을 고객이 취소
bot.conversation.agent_call_disconnected	상담 종료
bot.message.sent	메시지 전송(봇, 상담원)
bot.message.received	메시지 수신(사용자)

PLATFORM_TYPE

타입	설명
kakao	카카오톡 스마트 API
kakaobiz	카카오 상담톡
facebook	페이스북 메신저
line	라인
navertalk	네이버톡톡
bizchat	SMS 문자 메시지 채팅 BizChat
wechat	위챗
web	웹챗
test	테스트용 챗

MESSAGE_TYPE

타입	설명
text	텍스트 메시지
media	이미지, 동영상, 오디오 등의 미디어
cards	카드 타입 리스트 (Carousel로 사용)
location	위치 정보 (latitude, longitude)