엔티티에서 파라미터 추출

엔티티 파라미터 추출은 입력된 사용자 발화에서 엔티티 값을 추출해 Skill에 전달하는 기능입니다. 이 기능은 Bot 시스템에 미리 등록된 엔티티를 예상되는 사용자 발화에 태깅하고 이를 파라미터에 추가하여 사용할 수 있습니다.

엔티티(Entity)란 Bot이 사용자의 의도에 맞는 동작을 수행에 필요한 주요 데이터로 시스템 엔티티와 나의 엔티티로 구분되며, 각 엔티티는 대표 엔트리(Entry)와 대표 엔트리의 동의어로 구성됩니다. 자세한 설명은 [챗봇 관리자센터] 엔티티와 [챗봇 관리자센터] 발화 패턴 만들기를 참고하시기 바랍니다.

표엔티티 구분

종류	설명	구성
시스템 엔티티	카카오 i 플랫폼에서 기본적으로 제공하는 엔티티 - 날짜, 시간, 숫자 등	대표 엔트리와 대표 엔트리 동의어
나의 엔티티	사용자가 직접 등록하여 사용하는 엔티티	대표 엔트리와 대표 엔트리 동의어

엔티티 등록

엔티티 파라미터 추출 기능을 사용하기 위해 먼저 엔티티를 등록합니다.

[Builder 사이트] 챗봇 관리자센터에서 [+ 봇 만들기]를 클릭합니다.

그림챗봇 관리자센터
내 챗봇 메뉴에서 원하는 봇을 선택합니다.

그림내 챗봇
시나리오 탭에서 [엔티티] 버튼을 클릭합니다.

그림엔티티 관리
나의 엔티티 > 나의 엔티티 관리 메뉴에서 [+] 버튼을 클릭합니다.

그림엔티티 추가
엔티티 이름과 대표 엔트리를 입력합니다.

그림대표 엔트리 입력
엔티티 목록에서 각 대표 엔트리의 동의어를 입력하고, [저장] 버튼을 클릭합니다.

그림 대표 엔트리 동의어 입력

파라미터 설정

엔티티 등록 후, 다음의 순서에 따라 발화 패턴에 태깅하고 파라미터로 설정합니다.

사용자 발화에 문장을 입력하고, 엔티티로 태깅하고 싶은 텍스트를 드래그합니다.
엔티티 선택 팝업창에서 위에서 등록한 엔티티를 선택합니다.

그림패턴 발화에 엔티티 태깅

그림엔티티 태깅 예시
일반 파라미터 값으로 엔티티를 정의하고, 사용자 음성명령에서 추출한 엔티티는 대표 엔트리로 변환하여 Skill에 전달합니다.
- 필수 파라미터 설정에 체크 시, 해당 엔티티가 입력되지 않으면 Bot에서 자동으로 되묻기 질문을 제공합니다.
그림태깅한 엔티티를 Skill 파라미터로 설정

Sample Code

다음은 챗봇 관리자센터에서 입력한 파라미터를 Skill 서버로 전달하는 Request 예시입니다.

코드예제Skill 서버 Request Sample Code

JSON

{
        "action": {
                "id": "ACTION_ID_1234",
                "name": "kakaoi.sample",
                "params": {
                        "answerChoice": "a"
                },
                "detailParams": {
                        "answerChoice": {
                                "origin": "에이",
                                "value": "a",
                                "groupName": ""
                        }
                }
        },
        "intent": {
                "id": "INTENT_ID_1234",
                "name": "kakaoi.intent"
        },
        "bot": {
                "id": "BOT_ID_1234!",
                "name": "카카오토익"
        },
        "userRequest": {
                "utterance": "에이입니다",
                "lang": "kr"
        }
}

폴백 블록 설정

폴백 블록 설정은 Bot이 처리할 수 없는 음성 명령에 대해 답변을 제공할 때 사용하는 기능입니다. 폴백 블록은 Bot을 생성하면 기본적으로 Bot에 포함되어 있는 블록으로 다음의 경우에 실행됩니다.

해당 Bot으로 분류되어 발화가 입력되었으나 입력된 문장에 대응하는 블록이 없을 경우(최초에 어떠한 블록도 생성하지 않은 경우 포함)
입력된 문장에 대응하는 블록은 존재하지만, 해당 블록에 Input 컨텍스트(Context)가 설정되어 있고 현재 Bot의 대화에 유효한 해당 컨텍스트가 존재하지 않을 경우
현재 대화에 컨텍스트가 설정되어 있지만 Input 컨텍스트가 설정된 블록 중 사용자가 입력한 문장에 대응하는 블록이 없거나 마이크가 열려 있는 동안 답변을 하지 않은 경우

폴백 블록도 일반 블록과 동일하게 고정 답변을 등록해 놓으면, 등록된 답변 중 한 개가 사용자 음성명령에 대한 답변으로 제공됩니다.
보다 적절한 폴백 답변을 제공하기 위해서는 폴백 블록에 Skill을 연결하고 스피커 식별값, Bot의 컨텍스트 정보, 입력된 문장에서 추출된 파라미터 등을 Skill 서버에 전달합니다.

시나리오 예시

질문 블록(A)에서 봇이 사용자에게 답변을 받기 위한 질문을 요청하고 마이크를 연 후, 답변 블록(B)에 등록되지 않은 발화 패턴으로 사용자가 답변했을 경우의 예시는 다음과 같습니다.

스피커 » 정답을 골라주세요.
사용자 » …
스피커 » (폴백 블록) 잘 못 들었어요. a, b, c 중에 정답을 골라주세요.
사용자 » a 일 것 같기도 하고 아닌 것 같기도 하고…
스피커 » 정답입니다.

안내
폴백 블록도 일반 블록과 동일하게 발화 패턴에서 엔티티를 추출할 수 있습니다.

이전 블록에서 “dialog”: “reply”로 사용자 발화를 기대해 마이크를 열었지만 사용자 발화가 입력되지 않으면 폴백 Request에 “utterance”: “EMPTY”가 전달됩니다.

폴백 블록을 설정하는 방법은 다음과 같습니다.

[Builder 사이트] 챗봇 관리자센터에서 [+ 봇 만들기]를 클릭합니다.

그림챗봇 관리자센터
내 챗봇 메뉴에서 원하는 봇을 선택합니다.

그림내 챗봇
시나리오 탭의 기본 시나리오 > 폴백 블록을 선택합니다.

그림폴백 블록
일반 블록과 동일하게 고정 답변을 입력하거나 Skill을 연결합니다.

Sample Code

코드예제폴백 블록 설정 Sample Code

JSON

{
        "_code": 200,
        "answer": {
                "status": "normal",
                "sentence": "잘 못 들었어요. a, b, c 중에 정답을 골라주세요.",
                "dialog": "reply"
        }
}

되묻기 질문

되묻기 질문이란 Bot이 답변을 구현하기 위해 사용자 발화에 필수 정보가 입력되지 않은 경우, 해당 정보가 입력될 때까지 Bot이 되묻기 질문을 수행하는 기능입니다. 이 기능을 사용하기 위해서는 답변 구현에 필수적인 정보를 필수 파라미터로 설정한 후, 사용자가 해당 정보를 입력하도록 유도합니다. 이때 필수 파라미터를 개별로 설정하거나 그룹으로 설정할 수 있습니다.

그룹 파라미터는 두 개 이상의 파라미터로 구성되며, 그룹에 속한 파라미터 중 최소 한 개의 파라미터가 입력되면 되묻기 질문 없이 Skill이 호출됩니다. 그룹 내 하나의 정보만 입력되어도 답변을 구현하는 데 문제가 없을 때 주로 사용됩니다. 그룹 파라미터가 구성되면 해당 그룹은 자동으로 필수 파라미터가 됩니다.

시나리오 예시

사용자 발화 패턴에 “토익 파트 시작해 줘", “토익 파트 3 시작해 줘" 등을 등록하고, 숫자 엔티티를 필수 파라미터로 지정한 경우의 시나리오는 다음과 같습니다. 자세한 설명은 [챗봇 관리자센터] 슬롯필링과 [챗봇 관리자센터] 되묻기 질문 등록하기를 참고하시기 바랍니다.

표시나리오 예시

대화 입력	사용자 발화	스피커 답변	동작
1차	“토익 파트 시작해 줘”	“파트 번호를 말해주세요.”	필수 파라미터가 채워질 때까지 설정한 되묻기 질문 응답이 자동으로 나감 - 이 경우 블록에 연결한 Skill이 호출되지 않음
2차	“블라블라”	“파트 번호를 말해주세요.”	필수 파라미터가 채워질 때까지 설정한 되묻기 질문 응답이 자동으로 나감 - 이 경우 블록에 연결한 Skill이 호출되지 않음
3차(A)	“파트 3”	“토익 파트 3을 시작합니다.”	필수 파라미터가 채워지면 연결된 Skill이 호출되고, 해당 파라미터가 전달됨
3차(B)	“블라블라”	“응답 횟수가 초과되었습니다.”	설정된 되묻기 허용 횟수만큼 되묻기를 시도했지만 필수 파라미터가 채워지지 않은 경우, 초과 시 안내 메시지가 답변으로 나가고 대화가 종료됨

필수 파라미터 개별 설정

되묻기 질문을 사용하기 위해 필수 파라미터를 개별 설정하는 방법은 다음과 같습니다.

[Builder 사이트] 챗봇 관리자센터에서 [+ 봇 만들기]를 클릭합니다.

그림챗봇 관리자센터
내 챗봇 메뉴에서 원하는 봇을 선택합니다.

그림내 챗봇
시나리오 탭에서 해당하는 블록을 선택하고, 파라미터 설정 섹션의 필수 파라미터에서 [+] 버튼을 클릭합니다.

그림필수 파라미터 추가
파라미터 만들기 팝업창에서 파라미터명과 엔티티를 입력합니다.
- 필수 파라미터 설정에 체크 시, 해당 엔티티가 입력되지 않으면 Bot에서 자동으로 되묻기 질문을 제공합니다.
그림파라미터 정보 입력
- 파라미터 설정 섹션의 일반 파라미터에 커서를 두고 [→] 버튼을 클릭하면 일반 파라미터를 필수 파라미터로 변경할 수 있습니다.
그림파라미터 필수 여부 설정
필수 파라미터에서 [되묻기 질문] 버튼을 클릭합니다.

그림되묻기 질문

되묻기 질문 팝업창에서 되묻기 질문 응답을 입력하고 바로연결 응답 및 되묻기 허용 횟수를 설정합니다.

그림되묻기 질문 설정

표되묻기 질문 창

구분	설명
되묻기 질문 응답	되묻기 질문을 정의하며, 총 세 개까지 정의 가능 - 되묻기 질문은 사용자에게 출력되는 허용 횟수 안에서 무작위 순으로 출력됨
바로연결 응답	사용자가 되묻기 상황에서 입력할 파라미터 값을 클릭해 보낼 수 있도록 버튼을 설정
되묻기 허용 횟수 설정	되묻기 질문이 실행될 횟수를 선택 - 최대 허용 횟수가 끝나서 결국 원하는 파라미터 값을 획득하지 못했을 때 Bot이 사용자에게 출력할 안내 메시지를 정의함

그룹 파라미터 설정

필수 파라미터를 개별로 설정하지 않고, 그룹 파라미터를 설정하는 방법은 다음과 같습니다.

그룹 파라미터는 두 개 이상의 파라미터로 구성되며, 그룹에 속한 파라미터 중 최소 한 개의 파라미터가 입력되면 되묻기 질문 없이 Skill이 호출됩니다. 그룹 내 하나의 정보만 입력되어도 답변을 구현하는 데 문제가 없을 때 주로 사용됩니다.

필수 파라미터 섹션 오른쪽 위의 [폴더] 아이콘을 클릭합니다.

그림파라미터 그룹 설정
그룹 생성 팝업창에서 그룹명 입력 및 그룹으로 묶을 파라미터를 선택하고 [확인] 버튼을 클릭합니다.

그림파라미터 그룹 생성
필수 파라미터에서 [되묻기 질문] 버튼을 클릭합니다.

그림되묻기 질문

되묻기 질문 팝업창에서 되묻기 질문 응답을 입력하고 바로연결 응답 및 되묻기 허용 횟수를 설정합니다.

그림그룹 되묻기 질문 설정

표되묻기 질문 창

구분	설명
되묻기 질문 응답	되묻기 질문을 정의하며, 총 세 개까지 정의 가능 - 되묻기 질문은 사용자에게 출력되는 허용 횟수 안에서 무작위 순으로 출력됨
바로연결 응답	사용자가 되묻기 상황에서 입력할 파라미터 값을 클릭해 보낼 수 있도록 버튼을 설정
되묻기 허용 횟수 설정	되묻기 질문이 실행될 횟수를 선택 - 최대 허용 횟수가 끝나서 결국 원하는 파라미터 값을 획득하지 못했을 때 Bot이 사용자에게 출력할 안내 메시지를 정의함

위 작업이 완료되면 그룹에 속한 파라미터 중 하나라도 입력 시 파라미터가 채워진 것으로 간주하고, 파라미터가 아무것도 채워지지 않은 경우에만 되묻기 질문을 수행합니다.

안내
그룹 파라미터 설정에서 되묻기 질문을 사용하고 싶지 않은 경우, 고정값을 가진 파라미터를 파라미터 그룹에 포함합니다.

고정값을 가진 파라미터를 파라미터 그룹에 포함하면 어떤 사용자 발화에도 최소 한 개의 값이 채워진 상태라고 판단하기 때문에 되묻기 질문을 수행하지 않습니다.

그룹 파라미터 중 추출된 파라미터만 Skill Request에 전달됩니다.

필수 파라미터 검증

필수 파라미터 검증은 사용자 발화를 통해 입력된 필수 파라미터가 유효한 값인지 파라미터 검증 API를 사용해 검증하고 처리하는 기능입니다. 파라미터 검증 API가 입력된 필수 파라미터를 유효한 값으로 판단하면 정상적으로 Skill을 호출하지만, 유효하지 않은 값일 경우 Skill을 호출하지 않고 사용자에게 되묻기 질문을 수행합니다. 자세한 설명은 [챗봇 관리자센터] 파라미터 검증 API를 참고하시기 바랍니다.

파라미터 검증 방법

파라미터 검증 API를 설정해 필수 파라미터를 검증하는 방법은 다음과 같습니다.

[Builder 사이트] 챗봇 관리자센터에서 [+ 봇 만들기]를 클릭합니다.

그림챗봇 관리자센터
내 챗봇 메뉴에서 원하는 봇을 선택합니다.

그림내 챗봇
파라미터 설정 패널 우측에 있는 필수 파라미터 탭의 [+] 버튼을 클릭합니다.

그림필수 파라미터 추가
파라미터 만들기 팝업창에서 기본 설정 항목들을 입력합니다. 그림파라미터 생성
파라미터 검증 API 주소에 파라미터 검증 API URL을 입력합니다.
- 검증 실패 시 “유효하지 않은 값입니다."(default)라는 메시지로 답변 처리되며, 검증 실패 오류 메시지 문구를 직접 입력할 수 있습니다.
[확인] 버튼을 클릭합니다.

파라미터 검증 API

파라미터 검증 API는 검증 결과를 나타내는 status와 함께 Resolved 값인 value를 반환할 수 있으며, Resolved 값은 Skill에 해당 파라미터의 값으로 전달됩니다. 파라미터 검증 API의 결과가 FAIL이면 파라미터가 채워지지 않은 것으로 판단하여 사용자에게 되묻기 질문을 수행합니다.

표파라미터 검증 API

파라미터	타입	필수 여부	설명
status	String	`필수`	필수 파라미터 값이 유효한지를 나타내는 상태 값
			`SUCCESS`: 유효한 값
			`FAIL`: 유효하지 않은 값
			`ERROR`: 에러
value	Integer	`선택`	Skill에 해당 파라미터의 값으로 전달
data	String	`선택`	비정형화된 추가 정보를 대화에 저장하기 위해 JSON 형식으로 전달

시나리오 예시

알파벳 문자가 필수 파라미터이고, 파라미터 검증 API가 A, B, C만 허용하는 경우의 시나리오입니다.

표파라미터 검증 시나리오

대화 입력	사용자 발화	스피커 답변	동작
1차	“정답은 D”	“A, B, C 중에 정답을 말해주세요.”	알파벳 문자 파라미터에 연결한 파라미터 검증 API가 `FAIL`을 반환하면, 필수 파라미터가 채워지지 않았다고 판단하므로 되묻기 질문 응답이 자동으로 출력되고, 블록에 연결된 Skill이 호출되지 않음
2차	“정답은 A”	“정답입니다.”	알파벳 문자 파라미터에 연결한 검증 API가 `SUCCESS`를 반환하면, 필수 파라미터가 채워진 것으로 판단하여 Skill이 호출되고 해당 파라미터가 전달됨

Sample Code

파라미터 검증 API의 Response 예시입니다.

코드예제파라미터 검증 API Response Sample Code

JSON

{
        "status": "SUCCESS",
        "value": "a",
        "data": {
                "extracted": "a"
        }
}

알파벳 엔티티 Validator API

알파벳 엔티티 Validator API는 시스템에서 제공하는 파라미터 검증 API로서, URL Path Parameter인 candidates에 원하는 알파벳을 지정하여 사용합니다.

사용자 음성이 인식된 사용자 발화 문장 중에서 한 개의 알파벳 단독 발화가 존재하는 경우 status에 SUCCESS를 반환합니다. 반대로, 지정된 알파벳이 추출되지 않으면 status에 FAIL을 반환합니다.

표알파벳 엔티티 Validator API

API 명	API URL
알파벳 엔티티 Validator	`http://shadow.i.kakao.com/api/v1/validator/kakaoi_entities?entity_type=kakaoi.entity.v0.alphabet&mode=extract&extract_value_selector=resolved&candidates=a,b,c`

안내
알파벳 엔티티 Validator API는 챗봇 관리자센터의 파라미터 검증 API 설정을 통해서만 호출됩니다.

알파벳 엔티티 Validator API는 영어 문자 인식 방식의 검증을 위해 한시적으로 제공되는 API로서 향후 인식률 또는 사용 개선을 위해서 제공되는 방식이나 사용법이 변경될 수 있습니다.

시나리오 예시

시나리오 구현 시 다음과 같이 (1) 또는 (2)의 파라미터로 답변 구현이 가능한 경우, (1)과 (2)에 해당하는 두 가지 파라미터를 그룹 파라미터로 설정합니다. 이후 되묻기 질문을 설정하면 두 가지 파라미터 중 어느 것도 추출되지 않으면 자동으로 되묻기 질문을 수행합니다.

(1) 음성 인식된 최종 발화에서 ‘나의 엔티티’로 정의한 a, b, c 엔티티
(2) 음성 인식된 모든 문장 후보군 중 알파벳 엔티티 Validator를 통해 추출되는 알파벳 문자

스피커 > 정답을 골라주세요.
사용자 » 정답은 z입니다.
스피커 > 잘 못 들었어요. a, b, c 중에 정답을 골라주세요. (되묻기 질문)
사용자 » 정답은 z입니다.
… (되묻기 질문 횟수만큼 반복 후 Skill request 호출)
스피커 > 오답입니다. 다음 문제입니다.

동작 예시

사용자가 “에이” 라고 발음했는데, 음성 인식된 문장 중 가장 유의미한 Score가 매겨진 문장이 “hey”인 경우의 예시입니다.

표"에이"라고 발화 시 동작 예시

음성 인식된 문장 후보(Score 순)	최종 선택된 문장(utterance)	발화패턴에서 태깅된 나의 엔티티 찾기	알파벳 엔티티 Validator로 알파벳 문자 찾기
1. “hey” 2. “헤이” 3. “a” 4. “hay” 5. “너 hey” 6. “heh” 7. “너 헤이” 8. “hey you” 9. “에이” 10. “hey u”	“hey”	“hey”에서는 ‘나의 엔티티’로 설정된 a, b, c, d를 추출할 수 없음	알파벳 엔티티 Validator에서 음성 인식 후보군을 모두 조사하여 유의미한 알파벳 발화 1건을 선정

Sample Code

Skill Request에 알파벳 엔티티 Validator API로 추출된 파라미터가 포함된 예시입니다.

코드예제알파벳 엔티티 Validator API로 추출된 Elements

JSON

{
        "action": {
                "id": "ACTION_ID_1234",
                "name": "kakaoi.sample",
                "params": {
                        "extractedAnswer": "a"
                },
                "detailParams": {
                        "extractedAnswer": {
                                "origin": "none",
                                "value": "a",
                                "groupName": "answerGroup"
                        }
                }
        },
        "intent": {
                "id": "INTENT_ID_1234",
                "name": "kakaoi.intent"
        },
        "bot": {
                "id": "BOT_ID_1234!",
                "name": "카카오토익"
        },
        "userRequest": {
                "utterance": "hey",
                "lang": "kr"
        }
}

컨텍스트 사용 답변

컨텍스트 사용은 사용자의 음성명령에 질문으로 답변을 내보내고, 문맥적인 상황인 컨텍스트를 사용하여 사용자와의 상호적인 대화 시나리오를 구현하는 기능입니다.

안내
컨텍스트를 사용하여 대화 시나리오 구성 시 answer.dialog를 reply로 지정해 봇 답변 재생 후 마이크를 자동으로 열어둘 수 있습니다. 자세한 설명은 [카카오 i 기술문서] Skill API 레퍼런스를 참고하시기 바랍니다.

컨텍스트 설정

컨텍스트를 설정하는 방법은 다음과 같습니다.

[Builder 사이트] 챗봇 관리자센터에서 [+ 봇 만들기]를 클릭합니다.

그림챗봇 관리자센터
내 챗봇 메뉴에서 원하는 봇을 선택합니다.

그림내 챗봇
[+블록 추가]를 클릭하여 사용자의 음성 명령에 질문을 내보낼 블록(A)과 그 답변을 처리할 블록(B)을 생성합니다.
- 사용자의 음성 명령에 질문을 내보낼 블록(A): 이후, 질문 블록(A)으로 통일
- 그 답변을 처리할 블록(B): 이후, 답변 블록(B)으로 통일
그림질문 및 답변 블록 생성
질문 블록(A)과 답변 블록(B)의 사용자 발화 섹션에 사용자의 예상 대표 발화를 각각 등록합니다.

그림질문 블록의 사용자 발화 등록

그림답변 블록의 사용자 발화 등록
질문 블록(A)에서 오른쪽 위의 [•••] 버튼을 클릭한 후 컨텍스트 설정 메뉴로 이동합니다.

그림질문 블록의 컨텍스트 설정 메뉴
컨텍스트 설정 팝업창에서 Output 컨텍스트 섹션의 [+] 버튼을 눌러 컨텍스트 이름을 입력하고 유효 횟수(lifespan, 수명)와 유효 시간(ttl, seconds 단위의 시간 값)을 지정합니다.
- 질문 블록(A)이 실행될 때 Output 컨텍스트가 지정된 수명과 유효 시간만큼 생성되어 유지됩니다.
그림질문 블록에서 Output 컨텍스트 지정
답변 블록(B)의 컨텍스트 설정 메뉴에서 질문 블록의 Output 컨텍스트 이름과 동일하게 Input 컨텍스트 이름을 지정합니다.

그림답변 블록에서 Input 컨텍스트 지정

표수명 만료에 따른 동작 예시

구분	동작
수명 만료 전	답변 블록(B)에 등록된 발화가 입력되면 답변 블록(B)이 실행
수명 만료 후	답변 블록(B)에 등록된 발화 패턴이 입력되어도 답변 블록(B)이 실행되지 않고 폴백 블록이 실행

컨텍스트를 설정한 예시는 다음과 같습니다.

표컨텍스트 설정 예시

구분	발화 패턴 등록	스피커 답변	컨텍스트 설정	의미
질문 블록(A)	“토익 테스트 시작”	“문제를 듣고 정답을 골라주세요”	Output 컨텍스트: `{"name": "asked", "lifespan": 3}`	이후 사용자 대화 3회 동안 “asked”라는 컨텍스트 상태 값이 유지됨
답변 블록(B)	“정답은 에이”	“정답입니다.”	Input 컨텍스트: `{"name": "asked"}`	“asked”라는 컨텍스트 상태 값이 유지되는 동안 이 블록 발화 패턴에 해당하는 사용자 발화가 입력되면 답변 블록이 실행됨

안내
컨텍스트가 실행된 블록의 Output 컨텍스트로 지정되어 있거나 Skill에 전달되는 리퀘스트의 inputContexts에 포함된 경우, Skill Response에서 lifespan / ttl / param 항목을 변경하여 반환하면 해당 클라이언트의 Bot 대화 컨텍스트가 업데이트됩니다. 컨텍스트 사용에 대한 자세한 설명은 [챗봇 관리자센터] 컨텍스트 사용하기를 참고하시기 바랍니다.

Sample Code

다음은 질문 블록의 Skill Response 예시입니다. 질문 블록의 Skill Response에 답변 블록으로 전달하고 싶은 Output 컨텍스트의 param을 다음과 같이 반환하시기 바랍니다.

코드예제질문 블록의 Skill Response Sample Code

JSON

{
        "answer": {
                "status": "normal",
                "sentence": "보기 중에 정답을 골라주세요.",
                "dialog": "reply"
        },
        "outputContexts": [
                {
                        "name": "engQuestionAsked",
                        "lifespan": 3,
                        "ttl": 300,
                        "param": {
                                "currentStep": 1,
                                "totalSteps": 3
                        }
                }
        ]
}

다음은 답변 블록의 Skill Request 예시입니다. 답변 블록의 Skill 파라미터에 Input 컨텍스트의 param을 지정하면 다음과 같이 전달됩니다.

코드예제답변 블록의 Skill Request

JSON

{
        "action": {
                "id": "ACTION_ID_1234",
                "name": "kakaoi.sample"
        },
        "intent": {
                "id": "INTENT_ID_1234",
                "name": "kakaoi.intent"
        },
        "bot": {
                "id": "BOT_ID_1234!",
                "name": "테스트"
        },
        "userRequest": {
                "utterance": "테스트 응답",
                "lang": "kr"
        },
        "contexts": [
                {
                        "name": "engQuestionAsked",
                        "lifespan": 3,
                        "params": {
                                "currentStep": {
                                        "value": 1,
                                        "resolvedValue": 1
                                },
                                "totalSteps": {
                                        "value": 3,
                                        "resolvedValue": 3
                                }
                        }
                }
        ]
}

에러 응답 시 컨텍스트 생성하지 않기

다음 예시와 같이 블록에 연결된 Skill에서 에러 응답을 반환한 경우에도 지정된 수명 동안 해당 블록에 설정된 outputContext가 무조건 생성됩니다.

따라서 사용자에게 에러 응답을 제공하지만 컨텍스트는 생성하지 않을 경우에는 outputContexts의 lifespan을 0으로 지정합니다.

코드예제에러 응답을 제공하지만 컨텍스트는 생성하지 않을 경우

JSON

{
        "answer": {
                "status": "normal",
                "sentence": "등록되지 않은 사용자입니다. 가입 후에 다시 시도해주세요.",
                "dialog": "terminate"
        },
        "outputContexts": [
                {
                        "name": "engQuestionAsked",
                        "lifespan": 0
                }
        ]
}

기존 대화 블록에서 컨텍스트 정보 가져오기

이 기능은 질문 블록 (A)에서 생성된 컨텍스트 정보를 답변 블록(B)에서 파라미터로 전달받아 활용하는 기능입니다.
이 기능을 사용하기 위해서는 질문 블록(A)의 Response의 outputContexts.param에 map 형태의 데이터를 포함하고, 답변 블록(B)의 Skill 파라미터에 이를 지정해야 합니다.

답변 블록(B)의 파라미터 설정 패널에서 일반 파라미터의 [+] 버튼을 클릭합니다.

그림일반 파라미터 추가

파라미터 만들기 팝업창에서 다음의 항목을 지정하고, [확인] 버튼을 클릭합니다.

표파라미터 만들기 팝업창 항목

구분	의미
파라미터명	답변 블록(B)에서 전달받을 파라미터 이름
엔티티	`sys.constant`를 입력
값	`#{input 컨텍스트의 이름}.{input 컨텍스트 param의 필드 이름}`을 입력

그림답변 블록(B)의 Skill 파라미터 값을 지정

위 작업이 완료되면, 답변 블록(B) 실행 시 질문 블록(A) Skill Response의 Output 컨텍스트의 param 중 해당 필드 값을 전달받게 됩니다.

그림Skill 파라미터 설정

공통 발화와 답변 블록 연결

공통 발화란 긍정/부정/중지(응/아니/그만) 발화 등 답변 블록에 공통으로 쓰이는 발화입니다. 공통 발화는 다른 음성 명령과는 다르게 보이스봇 블록에 등록해도 스피커 등 실제 음성 서비스에서 해당 블록이 실행되지 않으며, 긍정 답변 블록, 부정 답변 블록, 중지 답변 블록에 별도의 연결 요청이 필요합니다.

공통 발화를 답변 블록에 연결하는 방법은 다음과 같습니다.

질문 블록에서 Skill 서버의 응답(answer)으로 질문 문장(sentence)과 함께 “dialog”: “reply”를 반환하고, Output 컨텍스트를 생성합니다.
긍정/부정/중지 답변 블록에서 input 컨텍스트를 질문 블록의 output 컨텍스트와 동일한 이름으로 지정합니다.
질문 후 긍정/부정/중지 발화가 입력되었을 때 스피커에서 해당 답변 블록이 실행됩니다.

안내
답변 블록에 공통 발화를 연결 시, 컨텍스트 사용 답변에서 설명한 질문 블록 및 답변 블록을 구현한 방식(컨텍스트 사용)이 동일하게 적용됩니다.

주의
챗봇 관리자센터 사이트에서 Bot 테스트 시, 해당 발화 등록만으로 블록이 실행되더라도 실제 스피커에서는 폴백 블록이 실행됩니다.

시나리오 예시

블록별 답변 및 컨텍스트 설정 예시는 다음과 같습니다.

표블록별 답변 및 컨텍스트 설정 예시

구분	발화 패턴 등록	스피커 답변	컨텍스트 설정
질문 블록	“레벨테스트 시작”	“레벨테스트를 시작할까요?”	Output 컨텍스트: `{"name": "started", "lifespan": 3}`
긍정 답변 블록	“응”	“레벨테스트를 시작합니다. 문제를 듣고, A, B, C, D 중에 정답을 말해주세요.”	Input 컨텍스트: `{"name": "started"}`
부정 답변 블록	“아니”	“나중에 토익 학습을 하려면, 산타토익을 불러주세요.”	Input 컨텍스트: `{"name": "started"}`

질문/답변 중 중지 답변을 받는 경우는 다음과 같습니다.

표질문/답변 중 중지 답변 예시

구분	발화 패턴 등록	스피커 답변	컨텍스트 설정
질문 블록	“듣기평가 시작”	“문제를 듣고, A, B, C, D 중에 정답을 말해주세요.” + (문제재생)	Output 컨텍스트: `{"name": "asked", "lifespan": 3}`
긍정 답변 블록	“A”	“정답입니다. 다음 문제는 ...”	Input 컨텍스트: `{"name": "asked"}`
부정 답변 블록	“그만”	“그만할게요. 총 {M}개의 문제 중 {N}개를 맞췄어요.”	Input 컨텍스트: `{"name": "asked"}`

안내
공통 발화 묶음은 긍정 답변(응, 그래, 네, 예 등), 부정 답변(아니, 아니요, 아니야 등), 중지 답변(그만, 멈춰 등) 뿐만 아니라 다양한 묶음이 존재합니다. 추가적인 오픈 스펙은 현재 준비 중으로 필요한 경우 문의하시기 바랍니다.

지연 안내 답변

지연 안내 답변은 Skill 서버에서 응답 지연 시 답변 지연 안내 후, 보이스봇에서 답변 재생 시작/종료 이벤트를 받아 처리하는 기능으로, 이를 통해 지연 안내 답변이 재생되는 시간만큼 Skill에서 처리 시간을 확보합니다.

챗봇 관리자센터 사이트에 연결된 Skill의 Response Timeout은 2초이며, Skill이 2초 이내에 응답하지 않으면 카카오 i 클라이언트에 Timeout 에러 답변(“일시적인 오류로 처리할 수 없어요" 등)이 발생합니다. Response에 2초 이상의 시간이 필요한 경우, Response에서 지연 안내 답변(“잠시 후에 다시 시도해 주세요", “잠시만 기다려주세요. 다음 문제를 찾고 있습니다.” 등)을 반환한 후, 준비된 정식 답변을 반환할 수 있습니다.

Skill에서 지연 안내 답변과 함께 해당 음성 답변에 대해 발생하는 재생 시작과 종료, 취소 이벤트를 전달할 수 있습니다. Skill 서버는 전달되는 이벤트 명과 토큰을 포함한 Request 정보를 참조하여 필요한 비즈니스 로직을 수행합니다.

지연 안내 내보내기

Response의 answer.sentence 위치에 일반 Text 또는 SSML 타입의 답변 문장을 반환하면서, baggage.token이라는 항목을 추가하여 해당 답변에 대한 유니크 식별자를 지정합니다.

표__baggage__

구분	설명
__baggage__	Skill Response 중에서 보이스봇의 음성 답변에 대한 추가적인 정보를 담는 필드
	__baggage__에 포함되어, Skill Response의 음성 답변을 고유하게 식별할 수 있는 String
서비스 제공자명	16자 이내의 알파벳 소문자로 부득이한 경우 온점(`.`)으로 구분자 사용 ex) kakao, kakao.com
봇 아이디	Skill을 호출한 봇의 ID로 Skill Request의 `body.bot.id`로 전달된 값을 사용해야 함 - 테스트 모드인 경우, “`!`” 로 끝나는 `bot.id`를 사용해야 발급한 토큰으로 다시 이벤트를 전달받을 수 있음
유니크 식별값	1,024자 이내의 String

정식 답변 내보내기

음성 답변 재생의 시작과 종료 이벤트를 처리할 블록을 생성합니다.
- 해당 블록에서 이벤트만 처리하는 경우에는 사용자 발화는 입력할 필요가 없습니다.
오른쪽 위의 [•••] 버튼을 눌러 이벤트 설정 메뉴로 이동합니다.

그림이벤트 설정 메뉴

이벤트 설정 팝업창에서 아래의 Event 중 필요한 Event를 입력하고, [확인] 버튼을 클릭합니다.

이벤트 설정에서 Event 명 입력 후 엔터를 눌러야 저장됩니다.

표Event 명

Event 이름	설명
Synthesizer.SpeakStarted	토큰을 지정한 스피커 답변이 재생 시작할 때 발생
Synthesizer.SpeakFinished	토큰을 지정한 스피커 답변이 끝까지 재생 완료되었을 때 발생
Synthesizer.SpeakStopped	토큰을 지정한 스피커 답변이 재생 중에 중단되었을 때 발생 - 사용자가 스피커를 웨이크업해서 마이크가 열렸을 때, 별도의 스피커 음성 답변이 푸시로 발생하거나(“택시가 도착했어요.”), 알람/타이머 멘트가 재생될 때(“알람 시간이에요.”) 등 중단된 스피커 답변은 인터럽트 상황이 종료되어도 이어서 재생되지 않고 삭제됨

그림이벤트 설정

Event가 호출되었을 때 사용할 Skill을 연결합니다.

그림Skill 서버 연결
위 작업이 완료되면 Request에 다음의 정보가 전달됩니다.
- Event 명: userRequest.event.name
- 이전 음성 답변에 지정한 Token: userRequest.params.body.token
- 일반 블록이 사용자 음성명령으로 호출되었을 때와 마찬가지로 Skill Request에 이전 대화로부터 생성되어 유효하게 남아있는 contexts와 Skill 파라미터로 지정한 action.params 등도 전달됩니다.

Sample Code

답변 문장 뒤에 3초 묵음을 포함해서 음성 합성된 오디오 소스가 클라이언트에서 재생되는 경우, 답변이 재생된 다음 종료 이벤트를 받은 후 다음 답변을 반환하도록 되어있습니다. 따라서 현재 답변은 “dialog”: “finish”로 지정하여 답변 재생 후 마이크를 열지 않도록 합니다.

답변 문장 뒤에 3초 묵음을 포함한 오디오 소스가 클라이언트에서 재생되는 경우입니다. 답변에 포함된 3초간의 묵음이 재생된 이후, 종료 이벤트를 받아 다음 답변을 반환하도록 설계되어 있습니다. 따라서 이 예시에서는 “dialog”: “finish”로 지정하여 답변 재생 후 마이크를 열지 않습니다.

코드예제답변 문장 뒤에 3초 묵음을 포함한 오디오 소스가 클라이언트에서 재생되는 경우

JSON

{
        "answer": {
                "status": "normal",
                "sentence": "<speak><voice>정답입니다. 다음은 2번 문제입니다.</voice><audio src=\"kakaosound://_/Silence/3초\"/></speak>",
                "dialog": "finish"
        },
        "outputContexts": [
                {
                  ...
                }
        ],
        "__baggage__": {
                "token": "kakao/BOT_ID!/ENG_ANSWER.XINSTANCEID_123.20190126_1234"
        }
}

이전 응답 종료 후 다음 답변을 이어서 재생하기

이전 응답 종료 후 다음 답변을 이어서 재생할 경우, 블록에 Synthesizer.SpeakFinished 이벤트를 지정하고 연결된 Skill에서 필요한 답변을 반환하면 됩니다.

사용자 음성 명령으로 호출되는 일반 블록과 동일한 방식으로 봇 응답 섹션에서 {{webhook.answer.sentence}}을 지정합니다.

그림봇 응답 설정
Skill Response의 answer.sentence 위치에 답변을 지정하면 스피커에서 음성 답변을 재생할 수 있습니다.

시나리오 예시

사용자 발화로 연결된 블록 A에서 1차 답변 후, 해당 답변 재생 종료 이벤트로 호출된 블록 B에서 질문 문장과 함께 마이크를 엽니다. 이에 대한 사용자 답변을 받아 Input Context C가 지정된 블록에서 처리하고 싶은 경우에는 이벤트로 호출된 블록 B에서는 Context가 생성되지 않으므로 이전에 호출된 블록 A에서 Context C를 생성해야 합니다.
시나리오 예시는 다음과 같습니다.

사용자 » (블록X) 카카오토익에서 오늘의 학습 시작해줘
보이스봇 » (문제 재생) 보기 중에 정답을 골라주세요. + context C 생성 + 마이크 열림(“dialog”: “reply”)
사용자 » (블록A) 에이
보이스봇 » 정답입니다. + context C 생성 + 마이크 열지 않음(“dialog”: “finish”)
스피커 » (블록B) Synthesizer.SpeakStarted 이벤트 발생
보이스봇 » (다음 문제 재생) 보기 중에 정답을 골라주세요 + 마이크 열림(“dialog”: “reply”)
사용자 » (블록A) 에이
보이스봇 » 정답입니다. + context C 생성 + 마이크 열지 않음(“dialog”: “finish”)
스피커 » (블록B) Synthesizer.SpeakStarted 이벤트 발생
보이스봇 » (다음 문제 재생) 보기 중에 정답을 골라주세요 + 마이크 열림(“dialog”: “reply”)
사용자 » (블록A) 에이
보이스봇 » 정답입니다. 오늘의 학습 3문제 중에 3문제를 맞혔습니다.

Sample Code

Event로 블록이 실행될 때 Request 예시는 다음과 같습니다.

코드예제Event로 블록이 실행될 때 Request Sample Code

JSON

{
        "action": {
                "id": "SKILL_ID",
                "name": "SKILL_NAME",
                "params": {
                        "currentStep": "2",
                        "totalSteps": "3"
                },
                "detailParams": {
                  ...
                }
        },
        "contexts": [
          ...
        ],
        "intent": {
                "id": "INTENT_ID",
                "name": "handleEvent"
        },
        "bot": {
                "id": "BOT_ID",
                "name": "실험실"
        },
        "userRequest": {
                "event": {
                        "name": "Synthesizer.SpeakFinished",
                        "data": null
                },
                "params": {
                        "agent": {
                          ...
                        },
                        "body": {
                                "token": "kakao/BOT_ID/ENG_ANSWER.XINSTANCEID_123.20190126_1234"
                        }
                }
        }
}

Synthesizer.SpeakStarted 이벤트에 동작 없이 무시하는 응답을 내릴 경우 Response 예시는 다음과 같습니다.

코드예제동작 없이 무시하는 응답을 내릴 경우 Response

JSON

{
        "answer": {
                "status": "dummy",
                "sentence": "",
                "dialog": "terminate"
        }
}

주의
스피커에서 발생하는 이벤트로 블록이 호출되는 것은 챗봇 관리자센터를 통해 설계되는 대화의 컨텍스트에 영향을 주지 않습니다.

컨텍스트 설정 메뉴를 통해 Output 컨텍스트를 지정하거나, Skill Response에서 Context를 반환하더라도 봇의 컨텍스트가 생성/수정되지 않고, 블록이 호출되어도 생성되어 있는 컨텍스트의 lifespan이 차감되지 않습니다.

기존 대화 블록에서 컨텍스트 정보 가져오기

이 기능은 질문 블록(A)에서 생성된 컨텍스트 정보를 답변 블록(B)에서 파라미터로 전달받아 활용하는 기능입니다.
이 기능을 사용하기 위해서는 질문 블록(A)의 Response의 outputContexts.param에 map 형태의 데이터를 포함하고, 답변 블록(B)의 Skill 파라미터에 이를 지정해야 합니다.

답변 블록(B)의 파라미터 설정 패널에서 일반 파라미터 섹션의 [+] 버튼을 클릭합니다.

그림일반 파라미터 추가

파라미터 만들기 팝업창에서 다음의 항목을 지정하고, [확인] 버튼을 클릭합니다.

표파라미터 만들기 팝업창 항목

구분	의미
파라미터명	답변 블록(B)에서 전달받을 파라미터 이름
엔티티	`sys.constant`를 입력
값	`#{input 컨텍스트의 이름}.{input 컨텍스트 param의 필드 이름}`을 입력

그림답변 블록(B)의 Skill 값 지정

위 작업이 완료되면, 답변 블록(B) 실행 시 질문 블록(A) Skill Response의 Output 컨텍스트의 param 중 해당 필드 값을 전달받게 됩니다.

그림Skill 파라미터 설정

Bot 재분류

Bot 재분류는 음성 명령으로 보이스봇의 블록이 실행된 후 해당 블록에 연결된 Skill API가 호출되었지만 Skill 서버에서 명령을 실행할 수 없는 경우에 다른 Bot으로 재분류하는 기능입니다. 재분류를 위해서는 Skill Response의 answer.status 값을 “handover”로 Bot에 전달해야 합니다.

시나리오 예시

“뽀로로 틀어줘” 라는 음성 명령을 다른 Bot으로 재분류하는 시나리오입니다.

“뽀로로 틀어줘” 라는 사용자 음성 명령을 “TV Bot” > “콘텐츠 재생” 블록으로 분류하고, “콘텐츠 재생” 블록의 Skill API를 호출합니다.
Skill API 서버에서 “뽀로로” 콘텐츠가 없어 사용자 명령을 실행할 수 없는 경우, Skill 서버에서 Skill Response로 “status”: “handover”를 반환합니다.
해당 음성명령을 카카오 i 플랫폼에서 재분류해서 적절한 Bot으로 다시 전달합니다.
- 예를 들어, 해당 음성명령이 “음악봇” 으로 다시 전달되어서 “뽀로로” 노래를 스피커로 재생할 수 있습니다.

Sample Code

위 시나리오에서 tv봇의 Skill Response 예시는 다음과 같습니다.

코드예제TV Bot의 Skill Response Sample Code

JSON

{
        "answer": {
                "status": "handover",
                "sentence": "",
                "dialog": "terminate"
        }
}

Kakao i Skill::개발 프로세스(Voice)::Skill 활용 답변 부가 기능

페이지 이동경로

엔티티에서 파라미터 추출

엔티티 등록

파라미터 설정

Sample Code

폴백 블록 설정

시나리오 예시

Sample Code

되묻기 질문

시나리오 예시

필수 파라미터 개별 설정

그룹 파라미터 설정

필수 파라미터 검증

파라미터 검증 방법

파라미터 검증 API

시나리오 예시

Sample Code

알파벳 엔티티 Validator API

시나리오 예시

동작 예시

Sample Code

컨텍스트 사용 답변

컨텍스트 설정

Sample Code

에러 응답 시 컨텍스트 생성하지 않기

기존 대화 블록에서 컨텍스트 정보 가져오기

공통 발화와 답변 블록 연결

시나리오 예시

지연 안내 답변

지연 안내 내보내기

정식 답변 내보내기

Sample Code

이전 응답 종료 후 다음 답변을 이어서 재생하기

시나리오 예시

Sample Code

기존 대화 블록에서 컨텍스트 정보 가져오기

Bot 재분류

시나리오 예시

Sample Code