Bot 개발 프로세스

Bot 개발 프로세스 단계에서는 Bot 인증, 멤버 조회, 채팅방 생성, 메시지 전송 수행 과정을 포함합니다. Bot 개발 프로세스 단계를 진행하기에 앞서 Bot 기획 및 생성 단계를 미리 완료해야 합니다.

Bot 인증

Bot 인증은 해당 가이드에서 설명하는 멤버 조회(Users), 채팅방 생성(Conversation), 메시지 전송(Messages) API를 호출하기 전에 공통으로 수행하는 작업입니다. 자세한 설명은 API 인증 문서를 참고하시기 바랍니다.

1. Bot 생성 시에 자동으로 부여받은 App Key를 Request Header의 Authorization에 추가합니다.
2. 각 API의 Request 파라미터에 App Key를 이용하여 인증을 요청합니다.

코드예제Authorization Header 사용 Curl 요청

  curl -X POST https://api.kakaowork.com/v1/conversations.open \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -d "user_id={USER_ID}"

멤버 조회

Bot 인증이 완료되면, 멤버 조회를 위해 Users API를 호출하여 멤버의 고유 식별정보인 멤버 ID(user_id)를 발급받습니다. 카카오워크의 Users API는 멤버 정보를 조회하는 API뿐만 아니라 멤버 정보를 갱신하는 API도 제공합니다.

본 가이드는 Bot이 생성된 이후에 특정 멤버에게 메시지를 전송하기 위해 멤버를 조회하는 시나리오를 설명하고 있으므로, Users 중 멤버를 조회하는 API에 대해서만 설명합니다.

워크스페이스의 전체 멤버 조회

워크스페이스의 전체 멤버를 조회할 수 있는 users.list API를 호출하면 특정 워크스페이스에 속한 전체 멤버 목록과 각 멤버의 상세 정보를 한 번에 확인할 수 있습니다.
워크스페이스 멤버 목록은 유동적이기 때문에 Bot 서버는 워크스페이스에 속한 멤버 ID(user_id)를 확보하기 위해 주기적으로 전체 멤버를 조회해야 하는 경우가 발생합니다. 하지만 해당 API 호출 시, 이전 호출 결과와 비교하여 추가 또는 삭제된 멤버 ID를 찾아내는 과정에서 불필요한 호출과 처리 과정을 요구하기 때문에 주기적인 호출은 권장하지 않습니다.

카카오워크에서는 일회성으로 전체 멤버를 한 번 확보하고, 이후에 추가되는 멤버들은 별도로 관리하는 방식을 권장합니다.

1. 관리자 서비스 사이트에서 멤버를 모두 추가한 후 일회성으로 users.list API를 호출하여 전체 멤버 ID를 확보합니다.
2. 이후에 추가/삭제된 멤버의 경우에만 이메일로 멤버를 조회하는 users.find_by_email API를 통해 멤버 ID를 관리합니다.

특정 멤버의 상세 정보 조회

특정 멤버의 상세 정보를 조회할 수 있는 API는 다음과 같습니다. 특정 멤버의 정보 조회는 멤버의 고유 식별정보인 멤버 ID, 멤버가 워크스페이스 가입 시 인증 수단으로 활용한 이메일을 통해 조회할 수 있습니다.

안내
메시지 전송마다 멤버의 ID(user_id)를 획득하는 것보다는 한 번 획득한 멤버 ID 정보를 별도 목록으로 관리하여 사용하는 것을 권장합니다.

채팅방 생성

채팅방을 생성하기 위해서는 멤버를 조회한 후에 발급받은 멤버 ID(user_id)를 사용하여 Conversations API를 호출합니다.

• 카카오워크에서는 1:1 채팅방과 그룹 채팅방의 개설을 지원합니다.

안내
채팅방을 생성할 때마다 채팅방 ID(conversation_id)가 발급됩니다.

• 1:1 대화방의 경우에는 Bot의 대화 상대인 멤버 ID에 대해 한 개의 채팅방만 생성할 수 있습니다.
• 그룹 대화방의 경우에는 복수의 채팅방 생성이 가능합니다.

알림형 대화

채팅방이 생성되면, Messages API를 통해 메시지를 전송합니다. 알림형 대화는 Bot이 특정 이벤트에 대한 간단한 알림 메시지를 멤버에게 일방향으로 알려주는 유형입니다. Modal 화면이나 메시지 입력 등 멤버와 상호작용이 필요할 경우 반응형 대화 문서를 참고하시기 바랍니다.

메시지 전송 API를 호출하기 전에 표 | 메시지 유형을 참고하여 일반 텍스트형과 조합형 말풍선 중 하나를 선택하고, 멤버에게 전송할 메시지 유형을 먼저 정의해야 합니다.

안내
카카오워크는 Markdown 서식과 함축적이고 풍부한 표현을 도와주는 이모지(Emoji)를 지원합니다.

반응형 대화

Bot이 일방향으로 메시지를 전송하는 알림형 시나리오가 아닌 멤버와 상호작용을 할 수 있는 반응형 시나리오를 구성하기 위해서는 반응형 메시지 API 또는 반응형 Modal API를 활용할 수 있습니다.
반응형 메시지 API는 Button Block의 action_type을 submit_action 속성으로 지정한 경우에 멤버가 채팅방에서 버튼을 클릭했을 때 해당 정보를 고객사 서버의 Callback URL로 전달합니다. 반면 반응형 Modal API는 Button Block의 action_type이 call_modal 속성으로 지정된 경우, Modal 화면의 블록 구성을 Request URL로 요청하고 멤버가 입력 또는 선택한 데이터를 고객사 서버의 Callback URL로 전달합니다.

반응형 메시지

Button Block의 action_type 중 submit_action 속성을 적용하면 Bot의 멤버가 채팅방에서 버튼을 클릭했을 때 해당 정보를 고객사 서버의 Callback URL로 전달할 수 있습니다.

반응형 메시지 API를 사용하기 위해서는 다음의 설정이 필요합니다.

• Bot이 멤버에게 전송할 조합형 말풍선을 구성 시, Button Block의 action_type을 submit_action으로 설정해야 합니다.
• 관리자 서비스에서 Bot 생성 시, Callback URL 정보를 등록 후 검증을 완료해야 합니다. 자세한 설명은 URL 등록 문서를 참고하시기 바랍니다.

API 호출 순서

submit_action 속성에 대한 API 호출은 다음의 순서로 진행됩니다.

1. 멤버가 조합형 말풍선에서 submit_action 속성이 지정된 버튼을 클릭합니다.
2. submit_action API를 호출하여 멤버가 상호작용한 메시지 및 선택한 버튼의 정보를 고객사 서버에 전달합니다.

안내
자세한 설명은 Block Kit 구성 및 정책을 참고하시기 바랍니다.

반응형 Modal

Button Block의 action_type 중 call_modal 속성을 적용하면 Bot의 알림 메시지에서 버튼 클릭 시에 Modal 화면이 띄워집니다. 멤버는 Modal 화면에 정보를 입력하거나 옵션을 선택함으로서 Bot과 상호작용하며 대화를 이어나갈 수 있으며, 이때 멤버가 선택하거나 입력한 데이터는 고객사 서버로 전송됩니다.
Modal 화면을 활용한 반응형 대화를 위해서는 반응형 Modal API를 사용합니다.

Modal을 생성하기 위해서는 다음의 설정이 필요합니다.

• Button Block, Text Block 등을 사용하여 조합형 말풍선 구성 시, Button Block의 action_type을 call_modal로 설정해야 합니다.
• 관리자 서비스에서 Request URL과 Callback URL을 활용하는 Bot을 생성할 시에는 사전에 Request URL과 Callback URL 정보를 등록한 후 검증을 완료해야 합니다. 자세한 설명은 URL 등록 문서를 참고하시기 바랍니다.

API 호출 순서

call_modal 속성에 대한 반응형 Modal API 호출은 다음의 순서로 진행됩니다.

1. request_modal API를 호출하여 Bot 메시지 정보를 고객사 서버로 전달하고, Modal 화면을 구성하는 JSON 정보를 받습니다.
2. submit_modal API를 호출하여 Modal 화면에서 멤버가 입력한 정보를 고객사 서버에 전달합니다.

안내
자세한 설명은 Block Kit 구성 및 정책을 참고하시기 바랍니다.