View Template::API 레퍼런스::Data 요청 API

페이지 이동경로

시작하기

View Template 화면 구현을 완료한 후, 디스플레이 디바이스와 연동하는 Bot에서 데이터를 수신하기 위해서는 Bot의 블록에 Vendor.Kakaoi.Route.InstructionForwarded Event를 설정해야 합니다. Event 설정이 완료되면 해당 블록으로 Template.Render Instruction이 전달됩니다. 이벤트(Event)란 클라이언트에서 KVS(Kakao i Virtual agent Service)로 보내지는 일련의 명령들을 의미합니다.

데이터 수신/닫기 API
구분 설명
Bot에 Data 수신 요청 Template.Render Instruction을 처리하기 위해, Vendor.Kakaoi.Route.InstructionForwarded Event를 설정하여 Bot에 데이터 수신 요청
Bot에 Data 닫기 요청 Template.Close Instruction을 처리하기 위해, Vendor.Kakaoi.Route.InstructionForwarded Event를 설정하여 Bot에 데이터 닫기 요청

Bot에 Data 수신 요청

구현이 완료된 View Template 화면 디스플레이 디바이스와 연동하는 Bot에 데이터 수신을 요청할 경우, 다음의 프로퍼티 형식이 사용됩니다.

Request

Request Header

Request Header에 대한 상세를 다음과 같이 작성합니다.

Bot에 Data 수신 요청 시 Request Header
파라미터 타입 필수 여부 설명
X-Request-ID String 필수 요청에 대한 Unique ID
- 디버깅 시 필요

Request Parameters

Bot에 Data 수신 요청 시 Request Parameters
파라미터 타입 필수 여부 설명
Object 필수 블록의 Skill 수행을 위한 데이터
- 연결한 Skill 이름, Skill ID, 파라미터에 전달된 값 등을 포함
id String 필수 Skill ID
name String 필수 Skill 이름
params Object 필수 개발사에서 생성한 카카오 i 오픈빌더의 블록에 정의한 파라미터
- params.파라미터 명detailParams.파라미터 명.value 값과 동일
detailParams String 필수 params의 하위 요소와 1:1로 정의됨
contexts Array 필수 사용자의 현재 대화 상태에 유효하게 존재하는 컨텍스트 데이터
- Bot에서 output 컨텍스트 지정을 했을 경우 지정한 대화 횟수(lifespan), TTL(유효 시간)에 따라 만료가 결정되는데, 대화 진행 중에 만료되지 않은 컨텍스트 데이터가 전달됨
intent String 필수 블록의 고유 ID와 이름을 포함한 블록 데이터
Object 필수 Bot 관련 데이터
- Bot의 고유 ID와 이름 포함
id String 필수 Bot의 고유 ID
name String 필수 Bot 이름
Object 필수 사용자 요청 데이터
- Event 이름, View Template 데이터, 계정 데이터, 장치 데이터를 포함
Object 필수 View Template을 처리하기 위해 발생시킨 Event 정보
name String 필수 Event 이름
- Vendor.Kakaoi.Route.InstructionForwarded 값으로 고정됨
Object 필수 입력장치 사용자의 데이터
Object 필수 사용자 계정 데이터
appUserId String 필수 챗봇으로 연결 시에 발급된 계정 ID
appUserStatus String 필수 appUserId의 상태
- 정상일 경우, REGISTERED
vendorAccessToken String 필수 3rd Party에서 발행한 Access Token
- 3rd Party에서 OAuth 기반 Access Token을 지원하는 경우에만 존재함
Array 필수 연결된 장치 목록
appId String 필수 카카오에 등록된 App ID
type String 필수 장치 타입
Array 필수 연결된 장치들의 인증정보
label String 필수 장치의 사용자 설정 이름
uniqueId String 필수 파트너사에서 제공한 장치 고유 번호
Object 필수 입력장치로부터 전달받은 데이터 목록
Object 필수 입력장치 데이터
Object 필수 입력장치의 패키지 데이터
name String 필수 패키지명
code String 필수 패키지 Code
version String 필수 패키지 버전
os String 필수 입력장치의 운영체제 데이터
Object 필수 입력장치 Software Development Kit 데이터
version String 필수 입력장치 SDK의 버전
lang String 필수 입력장치의 Locale Code
device String 필수 입력장치의 모델명
Object 필수 Event 처리를 위한 추가 데이터
token String 필수 Vendor.Kakaoi.Route.InstructionForwarded Event를 처리하기 위한 Token
Object 필수 Vendor.Kakaoi.Route.InstructionForwarded Event를 처리하기 위한 Data
Array 필수 클라이언트(디바이스)에서 수행할 명령의 목록
type String 필수 Instruction 타입
- View Template의 경우, Template.Render 값으로 고정됨
Object 필수 Instruction 타입별로 약속된 JSON Object 값
type String 필수 View Template의 타입
token String 필수 각 Instruction을 식별하기 위한 고유 토큰 값
url String 필수 View Template URL
- URL의 Query-string에서 ttl, width, height 값을 파싱하여 재사용 가능
- URL이 아닌 Data 형식으로 들어가는 경우에는 View Template별 Code 예시 참고
안내
각 파라미터에 대한 상세한 설명은 Skill API 레퍼런스를 참고하시기 바랍니다.

Sample Code

코드예제Bot에 데이터 수신 요청

{
   "action":{
      "id":"5b62e71731d4df1dd784a0f1",
      "name":"ContentsTv.View",
      "params":{
         
      },
      "detailParams":{
         
      }
   },
   "contexts":[
      
   ],
   "intent":{
      "id":"5b62d00976c4df1dd7849ffa",
      "name":"templateRender"
   },
   "bot":{
      "id":"5b441bbb58d4df2ff6ebb090",
      "name":"카카오TV"
   },
   "userRequest":{
      "event":{
         "name":"Vendor.Kakaoi.Route.InstructionForwarded"
      },
      "user":{
         "properties":{
            "appUserId":"1376016924426698168",
            "appUserStatus":"REGISTERED",
            "vendorAccessToken":"Bearer xxxxxxxxxxxxxxxxxxxxxxxx",
            "linkedDevices":[
               {
                  "appId":290095,
                  "type":"KAKAO_TV",
                  "instances":[
                     {
                        "uniqueId":"LGTV9200abcd",
                        "label":"안방티비"
                     }
                  ]
               }
            ]
         }
      },
      "params":{
         "agent":{
            
         },
         "body":{
            "token":"{{STRING}}",
            "data":{
               "instructions":[
                  {
                     "type":"Template.Render",
                     "body":{
                        "type":"{{STRING}}",
                        "token":"{{STRING}}",
                        "url":"http://sandbox-vt.i.kakao.com/v/XX?token={{STRING}}&ttl=20000&width=300&height=350"
                     }
                  }
               ]
            }
         }
      }
   }
}

Bot에 Data 닫기 요청

Template.Close API를 통해 View Template 화면을 디스플레이 디바이스와 연동하는 Bot에 View Template 화면의 닫기 요청을 할 경우, 다음의 프로퍼티 형식이 사용됩니다.

Request

Request Parameters

Bot에 Data 닫기 요청 시 Request Parameters
파라미터 타입 필수 여부 설명
action Object 필수 블록의 스킬 수행을 위한 데이터
- 연결한 스킬명, 스킬ID, 파라미터에 전달된 값 등을 포함
contexts Array 필수 블록에서 컨텍스트 설정을 했을 경우, 해당 컨텍스트에 대한 데이터
intent String 필수 블록 데이터
- 블록의 고유 ID와 이름을 포함
Object 필수 Bot 관련 데이터
- Bot의 고유 ID와 이름 포함
id String 필수 Bot의 고유 ID
name String 필수 Bot 이름
Object 필수 사용자 요청 데이터
- Event 이름, View Template 데이터, 계정 데이터, 장치 데이터를 포함
Object 필수 View Template을 처리하기 위해 발생시킨 Event 정보
name String 필수 Event 이름
- Vendor.Kakaoi.Route.InstructionForwarded 값으로 고정됨
Object 필수 입력장치 사용자의 데이터
Object 필수 사용자 계정 데이터
appUserId String 필수 챗봇으로 연결 시 발급된 계정 ID
appUserStatus String 필수 appUserId의 상태
- 정상일 경우, REGISTERED
vendorAccessToken String 필수 3rd Party에서 발행한 Access Token
- 3rd Party에서 OAuth 기반 Access Token을 지원하는 경우에만 존재함
Array 필수 연결된 장치 목록
appId String 필수 Kakao에 등록된 App ID
type String 필수 장치 타입
Array 필수 연결된 장치들의 인증정보
label String 필수 장치의 사용자 설정 이름
uniqueId String 필수 파트너사에서 제공한 장치 고유 번호
Object 필수 입력장치로부터 전달받은 데이터 목록
Object 필수 입력장치 데이터
Object 필수 입력장치의 패키지 데이터
name String 필수 패키지명
code String 필수 패키지 Code
version String 필수 패키지 버전
os String 필수 입력장치의 운영체제 데이터
Object 필수 입력장치 Software Development Kit 데이터
version String 필수 입력장치 SDK의 버전
lang String 필수 입력장치의 Locale Code
device String 필수 입력장치의 모델명
Object 필수 Event 처리를 위한 추가 데이터
token String 필수 Vendor.Kakaoi.Route.InstructionForwarded Event를 처리하기 위한 Token
Object 필수 Vendor.Kakaoi.Route.InstructionForwarded Event를 처리하기 위한 Data
Array 필수 클라이언트(디바이스)에서 수행할 명령의 목록
type String 필수 Instruction 타입
- View Template의 경우, Template.Close 값으로 고정됨
Object 필수 Instruction 타입별로 약속된 JSON Object 값
token String 필수 각 Instruction을 식별하기 위한 고유 Token 값
안내
각 파라미터에 대한 상세한 설명은 Skill API 레퍼런스를 참고하시기 바랍니다.

Sample Code

코드예제Bot에 데이터 닫기 요청

{
   "action":{
      "id":"5b62e71731d4df1dd784a0f1",
      "name":"ContentsTv.View",
      "params":{
         
      },
      "detailParams":{
         
      }
   },
   "contexts":[
      
   ],
   "intent":{
      "id":"5b62d00976c4df1dd7849ffa",
      "name":"templateRender"
   },
   "bot":{
      "id":"5b441bbb58d4df2ff6ebb090",
      "name":"카카오TV"
   },
   "userRequest":{
      "event":{
         "name":"Vendor.Kakaoi.Route.InstructionForwarded"
      },
      "user":{
         "properties":{
            "appUserId":"1376016924426698168",
            "appUserStatus":"REGISTERED",
            "vendorAccessToken":"Bearer xxxxxxxxxxxxxxxxxxxxxxxx",
            "linkedDevices":[
               {
                  "appId":290095,
                  "type":"KAKAO_TV",
                  "instances":[
                     {
                        "uniqueId":"LGTV9200abcd",
                        "label":"안방티비"
                     }
                  ]
               }
            ]
         }
      },
      "params":{
         "agent":{
            
         },
         "body":{
            "token":"{{STRING}}",
            "data":{
               "instructions":[
                  {
                     "type":"Template.Close",
                     "body":{
                        "token":"{{STRING}}"
                     }
                  }
               ]
            }
         }
      }
   }
}

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.