Bot-Skill 서버 연동 API

고객사의 서비스를 카카오 i 플랫폼 기반의 대화형 서비스를 통해 사용자 음성 명령 등으로 제공하고자 할 경우, 고객사는 [Builder 사이트] 챗봇 관리자센터에서 사용자와 상호 작용하는 Bot을 설계하고, 고객사의 Skill 서버를 해당 Bot과 연동해야 합니다.

그림Bot 시스템 요청과 Skill 서버 응답

이 장에서는 Bot-Skill 서버 연동에 참고할 수 있는 Skill Request와 Skill Response의 명세를 제공합니다.

표Bot-Skill 서버 연동 API 구성

구분	설명
Skill Request	Skill 실행 시, Bot 시스템이 Skill 서버에 전달하는 정보(Request)
Skill Response	Skill 서버가 Bot 시스템에 전달하는 응답(Response)

Request

Skill Request는 Skill 실행 시 Bot 시스템이 Skill 서버에 전달하는 정보(Request)입니다.

API 호출 방식

표API 호출 방식

메서드	요청 URL
POST	해당 Skill URL

Request Header

표Bot-Skill 서버 연동 Request Header

파라미터	타입	필수 여부	설명
X-Request-ID	String	`필수`	요청에 대한 Unique ID - 디버깅 시에 필요
KakaoI-Instance	String	`필수`	요청한 Input Device를 구분하기 위한 고유한 값 ex) AIIN KAI00000000000011179184

Request Body

표Bot-Skill 서버 연동 Request Body

파라미터	타입	필수 여부	설명
	Object	`필수`	블록의 Skill 수행을 위한 데이터 - 연결한 Skill 이름, Skill ID, 파라미터에 전달된 값 등을 포함
id	String	`필수`	Skill ID
name	String	`필수`	Skill 이름
params	Object	`필수`	개발사에서 생성한 챗봇 관리자센터의 블록에 정의한 파라미터 - `params.파라미터 명`은 `detailParams.파라미터 명.value` 값과 동일
	Object	`필수`	`params`의 하위 요소와 1:1로 정의됨
파라미터명.origin	String	`필수`	파라미터로 전달되는 엔티티의 원래 텍스트
파라미터명.groupName	String	`필수`	그룹 파라미터일 경우 그룹명
파라미터명.value	String	`필수`	정의된 엔티티 값
	Array	`필수`	사용자의 현재 대화 상태에 유효하게 존재하는 컨텍스트 데이터 - Bot에서 output 컨텍스트 지정을 했을 경우 지정한 대화 횟수(lifespan), TTL(유효 시간)에 따라 만료가 결정되는데 대화 진행 중에 만료되지 않은 컨텍스트 데이터가 전달됨
name	String	`필수`	이전에 대화를 진행한 블록에서 설정한 컨텍스트 이름
lifespan	Number	`필수`	컨텍스트 전달을 위한 Hop 개수 - 컨텍스트를 유지하는 대화를 진행할 때마다 1씩 감소
ttl	Number	`필수`	컨텍스트의 Time To Live
params	Object	`선택`	컨텍스트의 파라미터
	Object	`필수`	블록의 고유 ID와 이름을 포함한 블록 데이터
id	String	`필수`	블록 고유 ID
name	String	`필수`	블록 이름
	Object	`필수`	Bot의 고유 ID와 이름을 포함한 Bot 데이터
id	String	`필수`	Bot 고유 ID - 챗봇 관리자센터에서 테스트 시, ID 끝에 느낌표(!)가 추가됨
name	String	`필수`	Bot 이름
	Object	`필수`	사용자 요청 데이터 ex) 입력 장치 사용자의 발화데이터, 계정데이터, 장치데이터 등
	Object	`필수`	입력장치 사용자의 데이터
	Object	`필수`	사용자 계정 데이터
appUserId	String	`선택`	Bot이 Kakao Developers에서 생성한 앱과 연결되어 있는 경우, Bot을 실행한 사용자가 해당 앱의 가입자일 때, 앱에서 발급된 계정의 `userId`
appUserStatus	String	`선택`	appUserId의 상태 - `REGISTERED`: 정상
botUserKey	String	`필수`	Bot에서 고유하게 구분할 수 있는 사용자 식별값
id	String	`필수`	사용자 계정 type에 따른 ID - `userRequest.user.type`가 `aiin`일 때, 요청한 Input Device를 구분하기 위한 고유한 값
type	String	`필수`	사용자 계정 type - `aiin`이라는 고정값으로 전달
	Object	`필수`	입력장치로부터 전달받은 데이터 목록
	Object	`필수`	입력장치 데이터
	Object	`필수`	입력장치의 패키지 데이터
name	String	`필수`	패키지명
code	String	`필수`	패키지 코드
version	String	`필수`	패키지 버전
os	String	`필수`	입력장치의 운영체제 데이터
	Object	`필수`	입력장치 Software Development Kit 데이터
version	String	`필수`	입력장치 SDK의 버전
lang	String	`필수`	입력장치의 Locale code
device	String	`필수`	입력장치의 모델명
body	Object	`선택`	Event 요청 시 Event 메시지의 Body - 임의의 Object 포맷 허용
	Array	`선택`	입력장치의 상태 정보
type	String	`필수`	입력장치의 상태 정보의 state 종류
body	Object	`필수`	입력장치의 상태 정보의 state 상세 내용 - 임의의 Object 포맷 허용
utterance	String	`필수`	사용자 발화 내용
lang	String	`선택`	Locale code
timezone	String	`선택`	요청한 client 지역시간
	Object	`선택`	Event 요청 시 데이터
name	String	`필수`	Event 이름 - Event 메시지의 type
data	String	`필수`	Event 데이터

Sample Code

코드예제Bot-Skill 서버 연동 Request

JSON

{
        "action": {
                "id": "5ae090ae58d4df6b0a090975",
                "name": "ContentsTV.Volume",
                "params": {
                        "volume_interval": "1"
                },
                "detailParams": {
                        "volume_interval": {
                                "origin": "1",
                                "value": "1",
                                "groupName": ""
                        }
                }
        },
        "contexts": [
                {
                        "name": "sample_context",
                        "lifespan": 3,
                        "ttl": 600
                }
        ],
        "intent": {
                "id": "5ae0909d118d4df5b7a13fbf8",
                "name": "adjustVolumeUp"
        },
        "bot": {
                "id": "5ae18fc0909c27767522324",
                "name": "카카오TV"
        },
        "userRequest": {
                "user": {
                        "properties": {
                                "appUserId": "1234567890123456789",
                                "appUserStatus": "REGISTERED"
                        }
                },
                "params": {
                        "agent": {
                                "package": {
                                        "name": "com.kakao.i.vq",
                                        "version": "1.0.0",
                                        "code": "5"
                                },
                                "os": "Android 22",
                                "sdk": {
                                        "version": "0.1"
                                },
                                "lang": "KR",
                                "device": "KM1000/1.0.0"
                        }
                },
                "utterance": "볼륨 높여",
                "lang": "KR"
        }
}

Response

Skill Response는 Skill 서버가 Bot 시스템에 전달하는 응답(Response)입니다.

Response Elements

표Bot-Skill 서버 연동 Response Elements

파라미터	타입	필수 여부	설명
	Object	`필수`	출력장치로 응답할 데이터
status	String	`필수`	출력 장치의 응답 상태를 아래와 같이 지정
			`normal`: 정상 답변
			`dummy`: 묵음(답변 없음)
			`error`: 에러 상황을 의미하는 답변(스피커는 붉은 LED)
sentence	String	`선택`	출력 장치로 재생할 음성 답변 문장
dialog	String	`필수`	답변 재생 후 아래와 같은 동작을 지정
			`finish`: 마이크 비활성화
			`terminate`: 마이크 활성화 - 음성 입력 시 직전 Bot으로 전달 보장하지 않음
			`reply`: 마이크 활성화 - 음성 입력 시 직전 Bot으로 전달 보장(TTL = 60s)
	Array	`선택`	이전 화행(또는 요청)과 다음 화행(또는 요청) 사이에 Context 전달을 위해 사용 - 장치와 수차례 이어서 대화를 주고받더라도 장치에 대화의 주제를 지정함 Q1 » 택시 불러줘 A1 » 어디로 가는 택시를 호출할까요? Q2 » 판교역 A2 » 판교역으로 가는 택시를 호출할까요? Q3 » 응 A3 » 네, 호출할게요
name	String	`선택`	챗봇 관리자센터에 정의한 `outputContext` 값을 코드레벨에서 정의/수정 가능 - 챗봇 관리자센터에 정의한 `outputContext` 명과 일치해야 함
lifespan	Number	`선택`	이전 화행(또는 요청)과 다음 화행(또는 요청) 사이에 Context 전달을 위한 Hop의 수 - Context를 유지하는 대화를 진행할 때마다 1씩 감소 - 해당 값을 0으로 설정할 경우 Context가 무력화됨
ttl	Number	`선택`	Context의 Time To Live - Context 만료 시간을 초 단위로 지정 - 해당 시간이 지나면 Context가 무력화됨
	Array	`선택`	출력장치에서 수행할 명령어 리스트
type	String	`필수`	Instruction 종류
body	Object	`필수`	Instruction 데이터

Sample Code

코드예제Bot-Skill 서버 연동 Response

JSON

{
        "answer": {
                "status": "normal",
                "sentence": "서울역으로 가는 택시를 호출할게요.",
                "dialog": "terminate"
        },
        "outputContexts": [
                {
                        "name": "da_taxi_new_call",
                        "lifespan": 0
                }
        ]
}

kakaoIdocumentation

Kakao i Skill::Skill API 레퍼런스

페이지 이동경로

Bot-Skill 서버 연동 API

Request

API 호출 방식

Request Header

Request Body

Sample Code

Response

Response Elements

Sample Code

관련 문서