Kakao i Agent::Service Agent Interface::Speaker

페이지 이동경로

Speaker

Speaker 인터페이스는 음량 조절, 음소거, 음소거 해제 등 스피커 디바이스 제어와 관련한 Message를 제공합니다.

Speaker 인터페이스
Message 인터페이스 설명
Event VolumeChanged Speaker.SetVolume 또는 Speaker.AdjustVolume Instruction을 처리한 후, 스피커 볼륨이 조정 및 변경되었을 때 전송
MuteChanged Speaker.SetMute Instruction을 처리 후, 스피커의 음소거 상태가 변경 시 전송
Instruction SetVolume 절대적인 볼륨 조절이 필요한 경우마다 전송
AdjustVolume 상대적인 볼륨 조절이 필요한 경우마다 전송
SetMute 스피커의 음소거가 필요한 경우 전송
State VolumeState 현재 볼륨 설정과 관련된 일련의 상태

Event

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

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

VolumeChanged

Speaker.VolumeChanged는 Service Agent가 Speaker.SetVolume 또는 Speaker.AdjustVolume Instruction을 수신하여 처리한 후에 스피커 볼륨이 조정 및 변경되었음을 KVS에 전달하는 Event입니다.

Request Syntax

코드예제Speaker.VolumeChanged Request Syntax

{
	"event": {
		"header": {
			"type": "Speaker.VolumeChanged",
			"messageId": "{{STRING}}"
		},
		"body": {
			"volume": {{LONG}},
			"muted": {{BOOLEAN}}
		}
	}
}

Request Header

Speaker.VolumeChanged Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

Speaker.VolumeChanged Request Body
파라미터 타입 필수 여부 설명
volume Long 필수 절대 볼륨 레벨은 0(최소)에서 100(최대)까지 조정
muted Boolean 필수 스피커의 음소거 설정에 사용
true: 음소거 설정
false: 음소거 해제

MuteChanged

Speaker.MuteChanged는 Service Agent가 Speaker.SetMute Instruction을 수신하고 처리하여, 스피커의 음소거 상태가 변경되었음을 KVS로 전달하는 Event입니다.

Request Syntax

코드예제Speaker.MuteChanged Request Syntax

{
	"event": {
		"header": {
			"type": "Speaker.MuteChanged",
			"messageId": "{{STRING}}"
		},
		"body": {
			"volume": {{LONG}},
			"muted": {{BOOLEAN}}
		}
	}
}

Request Header

Speaker.MuteChanged Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

Speaker.MuteChanged Request Body
파라미터 타입 필수 여부 설명
volume Long 필수 절대 볼륨 레벨은 0(최소)에서 100(최대)까지 조정
muted Boolean 필수 스피커의 음소거 설정에 사용
true: 음소거 설정
false: 음소거 해제

Instruction

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

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

SetVolume

Speaker.SetVolume은 절대적인 볼륨 조절이 필요한 경우에 KVS가 Service Agent로 전송하는 Instruction입니다.

Request Syntax

코드예제Speaker.SetVolume Request Syntax
{
	"event": {
		"header": {
			"type": "Speaker.SetVolume",
			"messageId": "{{STRING}}"
		},
		"body": {
			"volume": {{LONG}},
		}
	}
}

Request Header

Speaker.SetVolume Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

Speaker.SetVolume Request Body
파라미터 타입 필수 여부 설명
volume Long 필수 절대 볼륨 레벨은 0(최소)에서 100(최대)까지 조정

AdjustVolume

Speaker.AdjustVolume은 상대적인 볼륨 조절이 필요한 경우에 KVS가 Service Agent로 전송하는 Instruction입니다. 현재 볼륨 설정을 기준으로 볼륨을 높이려면 양수(+), 줄이려면 음수(-)로 조정합니다.

Request Syntax

코드예제Speaker.AdjustVolume Request Syntax

{
	"instruction": {
		"header": {
			"type": "Speaker.AdjustVolume",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"volume": {{LONG}}
		}
	}
}

Request Header

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

Request Body

Speaker.AdjustVolume Request Body
파라미터 타입 필수 여부 설명
volume Long 필수 절대 볼륨 레벨은 0(최소)에서 100(최대)까지 조정

SetMute

Speaker.SetMute은 스피커의 음소거가 필요한 경우에 KVS가 Service Agent로 전송하는 Instruction입니다.

Request Syntax

코드예제Speaker.SetMute Request Syntax
{
	"instruction": {
		"header": {
			"type": "Speaker.SetMute",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"muted": {{BOOLEAN}}
		}
	}
}
}

Request Header

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

Request Body

Speaker.SetMute Request Body
파라미터 타입 필수 여부 설명
muted Boolean 필수 스피커의 음소거 설정에 사용
true: 음소거 설정
false: 음소거 해제

State

VolumeState

VolumeState는 현재 볼륨 설정과 관련된 일련의 상태를 제공합니다.

Request Syntax

코드예제Speaker.VolumeState Request Syntax
{
		"header": {
			"type": "Speaker.VolumeState",
		},
		"body": {
			"volume": {{LONG}},
			"muted": {{BOOLEAN}},
			"minVolume": "{{INTEGER}}",
			"maxVolume": "{{INTEGER}}",
			"preferredVolume": "{{INTEGER}}"
		}
}

Request Header

Speaker.VolumeState Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름

Request Body

Speaker.VolumeState Request Body
파라미터 타입 필수 여부 설명
volume Long 필수 상대적인 볼륨 조절을 위해, 현재 볼륨 설정과 관련해 볼륨을 높이거나 낮추는데 사용되는 양수 혹은 음수의 Long 값
- 범위: -100부터 +100까지
muted Boolean 필수 스피커의 음소거 설정에 사용
true: 음소거 설정
false: 음소거 해제
minVolume Integer 필수 볼륨 크기가 최소일 경우
maxVolume Integer 필수 볼륨 크기가 최대일 경우
preferredVolume Integer 필수 최적의 볼륨 상태
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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