벤더 인터페이스 정의
벤더 인터페이스(Vendor Interface)는 카카오 i에서 제공하는 인터페이스 이외에 특정 클라이언트와 전용 Bot이 독자적으로 추가 정의할 수 있는 Message 규칙을 의미합니다.
벤더 인터페이스를 활용하여 카카오 i SDK를 탑재한 클라이언트 전용 Bot을 개발할 때, 클라이언트의 상태 정보 조회(State), 클라이언트의 상태 변화 이벤트 수신(Event), 클라이언트에 동작 지시(Instruction)에 대한 Message 규칙을 정의하고 이를 Bot에 지정된 Skill API의 Request와 Response에 활용할 수 있습니다.
표벤더 인터페이스 구성Message | 설명 |
---|---|
Event | Bot의 Skill 서버로 전달되는 클라이언트의 상태 변화 이벤트 |
Instruction | Bot의 Skill 서버에서 클라이언트로 지시하는 특정 동작 |
State | Bot의 Skill 서버로 전달되는 클라이언트의 상태 정보 |
Message 공통 포맷
벤더 인터페이스를 구성하는 Event, Instruction, State는 공통의 Message 포맷을 가집니다.
표Message 포맷파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
String | 필수 |
Message를 구분하는 이름 | |
벤더 이름 | String | 필수 |
클라이언트와 Bot의 쌍을 위해 독자적으로 정의된 벤더 인터페이스의 제공자 - 주로 고객사를 지칭 ex) AbcCompany |
인터페이스 이름 | String | 필수 |
클라이언트와 Bot의 쌍을 위해 독자적으로 정의된 벤더 인터페이스의 이름 - 다수의 Event, Instruction, State를 적절한 기능으로 그룹화한 이름 ex) Navigation |
Message 이름 | String | 필수 |
동일한 벤더 인터페이스 이름 - 그룹화된 하위 Event, Instruction, State Message 이름 ex) Started, Start, NaviState |
Object | 필수 |
Message로 전달하고 싶은 추가 파라미터 | |
token | String | 선택 |
Message에 대한 유니크 식별값 - 벤더 이름, 봇 아이디, 유니크 식별자로 활용할 UUID를 슬래시(/)로 구분 - {벤더 이름}/{봇 아이디}/{uuid} 같은 형식으로 지정 |
data | Object | 필수 |
Message type 별로 독자적으로 정의한 파라미터 형식- 임의의 Object 형태로 구성 가능 |
type 파라미터 표기
type
파라미터에서 Message를 구분하는 이름을 정의할 때, Vendor.{벤더 이름}.{인터페이스 이름}.{Message 이름}
과 같이 온점(.
)으로 구분된 4-depth 알파벳 텍스트(Camel 표기법)로 구성합니다.
예를 들어, 고객사 AbcCompany의 클라이언트가 카카오 i SDK를 탑재하고, 클라이언트에서 제공할 전용 Bot을 개발하는 경우를 생각해 봅시다. Navigation 기능에 대한 벤더 인터페이스를 정의하고 싶은 경우에는 다음과 같이 Message type
을 정의합니다. 또한 각각의 Message type
에 대한 추가 파라미터를 정의해서 body
파라미터로 전달할 수 있습니다.
Message | 예시 | 설명 |
---|---|---|
Event | Vendor.AbcCompany.Navigation.Started | 클라이언트에서 네비게이션 기능이 시작되었다는 이벤트 |
Instruction | Vendor.AbcCompany.Navigation.Start | 클라이언트에서 네비게이션 기능을 시작하라는 지시 |
State | Vendor.AbcCompany.Navigation.NaviState | 클라이언트에서 네비게이션 기능의 실행 상태 |
token 파라미터 사용
Instruction/Event
카카오 i에서는 Bot의 Skill 서버가 클라이언트로 전달하는 Instruction Message에 토큰을 지정하는 것을 권장하며, 이 경우 클라이언트는 Instruction Message를 수행한 결과로 발생한 Event Message에 동일 토큰을 전달해야 합니다.
이렇게 Instruction과 Event Message가 동일 토큰을 교환함으로써, Bot의 Skill 서버는 Event Message를 전달받았을 때 Event Message에 포함된 토큰이 어떤 Instruction에 대한 결과인지 식별할 수 있습니다. 특히 Event Message의 경우, Bot의 ID가 형식에 맞게 토큰에 명시되어야 해당 Bot의 Skill Request로 Event Message가 전달됩니다.
State
클라이언트에서 발생하는 State Message에 포함된 토큰은 꼭 필요하지 않은 경우 생략될 수 있습니다.
표State Message 포함 토큰구분 | 설명 |
---|---|
Instruction Message에서 지정한 토큰이 특정 리소스(ex. 오디오 아이템 식별자)를 지칭하고 State Message에 대한 상태 값을 표시하는 경우 | 동일 토큰을 전달해서 Instruction Message에서 지시한 리소스의 상태 정보(ex. 오디오 아이템 재생 중)를 나타낼 수 있음 |
특정 리소스와 관계없는 상태 값의 경우 ex) 스피커 볼륨값 |
토큰은 생략될 수 있음 |
벤더 인터페이스 사용
특정 클라이언트와 전용 Bot에서 독자적으로 정의한 Message 규칙인 벤더 인터페이스를 사용하는 방법은 다음과 같습니다. 그림벤더 인터페이스 작업 흐름
Event와 State Message 전달받기
클라이언트가 전송한 Event Message를 Bot의 Skill Request 로 전달받는 방법은 다음과 같습니다.
-
[Builder 사이트] 챗봇 관리자센터에서 + 블록 추가를 클릭하여 Event Message를 처리할 Bot 블록을 생성합니다.
그림블록 추가
-
[•••] 버튼을 클릭하여 이벤트 설정 메뉴로 이동합니다.
그림이벤트 설정 메뉴
-
이벤트 설정 팝업창에서 벤더 인터페이스로 정의한 Event Message의
type
을 입력하고, [확인] 버튼을 클릭합니다.- 앞서 설명한 표 | type 파라미터 표기 예시에 따라
Vendor.AbcCompany.Navigation.Started
와 같이 Messagetype
의 전체 문자열을 입력합니다. - 이벤트 설정에서 이벤트 명을 입력하고 Enter를 눌러야 저장됩니다.
그림이벤트 설정
- 앞서 설명한 표 | type 파라미터 표기 예시에 따라
-
클라이언트에서 벤더 인터페이스로 정의한 Event Message가 발생한 경우, 해당 Message는 Bot의 Event 블록에 연결된 Skill Request로 전달됩니다. 이때,
type
파라미터와body
파라미터는 서로 다른 위치에서 전달됩니다.- 해당 Event Message의
type
파라미터: Skill Request Body의userRequest.event
파라미터로 전달 - 해당 Event Message의
body
파라미터: Skill Request Body의userRequest.params.body
파라미터로 전달
- 해당 Event Message의
-
만약 클라이언트에서 Event Message와 함께 State Message를 전달한 경우, 해당 State Message는 Bot Skill에 전달될 때 Skill Request Body의
userRequest.params.state
파라미터로 전달됩니다.
Sample Code
다음은 event
와 state
Message가 포함된 Skill Request Body 예시입니다.
코드예제Skill Request Sample Code
{
"bot": {
"id": "5ae18fc0909c27767522324",
"name": "Abc컴퍼니"
},
"intent": {
"id": "5ae0909d118d4df5b7a13fbf8",
"name": "startedEvent"
},
"userRequest": {
"event": "Vendor.AbcCompany.Navigation.Started",
"params": {
"body": {
"token": "AbcCompany/5ae18fc0909c27767522324/navi-bd1b6f6d2f3b4e88a9fbbe965c5040ab",
"data": {
"target": "판교역"
}
},
"state": [
{
"type": "Vendor.AbcCompany.Navigation.NaviState",
"body": {
"data": {
"estimatedArrivalTime": 1609242922716
}
}
}
]
},
"user": {
"id": "KAI1234567890",
"type": "aiin"
}
}
}
Instruction Message 전달하기
Bot의 Skill 서버가 클라이언트에게 Instruction Message를 전달하는 작업 흐름은 다음과 같습니다.
-
Bot에 연결된 Skill API 호출 시, 응답의
instructions
필드에 벤더 인터페이스로 정의한 Instruction Message가 반환됩니다. -
클라이언트가 해당 Instruction Message를 전달받고, 정의된 동작을 수행합니다.
Sample Code
다음은 instruction
Message가 포함된 Skill Response Body의 예시입니다.
코드예제Skill Response Sample Code
{
"_code": 200,
"answer": {
"status": "normal",
"sentence": "판교역으로 길안내할게요.",
"dialog": "terminate"
},
"instructions": [
{
"type": "Vendor.AbcCompany.Navigation.Start",
"body": {
"token": "AbcCompany/5ae18fc0909c27767522324/navi-bd1b6f6d2f3b4e88a9fbbe965c5040ab",
"data": {
"target": "판교역"
}
}
}
]
}