벤더 인터페이스 정의

벤더 인터페이스(Vendor Interface)는 카카오 i에서 제공하는 인터페이스 이외에 특정 클라이언트와 전용 Bot이 독자적으로 추가 정의할 수 있는 Message 규칙을 의미합니다.

벤더 인터페이스를 활용하여 카카오 i SDK를 탑재한 클라이언트 전용 Bot을 개발할 때, 클라이언트의 상태 정보 조회(State), 클라이언트의 상태 변화 이벤트 수신(Event), 클라이언트에 동작 지시(Instruction)에 대한 Message 규칙을 정의하고 이를 Bot에 지정된 Skill API의 Request와 Response에 활용할 수 있습니다.

Message 공통 포맷

벤더 인터페이스를 구성하는 Event, Instruction, State는 공통의 Message 포맷을 가집니다.

type 파라미터 표기

type 파라미터에서 Message를 구분하는 이름을 정의할 때, Vendor.{벤더 이름}.{인터페이스 이름}.{Message 이름}과 같이 온점(.)으로 구분된 4-depth 알파벳 텍스트(Camel 표기법)로 구성합니다.

예를 들어, 고객사 AbcCompany의 클라이언트가 카카오 i SDK를 탑재하고, 클라이언트에서 제공할 전용 Bot을 개발하는 경우를 생각해 봅시다. Navigation 기능에 대한 벤더 인터페이스를 정의하고 싶은 경우에는 다음과 같이 Message type을 정의합니다. 또한 각각의 Message type에 대한 추가 파라미터를 정의해서 body 파라미터로 전달할 수 있습니다.

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에 포함된 토큰은 꼭 필요하지 않은 경우 생략될 수 있습니다.

벤더 인터페이스 사용

특정 클라이언트와 전용 Bot에서 독자적으로 정의한 Message 규칙인 벤더 인터페이스를 사용하는 방법은 다음과 같습니다. 그림벤더 인터페이스 작업 흐름

Event와 State Message 전달받기

클라이언트가 전송한 Event Message를 Bot의 Skill Request 로 전달받는 방법은 다음과 같습니다.

1. [Builder 사이트] 챗봇 관리자센터에서 + 블록 추가를 클릭하여 Event Message를 처리할 Bot 블록을 생성합니다.

   그림블록 추가

2. [•••] 버튼을 클릭하여 이벤트 설정 메뉴로 이동합니다.

   그림이벤트 설정 메뉴

3. 이벤트 설정 팝업창에서 벤더 인터페이스로 정의한 Event Message의 type을 입력하고, [확인] 버튼을 클릭합니다.

   • 앞서 설명한 표 | type 파라미터 표기 예시에 따라 Vendor.AbcCompany.Navigation.Started 와 같이 Message type의 전체 문자열을 입력합니다.
   • 이벤트 설정에서 이벤트 명을 입력하고 Enter를 눌러야 저장됩니다.

   그림이벤트 설정

4. 클라이언트에서 벤더 인터페이스로 정의한 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 파라미터로 전달

5. 만약 클라이언트에서 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를 전달하는 작업 흐름은 다음과 같습니다.

1. Bot에 연결된 Skill API 호출 시, 응답의 instructions 필드에 벤더 인터페이스로 정의한 Instruction Message가 반환됩니다.

2. 클라이언트가 해당 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": "판교역"
                                }
                        }
                }
        ]
}