10.Naver 톡톡 수신 API

Edit

10.1개요

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

그림 10-1Line Sequence Diagram

10.2(BIZTALK → PBX) 수신 이벤트

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 상담 발신/수신" 서버에서 채팅을 사용하지 못하도록 안내처리가 추가된 상태입니다.

키

타입

설명

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 이벤트가 전송됩니다.

키

타입

설명

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 이벤트가 전송됩니다.

키

타입

설명

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" 항목 중 "첨부파일 다운로드"를 사용하여 메시지 수신 시 첨부된 파일을 다운로드 할 수 있습니다.

키

타입

설명

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": ""
}

10.2.5사용자 세션 생성 이벤트

  • 사용자로부터 메시지 수신 시 기존 세션 정보가 없거나 만료된 경우 신규 세션 생성과 동시에 발생하는 이벤트 입니다.

    • 해당 이벤트는 “Naver 톡톡”이 아닌 “상담톡 발신/수신”서버에서 자체 발생합니다.

키

타입

설명

chat_type

text

NAVER_TALK_TALK

sender_key

text

Partner ID

user_key

text

사용자 ID

session_id

text

세션 아이디

reference

object

(JSON)

메타 정보

키

-

타입

필수

설명

reference

-


-



inflow

text

Y

유입 정보


referer

text

Y

유입 페이지


under14

bool

Y

false: 만14세 이상, true: 만14세 미만


under19

bool

Y

false: 만19세 이상, true: 만19세 미만


mobile

bool

Y

기기 유형 - false: PC, true: 모바일


from

text

N

상품 ID 등 특정 맥락을 전달하는 파라미터.

동일 페이지 내 여러 상품 구분 시 유용.

10.2.6사용자 세션 종료 이벤트

  • 세션 종료 시 발생하는 이벤트 입니다.

    • 해당 이벤트는 “Naver 톡톡”이 아닌 “상담톡 발신/수신”서버에서 자체 발생합니다.

    • 해당 이벤트가 발생하는 경우는 다음과 같습니다.

      • “상담 종료(Session 종료) API” 사용

      • “상담톡 발신/수신”서버에서 자동 세션 종료 처리

키

타입

설명

chat_type

text

NAVER_TALK_TALK

sender_key

text

Partner ID

user_key

text

사용자 ID

session_id

text

세션 아이디

10.3(PBX → BIZTALK) 상담사 정보

10.3.1상담사 연결 시 세션 정보 업데이트

  • 사용자로부터 메시지 수신 후 상담사 연결 시 PBX로부터 받는 데이터를 세션 정보에 업데이트 합니다.

[Request]

키

타입

설명

chat_type

text

NAVER_TALK_TALK

sender_key

text

Partner ID

user_key

text

사용자 ID

uuid

text

uuid

agent_dn

text

상담원 DN

agent_vdn

text

상담원 VDN

[Response]

키

타입

필수

설명

code

text

Y

처리 결과 코드(0은 정상 / 나머지는 오류)

message

text

N

오류 메시지(오류시 존재하는 값)

[Sample]
[요청]
curl -v \
-X POST \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-d '
{
    "chat_type": "NAVER_TALK_TALK", 
    "user_key": "9Hs5exoqd0TRDoN3PwVlFQ", 
    "sender_key": "w4m8cj", 
    "uuid": "DB7B706E28B241784E6EC6695D21EB17", 
    "agent_dn": "30010", 
    "agent_vdn": "30010" 
}
' \
"http://127.0.0.1:8446/ntt/session/info"

[성공]
{
  "code": "0",
}

[잘못된 요청 또는 에러]
{
  "code": "99",
  "message": "상세 내용"
}