Kakao i Skill::Skill API 레퍼런스

페이지 이동경로

Bot-Skill 서버 연동 API

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

Bot 시스템 요청과 Skill 서버 응답 그림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 필수 개발사에서 생성한 카카오 i 오픈빌더의 블록에 정의한 파라미터
- 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
- 카카오 i 오픈빌더에서 테스트 시, 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.typeaiin일 때, 요청한 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

{
    "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으로 전달 보장하지 않음
error: 마이크 활성화
- 음성 입력 시 직전 Bot으로 전달 보장(TTL = 60s)
Array 선택 이전 화행(또는 요청)과 다음 화행(또는 요청) 사이에 Context 전달을 위해 사용
- 장치와 수차례 이어서 대화를 주고받더라도 장치에 대화의 주제를 지정함
Q1 » 택시 불러줘
A1 » 어디로 가는 택시를 호출할까요?
Q2 » 판교역
A2 » 판교역으로 가는 택시를 호출할까요?
Q3 » 응
A3 » 네, 호출할게요
name String 선택 카카오 i 오픈빌더에 정의한 outputContext 값을 코드레벨에서 정의/수정 가능
- 카카오 i 오픈빌더에 정의한 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

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

관련 문서

개발 프로세스(Voice) Kakao i Skill Skill API 레퍼런스 Kakao i Skill 음성 답변 가이드 Kakao i Skill SSML 활용 가이드 Kakao i Skill

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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