11.1공통

Naver 톡톡 상담톡 API
- Naver Chat Bot API 를 이용해서 Message 전송을 지원하는 기능을 제공합니다.
- http/https 프로토콜을 사용하며, GET, POST method를 사용합니다.
- response는 JSON형태 로 전달됩니다.
요청 도메인에 prefix (ntt)를 추가 해야합니다. (ex : https://tkakao.uconnect.co.kr/ntt )

11.1.1RESPONSE SAMPLE

[성공]

{
    "code": "0",                
    ... // 요청한 데이터
}

[잘못된 요청 또는 에러]

{
    "code": "99",
    "message": "상세 내용"                
}

11.1.2코드 정의

code	설명
0	요청 성공
01	Authorization 정보 오류 Authorization 정보가 잘못되었거나 이미 만료된 정보를 사용한 경우
02	request json 문자열 파싱 오류 JSON 구조에 문제가 있거나 필숫값이 없을 경우
99	실패에 대한 구체적 내역 01, 02 외에 처리 중 발생할 수 있는 다양한 오류에 관한 상세 설명
IMG-01	이미지 업로드 - 포맷 불일치 또는 처리 실패 업로드하는 이미지 포맷이 JPG, JPEG, PNG, GIF가 아니거나 그 외의 경우
IMG-02	이미지 업로드 - 전송/처리 시간 초과 업로드하는 이미지의 다운로드 시간이 10초를 초과하는 경우
IMG-03	이미지 업로드 - 크기 초과 업로드하는 이미지가 20MB를 넘는 경우
-404	요청실패 Naver톡톡 서버 접속 실패
-405	파라미터 오류
-406	파라미터 오류 Invalid sender_key
-407	auth_key 없음
-508	요청한 데이터 없음. Naver톡톡에서 수신한 데이터에서 body data 없음
-600	DB 처리 실패

11.2기본 기능

11.2.1대화창 typing on/off 요청

action typing 이벤트
- 대화창에서 메시지 수신이 늦어지는 경우 메시지가 처리 중이라는 것을 사용자에게 UI 적으로 알릴 때 사용할 수 있습니다. 일반적으로 typingOff 액션을 사용하기 보다는 typingOn 전송 후 메시지 send 이벤트를 전송합니다.
(내용참조) action 이벤트
- https://github.com/navertalk/chatbot-api#action-%EC%9D%B4%EB%B2%A4%ED%8A%B8

[Request]

POST /action/typing

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID
user_key	text(100)	Y	사용자 ID
action	text(10)	Y	typingOn: 작성중 이미지가 대화창에서 메시지 형태로 보입니다. 추가 액션이 없다면 10초 동안 유지됩니다. 연속해서 보내면 새로 보낸 시점부터 유지 시간이 갱신됩니다. typingOff: 작성중 이미지가 대화창에서 사라집니다. 다른 메시지를 send 이벤트로 보내도 동일한 효과가 있습니다.

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

11.2.2Persistent Menu (고정 메뉴) 설정 요청

persistent menu (고정 메뉴)
- 사용자가 대화 중에 상시로 접근할 수 있는 대화창 하단에 고정된 메뉴입니다. 사용자에게 챗봇을 소개하거나 공지, 이벤트를 안내하는 데 사용할 수 있습니다.
(내용참조) persistentMenu
- https://github.com/navertalk/chatbot-api#persistentmenu-%EC%9D%B4%EB%B2%A4%ED%8A%B8

[Request]

POST /menu/persistent

[Parameter]

키

타입

필수

설명

sender_key

text(40)

Partner ID

content

json

persistentMenu의 JSON 개체입니다.

(persistentMenu 내용을 참조하여 작성합니다.)

"menu_intlz" 값을 전달 시 persistent menu 를 초기화합니다.

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

// 전송 sample - 설정
{
  "sender_key": "w4m8cj",
  "content": {
    "menus": [
      {
        "type": "TEXT",
        "data": {
          "title": "챗봇 안내",
          "code": "CHATBOT_GUIDE"
        }
      },
      {
        "type": "LINK",
        "data": {
          "title": "이벤트 페이지",
          "url": "http://your-pc-url.com/event",
          "mobileUrl": "http://your-mobile-url.com/event"
        }
      },
      {
        "type": "LINK",
        "data": {
          "title": "전화하기",
          "url": "tel:021234567"
        }
      },
      {
        "type": "NESTED",
        "data": {
          "title": "공지사항",
          "menus": [
            {
              "type": "LINK",
              "data": {
                "title": "교환/환불 안내",
                "url": "http://your-pc-url.com/guide",
                "mobileUrl": "http://your-mobile-url.com/guide"
              }
            }
          ]
        }
      }
    ]
  }
}

// 전송 sample - 초기화
{
  "sender_key": "w4m8cj",
  "content": "menu_intlz"
}

11.2.3Image upload 요청

자주 사용되는 이미지를 미리 업로드합니다. 일반적으로 메시지 전송 시 imageContent나 compositeContent에서 사용하는 imageUrl은 매번 이미지를 업로드하므로 사용자에게 즉각적으로 메시지를 전달할 수 없습니다. 그러나 이미지를 미리 업로드하고 imageId를 이용해 메시지를 전달하면 텍스트 메시지와 같은 속도로 메시지가 전달됩니다. 특히, compositeContent의 캐로셀(Carousel) 방식으로 이미지를 여러 개 사용하는 경우 속도 차이는 더 극명합니다.

(내용참조) Image Upload API V1
- https://github.com/navertalk/chatbot-api/blob/master/imageupload_api_v1.md#image-upload-api-v1

[Request]

POST /image/upload

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID
image_url	text(2048)	Y	upload image url

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)
image_id	text	N	upload된 이미지의 id

11.3Message

11.3.1메시지 전송 요청

(내용참조) 메시지 타입 명세
- https://github.com/navertalk/chatbot-api#textcontent

메시지 타입이 text 일 경우 텍스트의 최대 길이는 영문/한글 구분 없이 1만자 이내로 전송해야 합니다.

[Request]

POST /message/send

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID
user_key	text(100)	Y	사용자 ID
message_type	text(20)	Y	메시지 타입 text image_url image_id composite BS: 봇정보
message	json (3000byte)	Y/N	보내는 메시지의 내용이 포함된 JSON 개체입니다. ('메시지 타입 명세' 내용을 참조하여 작성합니다. ) message_type 이 BS 일 경우는 필수가 아님.
notification	bool	N	메시지 전송 시 사용자 푸시 알림 여부를 설정합니다. true: 메시지 전송 시 사용자는 푸시 알림을 받습니다 false: 메시지 전송 시 사용자가 푸시 알림을 수신하지 않습니다. 기본값: false
bot_id	text(150)	N	넥서스 시나리오 봇 아이디(콜아이디)
bot_name	text(100)	N	넥서스 시나리오 봇 이름
bot_status	text(20)	N	TIMEOUT: 고객 응답 없음, CONNECT: 상담원 연결, BUSY:대기 상담원 없음. EXPIRE: 고객상담종료

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

// 전송 sample - text
{
  "sender_key": "w4m8cj",
  "user_key": "9Zz5abced0DDDoA2WwYoBN",
  "message_type": "text",
  "message": {
    "text": "안녕하세요."
  },
  "notification": false
}

// 전송 sample - image url
{
  "sender_key": "w4m8cj",
  "user_key": "9Zz5abced0DDDoA2WwYoBN",
  "message_type": "image_url",
  "message": {
    "imageUrl": "http://www.test.net/menu_01.png"
  },
  "notification": false
}

// 전송 sample - image id
{
  "sender_key": "w4m8cj",
  "user_key": "9Zz5abced0DDDoA2WwYoBN",
  "message_type": "image_id",
  "message": {
    "imageId": "pH_JynG7bh3eYCubB1dhsadebeDWn_BEtaf9nxME7UNTwv7eUb9nmmlKmpsA"
  },
  "notification": false
}

// 전송 sample - image composite
{
  "sender_key": "w4m8cj",
  "user_key": "9Zz5abced0DDDoA2WwYoBN",
  "message_type": "composite",
  "message": {
    "compositeList": [
      {
        "title": "타이틀",
        "description": "설명",
        "image": {
          "imageUrl": "http://www.test.net/menu_01.png"
        },
        "elementList": {
          "type": "LIST",
          "data": [
            {
              "title": "리스트 요소 타이틀",
              "description": "리스트 요소 설명1",
              "subDescription": "리스트 요소 설명2",
              "image": {
                "imageUrl": "http://www.test.net/menu_01.png"
              },
              "button": {
                "type": "TEXT",
                "data": {
                  "title": "요소버튼",
                  "code": "code"
                }
              }
            }
          ]
        },
        "buttonList": [
          {
            "type": "TEXT",
            "data": {
              "title": "텍스트형 버튼",
              "code": "code"
            }
          },
          {
            "type": "LINK",
            "data": {
              "title": "링크형 버튼",
              "url": "https://www.test.com/view/menu/1",
              "mobileUrl": "https://www.test.com/view/menu/1#nafullscreen"
            }
          },
          {
            "type": "OPTION",
            "data": {
              "title": "옵션형 버튼",
              "buttonList": [
                {
                  "type": "TEXT",
                  "data": {
                    "title": "옵션-텍스트버튼",
                    "code": "code"
                  }
                },
                {
                  "type": "LINK",
                  "data": {
                    "title": "옵션-링크버튼",
                    "url": "https://www.test.com/view/menu/1",
                    "mobileUrl": "https://www.test.com/view/menu/1#nafullscreen"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "notification": false
}

11.3.2장문 메시지 가져오기

"Naver 톡톡 biz 수신 API" 항목 중 "메시지 수신" API의 "is_message_attachment" 값이 true 일 경우 사용합니다.

메시지 수신 시 1000자 이상의 경우 전체 내용의 메시지 데이터는 별도로 저장되며, 해당 API로 내려받을 수 있습니다.

[Request]

GET /message/attachment

[Parameter]

키	타입	필수	설명
serial_number	text(50)	Y	메시지 고유 ID

11.3.3첨부파일 다운로드

Naver 톡톡 서버에서 삭제 전에 미리 저장한 첨부파일을 다운로드 합니다.
- 저장된 파일이 없을 경우 Naver 톡톡 서버에서 직접 다운로드 합니다.

다음 사항에 해당하는 파일 다운로드 기능을 제공합니다.
- 메시지 수신 시 첨부된 파일(현재는 이미지만 지원)

[Request]

GET /file/download

[Parameter]

키	타입	필수	설명
serial_number	text(300)	Y	메시지 수신 이벤트 serial number

11.4사용자 인증 정보

11.4.1사용자 정보 조회 요청

1:1 채팅 시 사용자 키에 전화번호 및 이름 등을 가져오기 위한 API 입니다.
사용자가 1:1 채팅 방에 입장 후 개인정보 수집 및 이용 동의가 먼저 이루어져야 정보를 가져올 수 있습니다.

[Request]

GET /user/info

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Parther ID
user_key	text(100)	Y	사용자 ID

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)
sender_key	text	N	Parther ID
user_key	text	N	사용자 ID
tel_number	text	N	사용자 전화번호
is_under14	bool	N	14세 나이 구분 (false: 만14세 이상, true: 만14세 미만)
is_under19	bool	N	19세 나이 구분 (false: 만19세 이상, true: 만19세 미만)

[Example]

http://127.0.0.1:8080/user/info?sender_key=w4m8cj&user_key=9HsQeroz777RFoV4WnVlZY

{
    "code": "0",
    "sender_key": "w4m8cj",
    "user_key": "9HsQeroz777RFoV4WnVlZY",
    "tel_number": "01077771234",
    "is_under14": false,
    "is_under19": false
}

11.5Admin

11.5.1partner 정보 설정

Naver 톡톡 파트너 센터(https://partner.talk.naver.com/)에서 파트너 정보를 설정합니다.
id 값을 기준으로 insert, update 처리를 제공합니다.

[Request]

POST /admin/partner/set

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID
name	text(100)	Y	Partner Name
auth_key	text(100)	Y	보내기 API 인증키
is_use	bool	N	true: 사용, false: 미사용 기본값: false
memo	text(100)	N	메모

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

11.5.2partner 정보 조회

Partner 정보를 조회합니다.

[Request]

GET /admin/partner

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID 전체 요청 시 "all"

키

타입

필수

설명

sender_key

text(40)

Partner ID

전체 요청 시 "all"

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)
data	json	N	Partner List

[Response] - data

키	-	타입	필수	설명
data		array	-	Partner List
	sender_key	text	Y	Partner ID
	name	text	Y	Partner Name
	auth_key	text	Y	보내기 API 인증키
	is_use	bool	Y	true: 사용, false: 미사용
	memo	text	Y	메모
	reg_date	text	Y	등록 일자
	mod_date	text	Y	수정 일자

11.5.3partner 정보 삭제

Partner 정보를 삭제합니다.

[Request]

POST /admin/partner/del

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

11.5.4Domain 정보 설정

JEDAI 서버의 Domain 정보를 설정합니다. (domain + port)
- ex) https://nexus.net:443

[Request]

POST /admin/domain/set

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID
domain	text(500)	Y	JEDAI 서버의 Domain

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

11.5.5Domain 정보 조회

Domain 정보를 조회합니다.

[Request]

GET /admin/domain

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID 전체 요청 시 "all"

키

타입

필수

설명

sender_key

text(40)

Partner ID

전체 요청 시 "all"

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)
data	json	N	Domain List

[Response] - data

키	-	타입	필수	설명
data	-	array	-	Domain List
	sender_key	text		Partner ID
	domain	text	Y	Domain
	~~create_date~~ reg_date	text	Y	등록 일자
	~~modified_date~~ mod_date	text	Y	수정 일자

11.5.6Domain 정보 삭제

Domain 정보를 삭제합니다.

[Request]

POST /admin/domain/del

[Parameter]

키	타입	필수	설명
sender_key	text(40)	Y	Partner ID

[Response]

키	타입	필수	설명
code	text	Y	처리 결과 코드(0은 정상 / 나머지는 오류)
message	text	N	오류 메시지(오류시 존재하는 값)

11.Naver 톡톡 상담톡 API

11.1공통

11.1.1RESPONSE SAMPLE

11.1.2코드 정의

11.2기본 기능

11.2.1대화창 typing on/off 요청

11.2.2Persistent Menu (고정 메뉴) 설정 요청

11.2.3Image upload 요청

11.3Message

11.3.1메시지 전송 요청

11.3.2장문 메시지 가져오기

11.3.3첨부파일 다운로드

11.4사용자 인증 정보

11.4.1사용자 정보 조회 요청

11.5Admin

11.5.1partner 정보 설정

11.5.2partner 정보 조회

11.5.3partner 정보 삭제

11.5.4Domain 정보 설정

11.5.5Domain 정보 조회

11.5.6Domain 정보 삭제