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

페이지 이동경로

반응형 메시지

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

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

submit_action

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

Request

Callback Syntax

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

코드예제submit_action Request Syntax

  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": {멤버가 상호 작용한 메시지를 작성한 봇의 유저 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/jsonapplication/x-www-form-urlencoded의 형식을 지원하지만, 반응형 메시지 API는 application/json 형식만 허용합니다.

Request Element

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

submit_action Request Elements
파라미터 타입 필수 여부 설명
type String 필수 submit_action으로 고정
action_time String 필수 카카오워크 서버의 현재 시간 값
Object 필수 액션이 발생한 채팅 메시지 원본
id Integer 필수 멤버가 상호작용한 메시지의 id
text String 필수 멤버가 상호작용한 메시지의 암호화된 text 필드
user_id Integer 필수 멤버가 상호 작용한 메시지를 작성한 봇의 유저 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번대 성공 응답을 반환합니다.

Response Element

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

submit_action Response Element
필드 타입 필수 여부 설명
body Object 필수 submit_action 수행에 대한 결과 값

반응형 Modal

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

안내
현재 반응형 Modal API는 카카오워크 서버에서 고객사 서버로 Outbound 되는 유형만 지원합니다.
반응형 Modal API 리스트
대분류 API 명 설명
반응형 Modal request_modal Modal 화면을 구성하는 JSON 정보를 받음
submit_modal 사용자의 입력 정보를 모아 최종적으로 고객사 서버로 전달

request_modal

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

Request

Request Syntax

코드예제request_modal Request Syntax

  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/jsonapplication/x-www-form-urlencoded의 형식을 지원하지만, 반응형 Modal API는 application/json 형식만 허용합니다.

Request Elements

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

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_timesend_time 값은 현재 전송되지 않고 있으나, 추후에 지원될 예정입니다.

Response

Response Elements

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

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

  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/jsonapplication/x-www-form-urlencoded의 형식을 지원하지만, 반응형 Modal API는 application/json 형식만 허용합니다.

Request Elements

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

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 데이터가 제공된 경우

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

request_modal 요청에 대한 응답으로 위와 같은 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 응답

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

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

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

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

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

Response

전달받은 Request를 성공적으로 처리한 경우 HTTP Status 200번대 성공 응답을 반환합니다.

Response Elements

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

submit_modal Response Elements
필드 타입 필수 여부 설명
body Object 필수 submission 수행에 대한 결과 값
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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