10.1개요

작동방식
- 고객이 Naver 톡톡을 통해 대화창 진입후 메시지를 보냅니다.
- Naver 톡톡 플랫폼은 "JEDAI 상담톡 발신/수신 서버(이하 JEDAI 상담톡 서버)"의 "Webhook URL"로 "Webhook Event"를 보냅니다.
- "Webhook Event"에 따라 "JEDAI 상담톡 서버"는 "JEDAI 서버"와 "상담원" 간의 절차를 진행 후 받은 메시지를 Naver 톡톡 플랫폼을 통해 고객에게 응답합니다.
수신 도메인에 prefix (ntt)를 추가 해야합니다. (ex : https://tkakao.uconnect.co.kr/ntt )

10.1.1시퀀스 다이어그램 (Sequence Diagram)

그림 10-1Line Sequence Diagram

10.2수신 이벤트

10.2.1open 이벤트

사용자가 채팅창에 진입할 때 유입 정보와 함께 open 이벤트를 전송합니다.
(내용참조) open 이벤트
- https://github.com/navertalk/chatbot-api#open-%EC%9D%B4%EB%B2%A4%ED%8A%B8

만 14세 미만일 경우 open 이벤트는 전송되지 않습니다.
"고객 인증"이 이루어진 후 부터 open 이벤트가 전송됩니다.

수신 URL Sample : https://tkakao.uconnect.co.kr/ntt/open ( 수신도메인 + 메시지 수신 path )

주의사항

개인정보수집을 위한 약관 동의시 만14세 미만의 경우 법정대리인의 동의를 받아야 합니다.(개인정보보호법 제22조)
만약, 개인정보를 수집한다면 법정대리인 동의 프로세스를 구현하거나 만 14세 미만은 사용하지 못하도록 안내하여야 합니다.

* 현재 만 14세 미만 사용자에 대해서는 "JEDAI 상담 발신/수신" 서버에서 채팅을 사용하지 못하도록 안내처리가 추가된 상태입니다.

path : /open
method : POST
header
- Content-type: application/json
request body에 Json 형태의 데이터 전달

키	타입	설명
chat_type	text	NAVER_TALK_TALK
serial_number	text	메시지 고유 ID
sender_key	text	Partner ID
user_key	text	사용자 ID
inflow	text	유입 방법 list: 채팅리스트에서 인입 button: 버튼이나 링크로 인입 none: 유입 경로가 없을 때(or 브라우저 주소창에 URL을 직접 입력해 유입)
referer	text	유입 페이지 url
from	text	별도로 from 파라미터를 사용시 받는 값
friend	bool	친구 추가 여부 true: 친구 false: 친구 아님
under14	bool	14세 나이구분 true: 만14세 미만 false: 만14세 이상
under19	bool	19세 나이구분 true: 만19세 미만 false: 만19세 이상
unreadMessage	bool	파트너나 챗봇이 보낸 메시지 중 읽지 않은 메시지 존재 여부 true: 읽지 않은 메시지 있음 false: 읽지 않은 메시지 없음
mobile	bool	이벤트 발생 시 모바일 여부 true: 모바일 false: 모바일 아님

{
  "chat_type": "NAVER_TALK_TALK",
  "serial_number": "7rRUT8AEgFnf-0005-6285FA6B",
  "sender_key": "w4m8te",
  "user_key": "1vZZZ8AEgFFFwZZZkKKkMM",
  "inflow": "list",
  "referer": "https:\\/\\/talk.naver.com\\/",
  "from": "",
  "friend": true,
  "under14": false,
  "under19": false,
  "unreadMessage": false,
  "mobile": true
}

10.2.2leave 이벤트

사용자가 채팅창 또는 채팅리스트에서 나가기를 누르면 발생하는 이벤트입니다.
(내용참조) leave 이벤트
- https://github.com/navertalk/chatbot-api#leave-%EC%9D%B4%EB%B2%A4%ED%8A%B8

"고객 인증"이 이루어진 후 부터 leave 이벤트가 전송됩니다.

path : /leave
method : POST
header
- Content-type: application/json
request body에 Json 형태의 데이터 전달

키	타입	설명
chat_type	text	NAVER_TALK_TALK
serial_number	text	메시지 고유 ID
sender_key	text	Partner ID
user_key	text	사용자 ID
mobile	bool	이벤트 발생 시 모바일 여부 true: 모바일 false: 모바일 아님

10.2.3friend 이벤트

~~사용자가 친구추가 또는 친구철회를 누르면 발생하는 이벤트입니다.~~

(2019년 8월 부로 친구추가가 소식받기로 변경됨)

사용자가 소식받기 설정 또는 해제를 누르면 발생하는 이벤트입니다.

(내용참조) friend 이벤트
- https://github.com/navertalk/chatbot-api#friend-%EC%9D%B4%EB%B2%A4%ED%8A%B8

"고객 인증"이 이루어진 후 부터 friend 이벤트가 전송됩니다.

path : /friend
method : POST
header
- Content-type: application/json
request body에 Json 형태의 데이터 전달

키	타입	설명
chat_type	text	NAVER_TALK_TALK
serial_number	text	메시지 고유 ID
sender_key	text	Partner ID
user_key	text	사용자 ID
set	text	소식받기 여부 on: 소식받기 설정 off: 소식받기 해제
mobile	bool	이벤트 발생 시 모바일 여부 true: 모바일 false: 모바일 아님

// 소식받기 설정
{
  "chat_type": "NAVER_TALK_TALK",
  "serial_number": "7rRUT8AEgFnf-0008-6285FB48",
  "sender_key": "w4m8te",
  "user_key": "1vZZZ8AEgFFFwZZZkKKkMM",
  "set": "on",
  "mobile": false
}

// 소식받기 해제
{
  "chat_type": "NAVER_TALK_TALK",
  "serial_number": "7rRUT8AEgFnf-0009-6285FB81",
  "sender_key": "w4m8te",
  "user_key": "1vZZZ8AEgFFFwZZZkKKkMM",
  "set": "off",
  "mobile": false
}

10.2.4메시지 수신 이벤트

사용자가 메시지를 보낼 때 발생하는 이벤트입니다
- 텍스트, 이미지, 이모티콘, 안심전화상담

(내용참조) send 이벤트
- https://github.com/navertalk/chatbot-api#send-%EC%9D%B4%EB%B2%A4%ED%8A%B8

만 14세 미만일 경우 메시지 수신 이벤트는 전송되지 않습니다.
만 14세 이상이고 "고객 인증"이 이루어진 후 부터 메시지 수신 이벤트가 전송됩니다.

"is_message_attachment" 값이 true 일 경우

"Naver 톡톡 biz 상담톡 API" 항목 중 "장문 메시지 가져오기"를 사용하여 전체 내용의 메시지를 요청하여 받을 수 있습니다.

수신한 메시지 타입이 이미지 일 경우

"Naver 톡톡 biz 상담톡 API" 항목 중 "첨부파일 다운로드"를 사용하여 메시지 수신 시 첨부된 파일을 다운로드 할 수 있습니다.

path : /message
method : POST
header
- Content-type: application/json
request body에 Json 형태의 데이터 전달

키	타입	설명
chat_type	text	NAVER_TALK_TALK
serial_number	text	메시지 고유 ID
sender_key	text	Partner ID
user_key	text	사용자 ID
message_id	text	message id (Naver 톡톡에서 전달받은 ID)
message_type	text	메시지 타입 text : 키보드 입력, 버튼, 이모티콘, 안심전화상담, 상품문의 image_url : 이미지 전송(url)
message	json	수신된 메시지 데이터
mobile	bool	이벤트 발생 시 모바일 여부 true: 모바일 false: 모바일 아님
is_message_attachment	bool	문자 메시지 수신 시 (event_type: "text") 장문의 텍스트일 경우 메시지의 일부분만 내려주고, 전체 내용의 메시지 데이터는 별도로 저장되어 API로 내려받을 수 있습니다. true 저장된 전체 내용 메시지 존재 false 저장된 전체 내용 메시지 없음
e164	text	사용자 ID 로 찾은 사용자 전화번호
user_name	text	사용자 ID 로 찾은 사용자 닉네임

[Response] - message: * data_type: text

키	-	타입	필수	설명
message	-		-	수신된 메시지 데이터
	text	text	Y	text message
	input_type	text	Y	사용자가 입력한 타입 typing: 키보드 입력 button: 버튼 sticker: 이모티콘 vphone: 안심전화상담 product: 상품문의
	code	text	N	버튼에 설정한 code 값 quick button compositeContent 내 버튼
	product	json	N	input_type 이 product 일 경우 product 상세 정보 포함.

{
  "chat_type": "NAVER_TALK_TALK",
  "serial_number": "7rRUT8AEgFnf-000A-6285FC0F",
  "sender_key": "w4m8te",
  "user_key": "1vZZZ8AEgFFFwZZZkKKkMM",
  "message_id": "17893",
  "message_type": "text",
  "message": {
    "text": "Text",
    "input_type": "typing"
  },
  "mobile": true,
  "is_message_attachment": false,
  "e164": "01077778888",
  "user_name": ""
}

[Response] - message: * data_type: image_url

키	-	타입	필수	설명
message	-		-	수신된 메시지 데이터
	~~imageUrl~~ image_url	text	Y	image url
	width	int	Y	image width
	height	int	Y	image height

{
  "chat_type": "NAVER_TALK_TALK",
  "serial_number": "7rRUT8AEgFnf-000B-6285FCEA",
  "sender_key": "w4m8te",
  "user_key": "1vZZZ8AEgFFFwZZZkKKkMM",
  "message_id": "17894",
  "message_type": "image_url",
  "message": {
    "image_url": "https:\\/\\/shop-phi.net\\/20220519_250\\/1_JPEG\\/165356.jpg",
    "width": "1960",
    "height": "4032",
  },
  "mobile": true,
  "e164": "01077778888",
  "is_message_attachment": false,
  "user_name": ""
}