Kakao i Agent::Service Agent Interface::Template

페이지 이동경로

Template

Template 인터페이스는 View Template의 노출, 종료, 리스트 항목 선택과 관련된 일련의 Message를 제공합니다.

Template 인터페이스
Message 인터페이스 설명
Event ElementSelected Template.Render Instruction의 items를 화면 터치로 선택할 수 있고, 그 중 하나가 선택되었을 때 전송
Rendered Service Agent가 Template을 그렸음을 전달
Closed Service Agent가 Template을 종료했음을 전달
Instruction Render Service Agent 화면에 Template을 노출하도록 지시
Close Service Agent 화면에 노출된 Template을 강제 종료하도록 지시
State RenderState 현재 유효한 TTL 내 모든 Template의 상태를 KVS에 전달

Event

Event Message의 호출 방식은 다음과 같습니다.

Event Message 호출 방식
메서드 요청 URL
POST /{{API version}}/events

ElementSelected

Template.ElementSelected는 Template.Render Instruction의 items들을 화면 터치로 선택할 수 있고, 그 중 하나가 선택되었을 때 Service Agent에서 KVS로 전송하는 Event입니다.

Request Syntax

코드예제Template.ElementSelected Request Syntax

{
	"event": {
		"header": {
			"type": "Template.ElementSelected",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"token": "{{STRING}}",
			"params": [
				{
					"key": "{{STRING}}",
					"value": "{{STRING}}"
				}
			]
		}
	}
}

Request Header

Template.ElementSelected Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Template.ElementSelected Request Body
파라미터 타입 필수 여부 설명
token String 필수 유니크 식별자
Array 선택 추가 파라미터
key String 필수 추가 파라미터의 키
value String 필수 추가 파라미터의 값

Rendered

Template.Rendered는 Service Agent가 Template을 그렸음을 KVS로 전달하는 Event입니다.

Request Syntax

코드예제Template.Rendered Request Syntax

{
	"event": {
		"header": {
			"type": "Template.Rendered",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"token": "{{STRING}}"
		}
	}
}

Request Header

Template.Rendered Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Template.Rendered Request Body
파라미터 타입 필수 여부 설명
token String 필수 유니크 식별자

Closed

Template.Closed는 Service Agent가 Template을 종료했을 때 KVS로 전송하는 Event입니다.

Request Syntax

코드예제Template.Closed Request Syntax

{
	"event": {
		"header": {
			"type": "Template.Closed",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"token": "{{STRING}}"
		}
	}
}

Request Header

Template.Closed Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Template.Closed Request Body
파라미터 타입 필수 여부 설명
token String 필수 유니크 식별자

Instruction

Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

Instruction Message 호출 방식
메서드 요청 URL
GET /{{API version}}/instructions

Render

Template.Render는 KVS가 Service Agent 화면에 Template을 노출하도록 지시하는 Instruction입니다.

Request Syntax

코드예제Template.Render Request Syntax
{
	"instruction": {
		"header": {
			"type": "Template.Render",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"type": "{{STRING}}",
			"token": "{{STRING}}",
			"data": "{{OBJECT}}",
			"ttl": {{LONG}},
			"style": "{{STRING}}",
		}
	}
}

Request Header

Template.Render Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Template.RenderBody Request Body
파라미터 타입 필수 여부 설명
type String 필수 View Template 타입
token String 필수 유니크 식별자
data Object 필수 title, subtitle, button 등의 템플릿 스타일이나 동작을 포함한 구성 요소를 정의
- View Template 참고
ttl Long 선택 View Template이 화면에 그려지고 유지되어야 하는 시간
style String 선택 대화 완료 답변과 대화 중 입력에 사용되는 View Template의 Draw 스타일
BASIC(기본값): 대화 완료 상태
INTERIM: 사용자 입력을 기대하는 상태

Sample Code

코드예제Template.Render 날씨 Sample Code

{
	"instruction": {
		"header": {
			"type": "Template.Render",
			"messageId": "123456",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"type": "weatherDaily",
			"token": "{{STRING}}",
			"data": {
				"background": {
					"colors": [
						"#2DA5E1",
						"#1E6EB4"
					],
					"imageUrls": [
					]
				},
				"items": [
					{
						"dayOfWeek": "수",
						"description": "맑음",
						"maxTemperature": "26",
						"minTemperature": "13",
						"pictogramUrl": "{URL}",
						"temperature": "18"
					}
				],
				"title": "날씨",
				"subTitle": "서울 05.17 오전 05:00 기준"
			},
			"entity": {
				"": null,
				"": "20170517",
				"": "20170517000000",
				"": null,
				"": "서울",
				"": "서울 중구 태평로2가",
				"": "서울",
				"": "126.97786979309681, 37.564076020498796",
				"": "오늘",
				"": "20170517",
				"": "20170517235959",
			}
		}
	}
}

Close

Template.Close는 KVS가 Service Agent 화면에 노출된 Template을 강제 종료하도록 지시하는 Instruction입니다.

Request Syntax

코드예제Template.Close Request Syntax

{
	"instruction": {
		"header": {
			"type": "Template.Close",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"token": "{{STRING}}"
		}
	}
}

Request Header

Template.Close Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Template.Close Request Body
파라미터 타입 필수 여부 설명
token String 필수 유니크 식별자

State

RenderState

Template.RenderState는 현재 유효한 TTL 내의 모든 Template 상태를 표시하는 State입니다.

Request Syntax

코드예제Template.RenderState Request Syntax
{
	"header": {
			"type": "Template.RenderState",
		},
		"body": {
			"allTemplates": [
				 {
						"token": {{LONG}},
						"type": {{LONG}},
						"style": "{{STRING}}",
						"createdAt": {{LONG}},
						"state": "ready|active"
				 }
			],
			"activeTemplates": [
				 {
						"token": "{{STRING}}",
						"type": "{{STRING}}",
						"style": "{{STRING}}",
						"stateUpdatedAt": {{LONG}},
						"createdAt": {{LONG}},
						"expiredAt": {{LONG}}
				 }
			],
		}
}

Request Body

Template.RenderState Request Body
파라미터 타입 필수 여부 설명
Array 선택 모든 Template 정보 목록
token String 필수 Template 토큰
type String 필수 Template 타입
style String 필수 Template 스타일
INTERIM: 슬롯필링 또는 컨펌 등의 재질의를 표시
BASIC: 최종 결과 답변만 표시
createdAt Long 선택 Template 생성 시점
state 타입 선택 Template 상태
ready: 대기
active : 표시
Array 선택 표시된 Template의 정보
String 필수 Template 토큰
type String 필수 Template 타입
style String 필수 Template 스타일
INTERIM: 슬롯필링 또는 컨펌 등의 재질의를 표시
BASIC: 최종 결과 답변만 표시
createdAt Long 선택 Template 생성 시점
styleUpdatedAt Long 선택 Template 상태 갱신 시점
expiredAt Long 선택 Template 만료 시점
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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