Kakao Work::Bot 시작 가이드

페이지 이동경로

카카오워크 Bot

Bot(봇)은 특정 목적으로 구성된 시나리오에 따라 특정 임무를 수행하도록 프로그래밍이 된 애플리케이션으로, 일반적으로 시스템 알람을 수신하거나 멤버와 대화를 할 수 있는 기능을 제공합니다. 카카오워크(Kakao Work)에서 Bot은 특정 워크스페이스에 가입된 멤버로부터 내/외부 응용 프로그램의 권한을 부여받아 멤버 정보 조회, 채팅방 생성, 메시지 전송 등의 다양한 작업을 수행할 수 있으며, 기본 Bot과 커스텀 Bot으로 구분됩니다.
카카오워크에서 사용되는 워크스페이스(Workspace)란 멤버들로 구성된 작은 집합으로 팀/회사/단체/계열사 단위로 설정하여 사용할 수 있는 업무 공간을 의미합니다.

카카오워크 Bot 종류
구분 설명
기본 Bot 카카오워크 서버에 이미 등록되어 카카오워크 사용자들에게 무료로 제공되는 Bot
ex) Google Drive Bot, Jira Enterprise Bot
커스텀 Bot 고객사의 특정 업무에 필요한 다양한 협업 서비스 및 사내 시스템과 연동하여 멤버에게 중요한 알림을 전달하고 연동된 기능을 수행할 수 있는 Bot
- 커스텀 Bot의 개발은 [Admin 사이트] 관리자 서비스에서 수행

관리자 서비스

카카오워크에서는 고객사의 업무 환경과 요구 사항에 맞는 커스텀 Bot의 개발을 지원하기 위해 [Admin 사이트] 관리자 서비스를 별도로 제공하고 있습니다. 카카오워크 서버에서 기본적으로 제공하고 있는 Bot 관리뿐만 아니라 원하는 기능을 가진 커스텀 Bot을 생성하고 수정 및 관리를 할 수 있습니다.

관리자 서비스에서 제공하는 대표적인 기능은 다음과 같습니다.

  • Bot 개발자 등록
  • 카카오워크 서버에 기본으로 등록되어 제공되는 기본 Bot의 관리
  • 커스텀 Bot 생성, 수정 및 관리

관리자 서비스 정보
명칭 링크
관리자 서비스 admin.kakaowork.com
안내
관리자 서비스에 접근이 불가능한 경우 참여 중인 워크스페이스의 개설자에게 문의 부탁드립니다.

관리자 서비스에는 슈퍼 관리자, 관리자, Bot 개발자 등의 권한이 있으며, Bot 개발을 위해 아래의 표| 관리자 서비스 권한 정보에서 각 권한의 상세 내용을 참고하시기 바랍니다.

관리자 서비스 권한 정보
권한 명 권한 사항
슈퍼 관리자
(스페이스 개설자)
워크스페이스 개설자로서 스페이스의 모든 권한을 관리
- 슈퍼 관리자는 멤버에게 관리자 권한 혹은 개발자 권한 부여 가능
- 슈퍼 관리자도 개발자로 등록하여 Bot 개발 가능
관리자 슈퍼 관리자 또는 기존 관리자로부터 권한을 부여받은 멤버
- 개발자 권한을 부여하려면 봇 관리 메뉴에 대한 설정 권한을 받아야 함
- 봇 관리 메뉴에 대한 권한을 받은 관리자는 멤버에게 개발자 권한 부여 가능
- 관리자도 개발자로 등록하여 Bot 개발 가능
Bot 개발자 봇 관리 > Bot 개발 메뉴에만 접근 가능
- 슈퍼 관리자 혹은 관리자로부터 개발자 권한을 부여받아야 함
- Bot 개발자 권한을 부여받은 후에 관리자 서비스에 로그인하여 Bot 개발 가능

Block Kit Builder

카카오워크에서 Block Kit Builder(블록 킷 빌더)는 Block Kit을 활용하여 조합형 말풍선을 자유롭게 구성 할 수 있도록 도와주며, 또한 JSON 코드를 쉽게 확인할 수 있습니다.

Block Kit Builder 정보
명칭 링크
Block Kit Builder kakaowork.com/block-kit-builder

Bot 개발 라이프 사이클

Bot 개발 라이프 사이클 그림Bot의 개발 라이프 사이클

위의 그림 | Bot 개발 라이프 사이클과 같이 총 5단계로 구성된 Bot의 개발 라이프 사이클을 이해한 후에 Bot을 기획하고 구현한다면, 더욱 효율적인 방식으로 Bot을 생성할 수 있습니다. 각 단계별 상세 설명은 다음과 같습니다.

Bot 개발 라이프 사이클
단계 설명
기획 Bot 시나리오 기획이 완료되면 개발 담당자에게 공유
- 기획된 Bot 시나리오가 카카오워크 API를 활용하여 구현이 가능한지 개발자와 확인 필요
- Bot 기획 참고
개발 고객사 Bot 개발 담당자는 카카오워크 서버에 기획된 Bot 시나리오를 구현
테스트 개발된 Bot의 정상 동작 여부 확인을 위해 일정 기간 테스트를 진행
- 카카오워크 서버에 Bot이 등록되면, 전체 멤버가 Bot을 사용할 수 있는 상태가 됨
- 별도의 테스트용 워크스페이스를 생성 후, Bot 개발을 추천
- 운영 중인 워크스페이스에서 테스트가 필요한 경우, Bot의 이름을 “개발 중”으로 표시하거나 코드 네임으로 사용하는 것을 추천
공개 Bot 개발이 완료되면 멤버에게 Bot에 대한 충분한 설명을 진행
모니터링 Bot을 사용하는 멤버로부터 피드백을 수집
- Bot 시나리오를 개선할 부분이 있는지 검토하여 다시 기획한 후, Bot에 적용

안내
현재 카카오워크 Bot은 단일 워크스페이스에만 활성화됩니다. 한 개 이상의 워크스페이스에 공통으로 노출할 파트너 Bot을 제작해야 할 경우, 카카오워크 담당자(kakaowork_platform@kakaoenterprise.com)에게 별도 문의 부탁드립니다.

  • 등록된 커스텀 Bot은 해당 워크스페이스의 전체 멤버에게 메시지를 전송하도록 설정되어 있습니다. 만약 일부 멤버에게만 메시지를 전송해야 할 경우, 고객사 서버에서 메시지 수신자의 목록을 관리할 수 있는 로직을 별도로 개발해야 합니다. (Bot 메시지의 수신자 목록 관리 기능은 추후 제공 예정)

Bot과 대화하기

카카오워크에서 Bot과 사용자간 대화 시나리오는 그 특성에 따라 알림형반응형으로 구분됩니다.
알림형은 Bot이 특정 이벤트에 대한 간단한 알림 메시지를 멤버에게 일방향으로 알려주며, 상호 인터랙션은 하지 않는 시나리오입니다. 알림형은 Bot이 멤버에게 단순 텍스트 메시지만 전달하는 일반 텍스트 유형과 다양한 블록들을 조합하여 말풍선 형태로 보낼 수 있는 조합형 말풍선 유형으로 구분됩니다.
반면 반응형은 Button Block의 action_typesubmit_action 또는 call_modal속성을 활용하여 메시지를 수신한 사용자와 상호작용할 수 있는 시나리오입니다.

메시지 유형 그림메시지 유형

Bot과 대화하기 구분
구분 메시지 유형 설명
알림형 일반 텍스트 Bot이 채팅방을 생성하여 멤버에게 단방향으로 별도 서식없이 단순 텍스트 메시지를 전송
조합형 말풍선 다양한 Block들을 조합하여 Bot이 멤버에게 단방향으로 조합형 말풍선을 전송
반응형 반응형 메시지 Bot이 채팅방을 생성하고 멤버와 대화를 시도하며, 멤버는 버튼을 클릭하여 Bot과 대화를 계속 이어나갈 수 있음
- 멤버가 클릭한 버튼 정보는 Callback URL로 전달됨
반응형 Modal 채팅방에 Modal 화면이 표시되며, 멤버는 버튼을 클릭하거나 메시지를 입력하여 Bot과 대화를 계속 이어나갈 수 있음
- 멤버가 Modal에서 입력하거나 선택한 정보가 Bot의 Callback URL로 전달됨

알림형

알림형이란 간단한 공지 메시지와 같이 Bot이 채팅방을 생성하고, 상호 인터랙션이 필요없는 메시지를 전달할 때 적합합니다. 알림형은 단순 일반 텍스트만 사용자에게 제공하는 일반 텍스트 메시지 또는 Block Kit을 활용하여 조합형 말풍선을 제공할 수 있습니다. 알림형 조합형 말풍선 시나리오에서는 메시지에 버튼을 삽입할 수 있지만, 이 버튼은 단순히 외부 서비스나 애플리케이션으로 이동만 가능합니다. 따라서 메시지를 수신한 멤버가 버튼을 선택했을 때, 해당 데이터가 다시 고객사의 서버로 전달되지는 않습니다.
알림형 메시지의 동작 시나리오는 다음과 같습니다.

일반 텍스트

Bot이 사용자에게 일반 텍스트 메시지만 전달할 때 주로 사용되는 유형입니다. 메시지 전달의 시나리오는 아래의 조합형 말풍선과 동일한 프로세스로 제공됩니다.

일반 텍스트 활용 그림일반 텍스트 활용

  1. Bot 생성 및 관리: 사전에 Bot 기획을 완료한 후, Bot 개발자는 [Admin 사이트] 관리자 서비스에서 Bot을 생성합니다.
  2. Bot 인증: Bot 생성 시에 인증키(App Key)는 자동으로 부여됩니다.
  3. 멤버 조회: 대화를 시작하고자 하는 멤버의 정보를 조회하고, user_id를 발급받습니다.
  4. 채팅방 생성: user_id를 이용하여 채팅방을 생성하고, conversation_id를 발급받습니다.
  5. 알림형 대화(일반 텍스트): 채팅방에 별도의 서식없는 일반 텍스트로 구성된 메시지를 표시합니다.
안내
알림형 시나리오 중 텍스트로만 사용자에게 제공하는 예시는 일반 텍스트를 참고하시기 바랍니다.

조합형 말풍선

조합형 말풍선은 다양한 블록들을 조합하여 말풍선 형태로 보낼 수 있는 유형입니다. 조합형 말풍선 시나리오에서는 메시지에 버튼을 삽입할 수는 있지만, 멤버가 해당 버튼을 클릭하면 단순히 외부 서비스나 애플리케이션으로 이동만 가능합니다.

조합형 말풍선 활용 그림조합형 말풍선 활용

  1. Bot 생성 및 관리: 사전에 Bot 기획을 완료한 후, Bot 개발자는 [Admin 사이트] 관리자 서비스에서 Bot을 생성합니다.
  2. Bot 인증: Bot 생성 시에 인증키(App Key)는 자동으로 부여됩니다.
  3. 멤버 조회: 대화를 시작하고자 하는 멤버의 정보를 조회하고, user_id를 발급받습니다.
  4. 채팅방 생성: user_id를 이용하여 채팅방을 생성하고, conversation_id를 발급받습니다.
  5. 알림형 대화(조합형 말풍선): 채팅방에 다양한 Block들을 조합한 말풍선 메시지를 표시합니다.
안내
알림형 시나리오 중 Block Kit을 활용하여 조합형 말풍선을 구성하여 제공하는 예시는 조합형 말풍선을 참고하시기 바랍니다.

반응형

반응형 시나리오에서는 메시지를 수신한 멤버가 버튼을 클릭하거나 혹은 새로운 입력창에서 직접 텍스트를 입력하는 등의 액션을 통해 Bot과 상호작용하며 대화를 이어나갈 수 있습니다. Button Block의 action type은 submit_action 또는 call_modal을 사용할 수 있습니다. 각 속성 별 시나리오는 다음과 같습니다.

반응형 메시지

Button Block의 action_type 중 submit_action 속성을 사용하면, Bot이 채팅방을 생성하고 멤버와 대화를 시도하고 멤버는 버튼을 클릭하여 Bot과 대화를 계속 이어나갈 수 있습니다. 이때 멤버가 클릭한 버튼 정보는 Callback URL로 전달됩니다. submit_action 속성을 활용한 시나리오는 다음과 같습니다.

반응형 메시지 활용 그림반응형 메시지 활용

  1. Bot은 멤버에게 특정 액션을 수행할 수 있는 Button Block이 포함된 메시지를 전송합니다.
    • Button Block의 action_typesubmit_action로 설정되어야 합니다.
  2. 멤버가 메시지를 확인하고, 원하는 버튼을 클릭합니다.
  3. 카카오워크 서버는 검증이 완료된 Bot의 Callback URL로 클라이언트 화면에서 멤버가 선택한 버튼 정보를 전달합니다.
  4. Callback URL로 전송이 완료되면, 버튼을 선택한 액션 시나리오가 종료됩니다.
안내
반응형 시나리오 중 submit_action 속성을 활용한 구성 예시는 반응형 메시지를 참고하시기 바랍니다.

반응형 Modal

Button Block의 action_type 중 call_modal 속성을 사용하면, 카카오워크 클라이언트에 Modal 화면이 표시됩니다. 멤버가 해당 Modal 화면의 옵션을 선택하거나 입력한 데이터는 Bot의 Callback URL에 전달됩니다.
call_modal 속성을 활용한 시나리오는 다음과 같습니다.

반응형 시나리오 그림반응형 Modal 활용

  1. Bot은 멤버에게 특정 액션을 수행할 수 있는 Button Block이 포함된 메시지를 전송합니다.
  2. 멤버가 메시지를 확인하고, 원하는 버튼을 클릭합니다.
  3. 클라이언트 화면에 Modal이 출력되며, 카카오워크 서버는 검증이 완료된 Bot의 Request URL로 이벤트 정보를 전달합니다.
  4. 고객사 서버는 응답(Response) 값에 Modal에 표시할 블록 정보를 포함해 카카오워크 서버로 전달합니다.
  5. 클라이언트 화면의 Modal에 전달받은 블록들이 표시됩니다.
  6. 멤버가 Modal에서 요청한 값을 입력하거나 선택한 뒤, 화면 하단의 Modal Button을 클릭합니다.
  7. 사전에 검증 완료된 Bot의 Callback URL로 멤버가 작성한 정보를 전송합니다.
  8. Callback URL로 전송이 완료되면, Modal 화면이 종료됩니다.
안내
반응형 시나리오 중 call_modal 속성을 활용한 구성 예시는 반응형 Modal를 참고하시기 바랍니다.

관련 문서

Bot 시작 가이드 Kakao Work Web API 레퍼런스 Kakao Work Block Kit 구성 및 정책 Kakao Work Bot 메시지 시나리오 Kakao Work

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

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