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 | 필수 |
사용자 계정 데이터 | |
id | String | 필수 |
사용자 계정 type에 따른 ID - userRequest.user.type 가 aiin 일 때, 요청한 Input Device를 구분하기 위한 고유한 값 |
type | String | 필수 |
사용자 계정 type - aiin 이라는 고정값으로 전달 |
Object | 필수 |
입력장치로부터 전달받은 데이터 목록 | |
Object | 필수 |
입력장치 데이터 | |
Object | 필수 |
입력장치의 패키지 데이터 | |
os | String | 필수 |
입력장치의 운영체제 데이터 |
Object | 필수 |
입력장치 Software Development Kit 데이터 | |
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으로 전달 보장하지 않음 |
|||
reply : 마이크 활성화- 음성 입력 시 직전 Bot으로 전달 보장(TTL = 60s) |
|||
Array | 선택 |
이전 화행(또는 요청)과 다음 화행(또는 요청) 사이에 Context 전달을 위해 사용 - 장치와 수차례 이어서 대화를 주고받더라도 장치에 대화의 주제를 지정함 Q1 » 택시 불러줘 |
|
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
{
"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