Kakao i Skill::개발 프로세스(Voice)::벤더 인터페이스 연동

페이지 이동경로

벤더 인터페이스 정의

벤더 인터페이스(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 파라미터로 전달할 수 있습니다.

type 파라미터 표기 예시
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 로 전달받는 방법은 다음과 같습니다.

  1. [Builder 사이트] 카카오 i 오픈빌더에서 [+블록 추가] 버튼을 클릭하여 Event Message를 처리할 Bot 블록을 생성합니다.

    블록 추가 그림블록 추가

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

    이벤트 설정 메뉴 그림이벤트 설정 메뉴

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

    • 앞서 설명한 표 | 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

다음은 eventstate 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": "판교역"
                }
            }
        }
    ]
}

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

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