Recognizer

Recognizer 인터페이스는 음성 및 텍스트 발화 인식과 관련된 일련의 Message를 처리합니다.

표Recognizer 인터페이스

Message	인터페이스	설명
Event	Speech	Service Agent에서 발생한 사용자 발화를 KVS에 전달
	Text	음성 발화가 아닌 텍스트 발화 입력 시에 사용 - Recognizer.Speech Event와 기본적인 동작은 동일함
	Canceled	Service Agent에서 발화 중 취소가 발생하여 해당 다이얼로그에 대해 모든 세션이 종료되었음을 KVS에 전달
Instruction	StopCapture	KVS가 사용자의 의도를 파악했거나 발화가 종료 시, 음성 캡처를 중지하도록 지시
	InformRecognized	KVS가 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달
	ExpectSpeech	KVS가 사용자에게 추가적인 발화를 원할 때, 마이크를 열고 사용자의 발화를 기다리도록 지시
	RequestText	Service Agent에 Text Event를 보내도록 지시
State	RecognizerState	음성 웨이크업을 지원하는 기기에 설정된 Wake-up Word를 KVS에 전달

Event

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

표Event Message 호출 방식

메서드	요청 URL
POST	`/{API version}/events`

Speech

Recognizer.Speech는 Service Agent에서 발생한 사용자 발화를 KVS로 전달하는 Event이며, Multipart Message로 통신합니다. Multipart의 <The First Part>에는 JSON 형식의 객체가 전달되며, <The Second Part>에는 Service Agent와 KVS 사이에 전송되는 오디오 데이터가 스트리밍 방식으로 배치됩니다. stream에는 320 bytes chunk 단위로 10ms의 캡처된 오디오 파일이 첨부됩니다.

표Multipart Message

구분	설명
The First Part	JSON 형식의 객체
The Second Part	마이크에서 캡처된 바이너리 오디오 파일

Request Syntax

코드예제Recognizer.Speech Request Syntax_The First Part

JSON

Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
        "state": [, , ,],
        "event": {
                "header": {
                        "type": "Recognizer.Speech",
                        "messageId": "{STRING}",
                        "dialogRequestId": "{STRING}"
                },
                "body": {
                        "profile": "{STRING}",
                        "format": "{STRING}",
                        "inflow": "{STRING}",
                        "activator": {
                                "type": "{STRING}",
                                "botId": "{STRING}",
                                "body": {
                                        "wakeWordDetection": {
                                                "reliableThreshold": {FLOAT},
                                                "reliability": {FLOAT},
                                                "sensitivity": {FLOAT}
                                        }
                                }
                        }
                }
        }
}

코드예제Recognizer.Speech Request Syntax_The Second Part (Binary Audio 첨부)

JSON

Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream

{BINARY AUDIO ATTACHMENT}

Request Header

표Recognizer.Speech Request Header

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

Request Body

표Recognizer.Speech Request Body

파라미터	타입	필수 여부	설명
profile	String	`필수`	다양한 거리에서 사용자 음성을 최적화하여 식별하는 ASR Profile 유형으로, 마이크와 사용자 음성의 거리를 나타냄
			`NEAR_TALK`(기본값): 보통 거리
			`CLOSE_FIELD`: 매우 가까운 거리
			`FAR_FIELD`: 매우 먼 거리
inflow	String	`필수`	발화 유입을 식별
			`REMOTE_MIC`: 스피커 본체와 떨어져있는 마이크에서 음성 입력
			`SPEAKER`:스피커 본체 마이크에서 음성 입력
format	String	`필수`	캡처한 오디오의 형식을 식별 ex) `RAWPCM/16/16000/1/_/_`
activator	Object	`선택`	발화가 개시된 이유를 명시 Service Agent: 다음 Recognizer.Speech에 이 객체를 그대로 다시 전달 - Recognizer.ExpectSpeech에 의해 수동적으로 발화가 개시된 경우, 수신된 Recognizer.ExpectSpeech의 `activator` 객체를 그대로 재전송
type	String	`필수`	발화가 개시된 이유를 명시
			<능동적으로 발화가 개시된 경우>
			`WAKEWORD`: Wake-up Word로 마이크를 열었을 때 Service Agent에서 세팅
			`BUTTON_TAP`: 버튼으로 마이크를 열었을 때 Service Agent에서 세팅
			<수동적으로 발화가 개시된 경우> Recognizer.ExpectSpeech Instruction에 다음의 주어진 값이 설정
			`EXPECT_REPLY`: 응답을 기대하는 경우
			`EXPECT_CONTINUE`: 대화가 이어질 수 있도록 마이크를 열어줌
			`EXPECT_WAKEUP`: Wake-up Word를 연속으로 발화했을 경우 다시 마이크를 열어줌
			`ASYNC_REPLY`: 푸시를 통한 비동기 답변
			`RECORDING`: 보이스프로필 등록 시 사용
botId	String	`선택`	ExpectSpeech를 발생시킨 Bot의 ID 전달 - `activator.type`이 `EXPECT_REPLY` 또는 `EXPECT_CONTINUE`
token	String	`선택`	현재 대화의 스트림을 나타내는 불투명한 토큰
	Object	`필수`	Wake-up Word에 대한 정보
	Object	`선택`	Wake-up Word로 웨이크업이 될 때 인식 신뢰도 및 민감도 정보
reliableThreshold	Float	`필수`	신뢰 여부(`reliable`)의 문턱값: `reliability` ≥ `reliableThreshold`
reliability	Float	`필수`	인식 신뢰도
sensitivity	Float	`필수`	Wake-up Word 검증 시 활용할 민감도의 상대값 ex) 0: 보통, 100: 민감, -100: 둔감

Text

Recognizer.Text는 입력 방식이 음성이 아닌 텍스트 발화일 때, Service Agent가 해당 텍스트 발화를 KVS에 전송할 경우에 사용하는 Event입니다. 기본 동작은 Recognizer.Speech Event와 동일합니다.

Request Syntax

코드예제Recognizer.Text Request Syntax

JSON

{
  "header": {
    "type": "Recognizer.Text",
    "messageId": "{STRING}",
    "dialogRequestId": "{STRING}"
  },
  "body": {
    "token": "{STRING}",
    "utterance": "{STRING}",
    "source": "{STRING}",
    "triggerType": "{STRING}"
  }
}

Request Header

표Recognizer.Text Request Header

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

Request Body

표Recognizer.Text Request Body

파라미터	타입	필수 여부	설명
token	String	`선택`	유니크 식별자
utterance	String	`필수`	텍스트 발화
source	String	`선택`	텍스트 발화가 발생한 입력 소스 - Recognizer.RequestText Event 생성자가 임의의 Readable String을 지정하므로 생성자 또는 대리자만 해석 가능
triggerType	String	`선택`	텍스트 발화가 발생한 타입
			`WORKFLOW`: 내 명령어 또는 예약 실행에서 사용되는 Workflow Event로 발생한 Recognizer.RequestText에 지정
			`PLAYBACK_CONTROL`: PlaybackController 인터페이스의 Event로 발생한 Recognizer.RequestText에 지정
			`QUICK_REPLY`: View Template의 `quickReply` action에 포함된 Recognizer.RequestText에 지정
			`REDIRECT`: 분류된 Bot에서 다른 Bot의 발화를 실행할 때 지정
			`UTTERANCE_INJECTION`: 다른 마이크에서 입력된 음성발화의 인식결과를 전달할 때 지정
			`CUSTOM_BUTTON`: 기기의 일반적인 버튼으로 인하여 발생한 Recognizer.RequestText에 지정

Canceled

Recognizer.Canceled는 Service Agent에서 발화 중 취소가 발생하여 해당 다이얼로그에 대해 슬롯필링 등의 모든 세션이 종료되었음을 KVS에 전달하는 Event입니다.

Recognizer.ExpectSpeech Instruction을 수신하기 전에 Recognizer.Canceled Event를 전송하면, 서버와의 동기화 문제로 취소(Canceled)된 dialogRequestId를 포함하는 Recognizer.ExpectSpeech Instruction을 다시 수신할 수 있습니다.

Service Agent는 발화 중 취소하려는 dialogRequestId에 해당하는 수신된 모든 Instruction이 동작하지 않도록 처리하고, Recognizer.Canceled Event로 전송한 dialogRequestId를 일정 기간 저장하여 서버에서 비동기로 수신되는 발화 중 취소하려는 dialogRequestId에 해당하는 Instruction을 무시해야 합니다.

Request Syntax

코드예제Recognizer.Canceled Request Syntax

JSON

{
  "header": {
    "type": "Recognizer.Canceled",
    "messageId": "{STRING}",
    "dialogRequestId": "{STRING}"
  },
  "body": {}
}

Request Header

표Recognizer.Canceled Request Header

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

Instruction

Event Message의 응답으로 Instruction Message를 수신할 수도 있습니다. Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

표Instruction Message 호출 방식

메서드	요청 URL
GET	`/{API version}/instructions`

StopCapture

Recognizer.StopCapture는 KVS가 사용자의 의도를 파악했거나 또는 사용자가 발화를 종료했을 때, 사용자 음성 캡처를 중지하도록 Service Agent로 지시하는 Instruction입니다. Service Agent가 Recognizer.StopCapture Instruction을 전송받으면, 즉시 마이크를 닫고 사용자 발화를 더 이상 듣지 않습니다.

Request Syntax

코드예제Recognizer.StopCapture Request Syntax

JSON

{
  "header": {
    "type": "Recognizer.StopCapture",
    "messageId": "{STRING}",
    "dialogRequestId": "{STRING}"
  },
  "body": {}
}

Request Header

표Recognizer.StopCapture Request Header

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

InformRecognized

Recognizer.InformRecognized는 KVS가 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달하는 Instruction입니다.

Request Syntax

코드예제Recognizer.InformRecognized Request Syntax

JSON

{
  "header": {
    "type": "Recognizer.InformRecognized",
    "messageId": "{STRING}",
    "dialogRequestId": "{STRING}"
  },
  "body": {
    "type": "{STRING}",
    "text": "{STRING}"
  }
}

Request Header

표Recognizer.InformRecognized Request Header

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

Request Body

표Recognizer.InformRecognized Request Body

파라미터	타입	필수 여부	설명
type	String	`필수`	음성 인식 결과 유형
			`WAKEUP`: 웨이크업
			`BPD`(Begin Point Detection): 사용자가 발화 시작
			`EPD`(End Point Detection): 사용자 발화 종료
			`PARTIAL`:음성 인식 진행 중
			`FINAL`: 음성 인식된 최종 스트림
text	String	`선택`	음성 인식 결과 텍스트 - 최대 4,096자

Sample Code

코드예제Recognizer.InformRecognized Sample Code

JSON

{
  "header": {
    "type": "Recognizer.InformRecognized",
    "messageId": "123456",
    "dialogRequestId": "dialogRequestId-123"
  },
  "body": {
    "type": "PARTIAL",
    "text": "아이유"
  }
}

ExpectSpeech

Recognizer.ExpectSpeech는 KVS가 사용자로부터 추가적인 발화를 기대할 때, 마이크를 열고 사용자의 발화가 시작될 수 있도록 Service Agent에 지시하는 Instruction입니다.

Request Syntax

코드예제Recognizer.ExpectSpeech Request Syntax

JSON

{
        "header": {
                "type": "Recognizer.ExpectSpeech",
                "messageId": "{STRING}",
                "dialogRequestId": "{STRING}"
        },
        "body": {
                "activator": {
                        "type": "{STRING}",
                        "botId": "{STRING}"
                },
                "waitTime": {LONG},
                "inflow": "{STRING}"
        }
}

Request Header

표Recognizer.ExpectSpeech Request Header

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

Request Body

표Recognizer.ExpectSpeech Request Body

파라미터	타입	필수 여부	설명
	Object	`필수`	발화가 개시된 이유를 명시하며, Service Agent는 다음 Recognizer.Speech에 이 객체를 그대로 다시 전달
type	String	`필수`	발화가 개시된 이유를 명시
			<능동적으로 발화가 개시된 경우>
			`WAKEWORD`: Wake-up Word로 마이크를 열었을 때 Service Agent에서 세팅
			`BUTTON_TAP`: 버튼으로 마이크를 열었을 때 Service Agent에서 세팅
			<수동적으로 발화가 개시된 경우> Recognizer.ExpectSpeech Instruction에 다음의 주어진 값이 설정됨
			`EXPECT_REPLY`: 응답을 기대하는 경우 예시 - 사용자: 환율 알려줘 - 답변(`EXPECT_REPLY`): 알고 싶은 환율의 국가나 통화명을 알려주세요 - 사용자: 달러 - 답변: 현재 미국 환율은 xxxx원이에요
			`EXPECT_CONTINUE`: 대화가 이어질 수 있도록 마이크를 열어줌 예시 - 사용자: 안녕 - 답변(`EXPECT_CONTINUE`): 안녕 - 사용자: 만나서 반가워 - 답변(`EXPECT_CONTINUE`): 그럼 저랑 더 얘기해봐요 - 사용자: 너 누구야 - 답변(`EXPECT_CONTINUE`): 저는 카카오라고 해요. 친하게 지내요!
			`EXPECT_WAKEUP`: Wake-up Word 연속 발화 시 마이크를 열어줌 예시 - 사용자: 헤이카카오 - 답변(“띠링” 소리 후 마이크 열림) - 사용자: 헤이카카오 - 답변(“띠링” 소리 후 마이크 열림)
			`ASYNC_REPLY`: 푸시를 통한 비동기 답변 예시 - 사용자: 카톡 읽어줘 - 답변(`EXPECT_REPLY`): 아이유에게 온 카톡 읽어줄까요? - 사용자: 그래 - 답변(`ASYNC_REPLY`): 카톡 다 읽었어요. 다음 수지 카톡 읽어줄까요?
			`RECORDING`: 보이스프로필 등록 시 사용하며, 문장에 포함된 Wake-up Word를 포함하여 녹음된 전체 문장을 목소리 학습에 활용 예시 - 사용자: 헤이카카오앱에서 스피커를 지정하고 목소리 등록 시작 - 답변(`RECORDING`): 목소리 등록을 시작할게요. “띠링” 소리 후 헤이카카오라고 말해주세요 - 사용자: 헤이카카오
botId	String	`선택`	ExpectSpeech를 발생시킨 Bot의 ID 전달 - `activator.type`이 `EXPECT_REPLY` 또는 `EXPECT_CONTINUE`
token	String	`선택`	현재 대화의 스트림을 나타내는 불투명한 토큰
waitTime	Long	`필수`	Service Agent가 마이크가 열린 뒤, 사용자 발화를 얼마나 오래 기다릴지 정함 - 정의된 시간 내 발화가 시작되지 않으면(BPD를 받지 못하면) 마이크를 닫음 - 단위: ms(miliseconds)
inflow	String	`선택`	마이크를 열 유입 대상을 지정

RequestText

Recognizer.RequestText는 KVS가 Service Agent로 Text Event를 보내도록 요청하는 Instruction입니다.

주의
Recognizer.RequestText 인터페이스는 1.1 버전부터 지원하고 있습니다.

지원하는 버전에 대한 자세한 설명은 Capability를 참고하시기 바랍니다.

Request Syntax

코드예제Recognizer.RequestText Request Syntax

JSON

{
  "instruction": {
    "header": {
      "type": "Recognizer.RequestText",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {
      "token": "{STRING}",
      "utterance": "{STRING}",
      "priority": "{STRING}",
      "source": "{STRING}",
      "triggerType": "{STRING}"
    }
  }
}

Request Header

표Recognizer.RequestText Request Header

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

Request Body

표Recognizer.RequestText Request Body

파라미터	타입	필수 여부	설명
token	String	`필수`	유니크 식별자
utterance	String	`필수`	Recognizer.Text Event의 `body`에 구성될 발화 내용
priority	String	`선택`	Recognizer.RequestText를 실행하는 우선순위 - Highest(기본값): 다른 작업보다 최우선으로 실행되며, 현재 Recognizer.Speak가 진행 중인 경우에도 바로 Event를 전송함
source	String	`선택`	Text 발화가 발생한 입력 소스 - Recognizer.RequestText 생성자가 임의의 Readable String을 지정할 수 있으며, 생성자 또는 대리자만 해석 가능 - Event 발생 시 `body`에 동일 값을 전송해야 함
triggerType	String	`선택`	Text 발화가 발생한 타입으로 정해진 값 중 선택 - Event 발생 시 `body`에 동일 값을 전송해야 함

State

State Message는 모든 Event Message를 전송하는 요청(Request)에 항상 포함되어야 합니다.

RecognizerState

Recognizer.RecognizerState는 KVS에서 디바이스에 설정된 웨이크업을 확인하고, 불필요한 웨이크업을 처리하는데 사용하는 State로, 음성 웨이크업을 지원하는 디바이스에 설정되어 있는 Wake-up Word(wuw)를 선택적으로 전달합니다.

Request Syntax

코드예제Recognizer.RecognizerState Request Syntax

JSON

{
  "header": {
    "type": "Recognizer.RecognizerState"
  },
  "body": {
    "wuw": "헤이 카카오"
  }
}

Request Header

표Recognizer.RecognizerState Request Header

파라미터	타입	필수 여부	설명
type	String	`필수`	해당 인터페이스 이름

Request Body

표Recognizer.RecognizerState Request Body

파라미터	타입	필수 여부	설명
wuw	String	`필수`	현재 디바이스에 설정된 Wake-up Word - 가능한 값: "헤이 카카오"

kakaoIdocumentation

Kakao i Agent::Service Agent Interface::Recognizer

페이지 이동경로

Recognizer

Event

Speech

Request Syntax

Request Header

Request Body

Text

Request Syntax

Request Header

Request Body

Canceled

Request Syntax

Request Header

Instruction

StopCapture

Request Syntax

Request Header

InformRecognized

Request Syntax

Request Header

Request Body

Sample Code

ExpectSpeech

Request Syntax

Request Header

Request Body

RequestText

Request Syntax

Request Header

Request Body

State

RecognizerState

Request Syntax

Request Header

Request Body