반응형 메시지

반응형 대화에서 특정 액션 타입이 지정된 버튼을 통해 멤버의 의견을 전달받고, 다음 시나리오로 이어나갈 때 submit_action API를 사용합니다. submit_action API를 사용하기 위해서는 말풍선 구성 시에 Button Block의 action_type을 submit_action으로 설정해야 합니다.

표Submit API 리스트

API 명	설명
submit_action	사용자가 선택한 Button의 정보와 멤버 ID, 해당 메시지의 정보를 고객사 서버로 전달

안내
Block Kit 블록에 대한 자세한 사항은 [카카오 i 기술문서]Block Kit 구성 및 정책 문서를 참고하시기 바랍니다.

submit_action

메시지 블록에서 사용자가 선택한 Button의 정보와 멤버 ID, 해당 메시지의 정보를 고객사 서버로 전달합니다.

Request

Callback Syntax

멤버가 Button을 클릭했을 때, 고객사의 Callback URL로 다음과 같이 POST 요청이 전송됩니다.

코드예제submit_action Request Syntax

BASH

curl -X POST https://{Bot 등록 시 설정한 callback_url} \
    -H "Content-Type: application/json;charset=utf-8"
    -d '{
            "type": "submit_action",
            "action_time": {카카오워크 서버의 현재 시간 값},
            "message": {
                "blocks": [{멤버가 선택한 메시지의 blocks 필드}],
                "conversation_id": {멤버와 메시지가 상호작용한 채팅방의 ID},
                "id": {멤버가 상호작용한 메시지의 ID},
                "text": "{멤버가 상호작용 한 메시지의 암호화된 text 필드}",
                "user_id": {멤버가 상호 작용한 메시지를 작성한 Bot의 유저 ID}
            },
            "react_user_id": {상호작용한 멤버},
            "action_name": {멤버가 상호작용한 버튼의 action_name},
            "value": {멤버가 상호작용한 버튼의 value}
        }'

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표submit_action Request Header

파라미터	타입	필수 여부	설명
Content-Type	String	`필수`	`application/json`으로 고정

안내
카카오워크 API 호출 방식은 application/json과 application/x-www-form-urlencoded의 형식을 지원하지만, 반응형 메시지 API는 application/json 형식만 허용합니다.

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표submit_action Request Elements

파라미터	타입	필수 여부	설명
type	String	`필수`	`submit_action`으로 고정
action_time	String	`필수`	카카오워크 서버의 현재 시간 값
	Object	`필수`	액션이 발생한 채팅 메시지 원본
id	Integer	`필수`	멤버가 상호작용한 메시지의 ID
text	String	`필수`	멤버가 상호작용한 메시지의 암호화된 text 필드
user_id	Integer	`필수`	멤버가 상호 작용한 메시지를 작성한 Bot의 유저 ID
conversation_id	Integer	`필수`	멤버와 메시지가 상호작용한 채팅방의 ID
blocks	Object[]	`선택`	멤버가 선택한 메시지의 blocks 필드
react_user_id	Integer	`필수`	상호작용한 멤버
action_name	String	`필수`	멤버가 상호작용한 버튼의 action_name
value	String	`필수`	멤버가 상호작용한 버튼의 value

Response

카카오워크 서버로부터 전달받은 Request를 성공적으로 처리한 경우, 봇 서버는 HTTP Status 200 성공 응답을 반환해야 합니다. 만약 200이외의 HTTP Status를 반환하게 되면 해당 요청을 실패한 것으로 판단합니다.

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표submit_action Response Elements

필드	타입	필수 여부	설명
body	Object	`필수`	`submit_action` 수행에 대한 결괏값

반응형 대화에서 특정 액션이 지정된 버튼을 통해 멤버의 의견을 입력받고 대화를 이어나가기 위해 Modal 화면을 사용할 수 있습니다. 다음 API를 사용하여 Modal 화면 구성 정보와 멤버의 입력 정보 등을 전달받을 수 있습니다.
Modal을 사용하기 위해서는 Block Kit을 사용하여 조합형 말풍선을 구성 시, Button Block의 action_type을 call_modal로 설정해야 합니다.

안내
현재 반응형 Modal API는 카카오워크 서버에서 고객사 서버로 아웃바운드(Outbound)되는 유형만 지원합니다.

표반응형 Modal API 리스트

대분류	API 명	설명
반응형 Modal	request_modal	Modal 화면을 구성하는 JSON 정보를 받음
반응형 Modal	submit_modal	사용자의 입력 정보를 모아 최종적으로 고객사 서버로 전달

안내
Block Kit 블록에 대한 자세한 사항은 [카카오 i 기술문서] Block Kit 구성 및 정책 문서를 참고하시기 바랍니다.

request_modal

고객사 서버에 Modal 화면을 구성하는 JSON 정보를 요청합니다.

Request

Request Syntax

코드예제request_modal Request Syntax

BASH

  curl -X POST https://{Bot 등록 시 설정한 request_url} \
    -H "Content-Type: application/json;charset=utf-8" \
    -d '{
            "type":"request_modal",
            "value":"{Bot 메시지의 버튼에 설정한 value 값}",
            "action_time":{카카오워크 서버의 현재 시간 값},
            "message":"{카카오워크 서버에서 관리하는 메시지 정보}"
        }'

표API 호출 방식

메서드	요청 URL
POST	Bot 등록 시, 카카오워크에게 제공한 `request_url` 정보 - 카카오워크에서 멤버가 Bot에게 특정 리소스를 요청할 때 사용하는 URL

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표request_modal Request Header

파라미터	타입	필수 여부	설명
Content-Type	String	`필수`	`application/json`

주의
카카오워크 API 호출 방식은 application/json과application/x-www-form-urlencoded의 형식을 지원하지만, 반응형 Modal API는 application/json 형식만 허용합니다.

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표request_modal Request Elements

파라미터	타입	필수 여부	설명
type	String	`필수`	`request_modal`로 고정
value	String	`필수`	Bot 메시지의 Button Block에 설정한 Value 값
action_time	String	`필수`	요청 액션이 발생한 카카오워크 서버의 시간 정보
	Object	`필수`	액션이 발생한 채팅 메시지 원본
id	Integer	`필수`	채팅 메시지 ID
text	String	`필수`	기본 텍스트 메시지
user_id	Integer	`필수`	메시지를 전송한 멤버 ID
conversation_id	Integer	`필수`	메시지가 작성된 채팅방 ID
send_time	Timestamp	`필수`	메시지가 전송된 시각
update_time	Timestamp	`필수`	메시지가 변경된 시각
blocks	Object[]	`선택`	블록 요소의 목록 - Block Kit 구성 및 정책 참고
react_user_id	Integer	`필수`	Modal 화면을 띄우고 request_modal을 수행한 사용자 아이디

안내
message 파라미터의 update_time과 send_time 값은 현재 전송되지 않고 있으나, 추후에 지원될 예정입니다.

Response

Response Syntax

코드예제request_modal Response Syntax

JSON

{
  "title": "결재요청 처리하기",
  "accept": "검토결과 전송하기",
  "decline": "취소",
  "value": "test=true",
  "blocks": [
    {
      "type": "label",
      "text": "검토결과 선택(필수)"
    },
    {
      "type": "select",
      "name": "sel_result",
      "required": true,
      "options": [
        {
          "text": "승인",
          "value": "1"
        },
        {
          "text": "반려",
          "value": "2"
        }
      ],
      "placeholder": "검토 결과를 선택해주세요"
    },
    {
      "type": "label",
      "inlines": [
        {
          "type": "styled",
          "text": "결과 선택 사유를 입력하세요(필수)",
          "bold": true
        }
      ]
    },
    {
      "type": "input",
      "name": "text_reason",
      "required": true,
      "placeholder": "사유를 입력해주세요(최대 1000자)"
    },
    {
      "type": "label",
      "text": "인풋블록테스트(필수X)",
      "inlines": [
        {
          "type": "styled",
          "text": "인풋블록테스트(필수X)",
          "bold": true
        }
      ]
    },
    {
      "type": "input",
      "name": "text_test",
      "required": false
    },
    {
      "type": "label",
      "text": "셀렉트블록테스트(필수X)",
      "inlines": [
        {
          "type": "styled",
          "text": "설렉트 "
        },
        {
          "type": "styled",
          "text": "블록",
          "bold": true
        },
        {
          "type": "styled",
          "text": "테스트(필수X)",
          "color": "red"
        }
      ]
    },
    {
      "type": "select",
      "name": "sel_result2",
      "required": false,
      "options": [
        {
          "text": "1번",
          "value": "1"
        },
        {
          "text": "2번",
          "value": "2"
        }
      ]
    }
  ]
}

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표request_modal Response Elements

필드	타입	필수 여부	설명
	Object	`필수`	Modal 화면을 그리는데 필요한 JSON 데이터
title	String	`필수`	Modal 타이틀
accept	String	`필수`	Modal의 수락 버튼에 표시할 내용
decline	String	`필수`	Modal을 닫기 위한 버튼에 표시할 내용 - 모바일의 경우 취소 버튼에 텍스트가 없기 때문에 무시
blocks	Object	`필수`	Modal을 구성하는 각각의 블록 리스트
value	String	`필수`	고객사 서버에서 다시 되돌려 받기를 희망하며 초기 설정한 값

submit_modal

Modal에서 사용자가 입력한 입력 정보를 모아 고객사 서버로 최종 전달합니다.

Request

Request Syntax

코드예제submit_modal Request Syntax

BASH

  curl -X POST https://{Bot 등록 시 설정한 callback_url} \
    -H "Content-Type: application/json;charset=utf-8" \
    -d '{
            "type":"submission",
            "actions":"{Modal에 사용자가 입력한 값}",
            "action_time":{카카오워크 서버의 현재 시간 값},
            "message":"{카카오워크 서버에서 관리하는 메시지 정보}",
            "value":{request_modal에 응답으로 준 value 값}
        }'

표API 호출 방식

메서드	요청 URL
POST	Bot 등록 시, 카카오워크에게 제공한 `callback_url` 정보 - 사용자가 Modal에 입력한 정보를 전달할 때 사용하는 URL

Request Header

Request Header에 대한 상세는 다음과 같습니다.

표submit_modal Request Header

파라미터	타입	필수 여부	설명
Content-Type	String	`필수`	`application/json`

주의
카카오워크 API 호출 방식은 기본적으로 application/json과 application/x-www-form-urlencoded의 형식을 지원하지만, 반응형 Modal API는 application/json 형식만 허용합니다.

Request Elements

Request Elements에 대한 상세는 다음과 같습니다.

표submit_modal Request Elements

파라미터	타입	필수 여부	설명
type	String	`필수`	`submission`으로 고정됨
action_time	String	`필수`	요청 액션이 발생한 카카오워크 서버의 시간 값
actions	Object	`필수`	Modal 화면에 사용자가 입력한 정보
	Object	`필수`	액션이 발생한 채팅 메시지 원본
id	Integer	`필수`	채팅 메시지 ID
text	String	`필수`	기본 텍스트 메시지
user_id	Integer	`필수`	메시지를 전송한 멤버 ID
conversation_id	Integer	`필수`	메시지가 작성된 채팅방 ID
send_time	Timestamp	`필수`	메시지가 전송된 시각
update_time	Timestamp	`필수`	메시지가 변경된 시각
blocks	Object[]	`선택`	블록 요소의 목록 - Block Kit 구성 및 정책 참고
react_user_id	Integer	`필수`	Modal 화면을 띄우고 `submit_modal`을 수행한 사용자 아이디
value	String	`필수`	request_modal의 응답으로 전송한 value 값

actions

actions필드는 key:value 쌍으로 구성된 Map 데이터이며, 사용자 입력 요소 중 name필드가 있는 항목만 값이 반환됩니다. 예를 들어, Input Block과 Select Block 중 name필드가 있는 항목은 필드 값이 Key가 되고, 사용자가 입력 또는 선택한 데이터가 Value 값이 되어 Map으로 전달됩니다.

다음은 Modal JSON 데이터가 제공된 경우를 가정한 예시입니다.

코드예제request_modal API 응답으로 Modal JSON 데이터가 제공된 경우

JSON

{
  "title": "결재요청 처리하기",
  "accept": "검토결과 전송하기",
  "decline": "취소",
  "value": "test=true",
  "blocks": [
    {
      "type": "label",
      "text": "검토결과 선택(필수)"
    },
    {
      "type": "select",
      "name": "sel_result",
      "required": true,
      "options": [
        {
          "text": "승인",
          "value": "1"
        },
        {
          "text": "반려",
          "value": "2"
        }
      ],
      "placeholder": "검토 결과를 선택해주세요"
    },
    {
      "type": "label",
      "inlines": [
        {
          "type": "styled",
          "text": "결과 선택 사유를 입력하세요(필수)",
          "bold": true
        }
      ]
    },
    {
      "type": "input",
      "name": "text_reason",
      "required": true,
      "placeholder": "사유를 입력해주세요(최대 1000자)"
    },
    {
      "type": "label",
      "text": "인풋블록테스트(필수X)",
      "inlines": [
        {
          "type": "styled",
          "text": "인풋블록테스트(필수X)",
          "bold": true
        }
      ]
    },
    {
      "type": "input",
      "name": "text_test",
      "required": false
    },
    {
      "type": "label",
      "text": "셀렉트블록테스트(필수X)",
      "inlines": [
        {
          "type": "styled",
          "text": "설렉트 "
        },
        {
          "type": "styled",
          "text": "블록",
          "bold": true
        },
        {
          "type": "styled",
          "text": "테스트(필수X)",
          "color": "red"
        }
      ]
    },
    {
      "type": "select",
      "name": "sel_result2",
      "required": false,
      "options": [
        {
          "text": "1번",
          "value": "1"
        },
        {
          "text": "2번",
          "value": "2"
        }
      ]
    }
  ]
}

request_modal 요청에 대한 응답으로 위와 같은 JSON 데이터가 제공되었을 때, 최종적으로 카카오워크에서 사용자 입력을 받아 고객사 서버에 전달할 때에는 아래와 같은 데이터가 됩니다.

코드예제고객사 제공

JSON

"actions": {
                "sel_result": "1",
                "text_reason": "사용자가 입력한 값", //승인을 선택
                "text_test": "사용자가 입력한 값",
                "sel_result2": "2" //2번을 선택
}

주의
request_modal API 응답으로 반환한 JSON 데이터에서 Input Block과 Select Block에 required 필드가 없거나 false인 경우, 사용자가 해당 필드에 값을 입력 또는 선택하지 않으면 submit_modal시에 null 값이 반환됩니다.

코드예제required 필드가 없거나 false인 경우 request_modal 응답

JSON

{
  "type": "input",
  "name": "text_reason",
  "required": false,
  "placeholder": "사유를 입력해주세요(최대 1000자)"
}

코드예제required 필드가 없거나 false인 경우 submit_modal

JSON

"actions": {
                ...
                "text_reason": null,
                ...
}

안내
message 파라미터의 update_time과 send_time 값은 현재 전송되지 않고 있으나, 추후에 지원될 예정입니다.

Response

Response Elements

Response Elements에 대한 상세는 다음과 같습니다.

표submit_modal Response Elements

필드	타입	필수 여부	설명
body	Object	`필수`	`submission` 수행에 대한 결괏값

kakaoIdocumentation

Kakao Work::Web API 레퍼런스::Reactive

페이지 이동경로

반응형 메시지

submit_action

Request

Callback Syntax

Request Header

Request Elements

Response

Response Elements

request_modal

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

submit_modal

Request

Request Syntax

Request Header

Request Elements

actions

Response

Response Elements