Skip to content

Latest commit

 

History

History
executable file
·
127 lines (98 loc) · 8.15 KB

profile_api_v1.md

File metadata and controls

executable file
·
127 lines (98 loc) · 8.15 KB
Raw

Profile API V1

업데이트 (2018.11.26.)

휴대전화번호, 주소 데이터 관리 주체 변경

네이버톡톡에서 관리하던 휴대전화번호는 네이버회원정보에서 관리하는 정보를, 주소는 N페이 통합배송지 에서 관리하는 정보를 제공하도록 변경되었습니다.

UI 변경

기존에는 회원의 수집/제공 동의를 얻기 위해서 사용자와 대화 형식의 인터랙션을 제공했었습니다만, 앞으로는 모바일에선 웹뷰 형식, PC에선 팝업 형식의 인터랙션을 제공합니다. 따라서 챗봇의 대화 흐름에 끼어들지 않고, 좀 더 분리된 형태로 정보 제공 동의 절차를 진행할 수 있게 되었습니다. 기타 세부사항은 아래 설명 참고 부탁드리겠습니다.

개요

Profile API는 Chat Bot API의 확장 API로서, 네이버 회원 정보를 요청할 수 있습니다. Profile API는 이벤트 형식 API이며 회원 정보 요청 시 사용자의 개인정보 제3자 제공 동의 하에 정보를 제공합니다.

제공 가능한 네이버 회원 정보는 다음과 같습니다.

  • 닉네임
  • 휴대전화번호
  • 주소

Profile API 동작 흐름

Profile API 사용 시 동작 흐름은 다음과 같습니다.

  1. 챗봇에서 회원 정보가 필요할 때 profile 이벤트를 네이버 톡톡에 전송합니다. profile 이벤트 전송 시 field 항목에 하나의 정보 필드만 요청할 수 있습니다.
  2. 네이버 톡톡은 챗봇으로부터 profile 이벤트를 받으면 곧바로 SUCCESS 응답을 보냅니다(Non-Blocking).
  3. 네이버 톡톡은 챗봇이 요청한 field에 대해 사용자가 챗봇에게 개인정보 제3자 제공 동의를 했는지 판단하여 처리합니다.
    • 동의했다면 요청한 정보를 담아 profile 이벤트를 챗봇에게 전송합니다. Profile API 호출에 대한 응답(Response)으로 데이터가 전달되는 것이 아니라, 웹훅으로 전달됩니다.
    • 사용자가 개인정보 제3자 제공 동의를 하지 않았다면 네이버 톡톡은 사용자와 동의 절차를 진행합니다.
      • 네이버 톡톡과 챗봇 사이의 연결이 동의 절차가 완료될 때까지 일시적으로 중단됩니다.
      • 동의 절차가 완료되기 전까지 사용자 이벤트가 챗봇으로 전달되지 않습니다. 또한 챗봇이 보내는 이벤트도 전달되지 않고 Error 코드로 응답이 옵니다.
  4. 다음과 같이 네이버 톡톡과 사용자 사이에 동의 절차가 완료됩니다.
    • 사용자가 동의한 경우 "result": "SUCCESS"와 요청한 정보 필드값을 담아서 profile 이벤트를 웹훅으로 전송합니다. API 호출에 대한 응답(Response)이 아닙니다.
    • 사용자가 프로필 제공을 원하지 않을 경우나 휴대전화번호가 등록되지 않은 상태에서 확인 버튼을 누르게 되면, "result": "CANCEL" 만 담아서 profile 이벤트를 전송합니다.
    • 사용자가 동의 절차 진행 중 정해진 시간 내에 응답하지 않으면 타임아웃이 발생할 수 있습니다.
      • 사용자와 동의 절차를 진행하는 과정에서 메시지를 주고받다가 마지막 메시지로부터 1분 이상 지체되면 타임아웃이 발생합니다.
      • 타임아웃 발생 시 챗봇으로 profile 이벤트가 전송되지 않으며 네이버 톡톡과 챗봇 사이에 일시 중지된 연결이 재개됩니다.
      • 챗봇에서는 기대했던 회원 정보를 받지 못한 상태로 이벤트가 재개되었으므로 상황에 따라 profile 이벤트를 다시 요청하거나 대화를 처음부터 진행하면 됩니다.

개인정보 제3자 제공 동의 절차 최소화 방안

챗봇이 nickname, cellphone, address 정보가 필요할 때 한 번에 하나씩 요청할 경우 결국 사용자는 세 번의 동의 절차를 거쳐야 합니다. 처음 nickname을 요청할 때 "agreements": [ "cellphone", "address" ]를 이용해 세 가지 필드에 대한 동의를 한 번에 받을 수 있습니다.
만약 nickname에 대해 개인정보 제공 동의가 되어 있는 상태에서 "agreements": [ "cellphone", "address" ]를 추가로 요청한다면 사용자의 동의 절차 없이 nickname만 전달됩니다. 즉, nickname에 대해 개인정보 제공 동의가 되어 있지 않다면 어차피 동의를 받아야 하므로 agreements 항목도 포함해서 동의를 받습니다. 하지만 nickname에 대해 개인정보 제공 동의가 이미 되어 있다면 agreements는 현재 필요한 정보가 아니므로 무시하고, 다음 번 "field": "cellphone"을 요청할 때 동의 절차를 거칠 수 있습니다.

정보 필드 설명

nickname 정보의 특징

  • 네이버에서 사용자가 직접 설정한 닉네임 정보입니다.
  • 사용자가 언제든지 닉네임을 변경할 수 있으므로 닉네임은 필요할 때마다 요청해야 합니다.
  • 닉네임 필드에 대해 개인정보 제공 동의가 되어 있으면 해당 사용자에게 다시 동의 절차를 진행하지 않습니다.
  • 경우에 따라 닉네임을 설정하지 않은 사용자가 있습니다. 이럴 경우 네이버 아이디를 마스킹 처리하여 제공합니다.

cellphone 정보의 특징

  • 네이버에서 사용자가 직접 설정한 휴대전화번호를 제공합니다.
  • 네이버 회원정보에 휴대전화번호가 저장되지 않은 사용자의 경우, 휴대전화번호를 설정하기 전까지 "result":"CANCEL"이 전달됩니다.

address 정보의 특징

  • N페이 통합배송지에 설정한 주소 중 5개 중에서 사용자가 선택한 하나의 주소가 전달됩니다.
  • address 정보 요청 시 모든 주소 목록이 제공되는 것이 아니라 요청 시점에 사용자가 선택한 주소 한 개가 전달되는 방식입니다.
  • 배달과 관련된 챗봇이라면 이전에 얻은 주소를 재사용하지 않고 매번 address 정보를 요청하여 현재 시점에 사용자가 원하는 주소를 가져가 사용해야 합니다.
  • 제공되는 address 속성명은 행정안전부 주소 서비스를 따릅니다.
  • 주소의 위치를 나타내는 좌표계는 위도경도로, 네이버 지도 API와 연동될 수 있는 좌표계입니다.
  • 주소는 신주소만 제공됩니다.

이벤트 명세

회원 정보 요청 Request 명세(챗봇 -> 네이버 톡톡)

POST /chatbot/v1/event HTTP/1.1
Host: gw.talk.naver.com
Content-Type: application/json;charset=UTF-8
Authorization: ct_wc8b1i_Pb1AXDQ0RZWuCccpzdNL

{
    "event": "profile", /* 프로필 이벤트 */
    "options": {
        "field": "nickname", /* 요청할 회원 정보 필드 nickname | cellphone | address */
        "agreements": [ "cellphone", "address" ] /* 제공 동의 필요 시 함께 동의받을 필드 */
    },
    "user": "al-2eGuGr5WQOnco1_V-FQ" /* 사용자 식별값 */
}

회원 정보 전달 Request 명세(네이버 톡톡 -> 챗봇)

POST / HTTP/1.1
Host: your.bot.co.kr
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
    "event": "profile", /* 프로필 이벤트 */
    "options": {
        /* nickname을 요청한 경우 */
        "nickname": "네이버톡톡",
        
        /* cellphone을 요청한 경우 */
        "cellphone": "01012341234",
        
        /* address를 요청한 경우 */
        "address": {
            "roadAddr": "경기도 성남시 분당구 불정로 6 (정자동)", /* 도로명 주소 */
            "detAddr": "톡톡부서", /* 상세 주소 */
            "zipNo": "13561", /* 우편번호 */
            "rnMgtSn": "411353180030", /* 도로명 코드 */
            "latitude": "37.3595316", /* 위도 */
            "longitude": "127.1052133" /* 경도 */
        },

        "result": "SUCCESS" /* 요청 결과 SUCCESS | DISAGREE | CANCEL */

    },
    "user": "al-2eGuGr5WQOnco1_V-FQ" /* 사용자 식별값 */
}