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

페이지 이동경로

Messages

특정 채팅방에 신규 메시지를 전송하거나 사용자의 이메일 주소를 통해 1:1 채팅방에 메시지를 전송하는 API는 다음과 같습니다.

Messages API 리스트
API 명 설명
messages.send 채팅방의 ID를 사용하여 특정 채팅방에 새로운 메시지를 전송
messages.send_by_email 이메일 주소를 통해 특정 사용자를 찾고, 1:1 채팅방에 메시지를 전송
messages.send_by 전달받은 이메일 주소 또는 Key 값을 사용하여 사용자와의 1:1 채팅방에 메시지를 전송
messages.send_attachments conversations.upload 통해 전달받은 attachment_id를 사용하여 특정 채팅방에 첨부파일 메시지를 전송

messages.send

특정 채팅방에 새로운 메시지를 전송합니다.

Request

Request Syntax

코드예제messages.send Request Syntax

curl -X POST https://api.kakaowork.com/v1/messages.send \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{"conversation_id":"1","text":"카카오워크에 오신걸 환영합니다.","blocks":[{"type":"text","text":"카카오워크에 오신걸 환영합니다.","inlines":[{"type":"styled","text":"카카오워크에 "},{"type":"styled","text":"오신걸 ","bold":true},{"type":"styled","text":" 환영합니다.","color":"red"}]}]}'

API 요청 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/messages.send

Request Header

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

messages.send Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 필수 application/json

주의
카카오워크 API 호출 방식은 application/jsonapplication/x-www-form-urlencoded의 형식을 지원하고 있습니다.

  • 단, Messages API의 경우에는 application/json 형식만 허용합니다.

Request Elements

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

messages.send Request Elements
파라미터 타입 필수 여부 설명
conversation_id String 필수 메시지를 전송할 채팅방의 ID
text String 필수 전송할 채팅 메시지
- 일반 텍스트 메시지를 전달할 때 사용
- 메시지를 text 형식이 아닌 blocks로 정의했을 때, 푸시 알림과 채팅방 목록과 같이 조합형 말풍선 메시지가 사용될 수 없는 경우에 활용되는 대체(Fallback) 메시지
- 메시지 최대 길이는 10,000자 이하
blocks Object[] 선택 조합형 말풍선 메시지를 전달할 때 사용
- Block Kit 구성 및 정책 문서 참고

Response

Response Syntax

코드예제messages.send Response Syntax

{
  "message": {
    "blocks": [
      {
        "type": "text",
        "text": "카카오워크에 오신걸 환영합니다.",
        "inlines": [
          {
            "type": "styled",
            "text": "카카오워크에 "
          },
          {
            "type": "styled",
            "text": "오신걸 ",
            "bold": true
          },
          {
            "type": "styled",
            "text": " 환영합니다.",
            "color": "red"
          }
        ]
      }
    ],
    "conversation_id": "1",
    "id": "777",
    "send_time": 1633001838,
    "text": "카카오워크에 오신걸 환영합니다.",
    "update_time": 1633001838,
    "user_id": "1"
  },
  "success": true
}

Response Elements

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

messages.send Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, message 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object 선택 전송된 메시지 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅 메시지 ID
text String 필수 기본 텍스트 메시지
user_id Integer 필수 메시지를 받은 사용자의 ID
conversation_id String 필수 메시지가 작성된 채팅방 ID
send_time Timestamp 필수 메시지가 전송된 시각
update_time Timestamp 필수 메시지가 변경된 시각
blocks Object[] 선택 블록 요소의 목록
- Block Kit 구성 및 정책 참고
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
message String 필수 오류 원인에 대한 설명
code String 필수 오류 상황을 구분하는 코드
invalid_parameter:
제공된 파라미터의 값이 올바르지 않음
invalid_authentication:
제공된 인증키가 유효하지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음

messages.send_by_email

이메일(Email) 주소를 통해 특정 사용자를 찾고, 해당 사용자와의 1:1 채팅방에 메시지를 전송합니다.

Request

Request Syntax

코드예제messages.send_by_email Request Syntax

  curl -X POST https://api.kakaowork.com/v1/messages.send_by_email \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{ "email": "{메시지를 수신할 사용자의 인증된 email 주소}", "text": "{전송할 채팅 메시지}" }'

API 요청 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/messages.send_by_email

Request Header

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

messages.send_by_email Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 필수 application/json

주의
카카오워크 API 호출 방식은 application/jsonapplication/x-www-form-urlencoded의 형식을 지원하고 있습니다.

  • 단, Messages API의 경우에는 application/json 형식만 허용합니다.

Request Elements

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

messages.send_by_email Request Elements
파라미터 타입 필수 여부 설명
email String 필수 메시지를 수신할 사용자의 인증된 email 주소
text String 필수 전송할 채팅 메시지
- 일반 텍스트 메시지를 전달할 때 사용
- 메시지를 text 형식이 아닌 blocks로 정의했을 때, 푸시 알림과 채팅방 목록과 같이 조합형 말풍선 메시지가 사용될 수 없는 경우에 활용되는 대체(Fallback) 메시지
- 메시지 최대 길이는 10,000자 이하
blocks Object[] 선택 조합형 말풍선 메시지를 전달할 때 사용
- Block Kit 구성 및 정책 문서 참고

Response

Response Syntax

코드예제messages.send_by_email Response Syntax

{
  "message": {
    "blocks": [
      {
        "markdown": true,
        "text": "카카오워크에 오신걸 환영합니다.",
        "type": "text"
      }
    ],
    "conversation_id": "1",
    "id": "777",
    "send_time": 1633001838,
    "text": "카카오워크에 오신걸 환영합니다.",
    "update_time": 1633001838,
    "user_id": 1
  },
  "success": true
}

Response Elements

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

messages.send_by_email Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, message필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object 선택 전송된 메시지 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅 메시지 ID
text String 필수 기본 텍스트 메시지
user_id Integer 필수 메시지를 받은 사용자의 ID
conversation_id String 필수 메시지가 작성된 채팅방 ID
send_time Timestamp 필수 메시지가 전송된 시각
update_time Timestamp 필수 메시지가 변경된 시각
blocks Object[] 선택 블록 요소의 목록
- Block Kit 구성 및 정책 문서 참고
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
message String 필수 오류 원인에 대한 설명
code String 필수 오류 상황을 구분하는 코드
invalid_parameter:
제공된 파라미터의 값이 올바르지 않음
invalid_authentication:
제공된 인증키가 유효하지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음

messages.send_by

파라미터로 전달된 이메일(Email) 또는 Key 값에 해당하는 사용자를 찾고, 해당 사용자와의 1:1 채팅방에 메시지를 전송합니다.

Request

Request Syntax

코드예제messages.send_by Request Syntax

curl -X POST https://api.kakaowork.com/v1/messages.send_by \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{ "email": "{메시지를 수신할 사용자의 인증된 email 주소}", "key": "{메시지를 수신할 사용자의 인증된 display_identifier 값}", "text": "Hello" }'

API 요청 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/messages.send_by

Request Header

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

messages.send_by Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 필수 application/json

주의
카카오워크 API 호출 방식은 application/jsonapplication/x-www-form-urlencoded의 형식을 지원하고 있습니다.

  • 단, Messages API의 경우에는 application/json 형식만 허용합니다.

Request Elements

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

messages.send_by Request Elements
파라미터 타입 필수 여부 설명
email String 선택 메시지를 수신할 사용자의 인증된 email 주소
key String 선택 메시지를 수신할 사용자의 인증된 display_identifier 값
text String 필수 전송할 채팅 메시지
- 일반 텍스트 메시지를 전달할 때 사용
- 메시지를 text 형식이 아닌 blocks로 정의했을 때, 푸시 알림과 채팅방 목록과 같이 조합형 말풍선 메시지가 사용될 수 없는 경우에 활용되는 대체(Fallback) 메시지
- 메시지 최대 길이는 10,000자 이하
blocks Object[] 선택 조합형 말풍선 메시지를 전달할 때 사용
- Block Kit 구성 및 정책 문서 참고
안내
요청 시, email 값과 key 값 중 한 개는 반드시 값이 존재해야 합니다.

Response

Response Syntax

코드예제messages.send_by Response Syntax

{
  "message": {
    "blocks": [
      {
        "markdown": true,
        "text": "카카오워크에 오신걸 환영합니다.",
        "type": "text"
      }
    ],
    "conversation_id": "1",
    "id": "777",
    "send_time": 1633001838,
    "text": "카카오워크에 오신걸 환영합니다.",
    "update_time": 1633001838,
    "user_id": 1
  },
  "success": true
}

Response Elements

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

messages.send_by Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, message필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object 선택 전송된 메시지 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅 메시지 ID
text String 필수 기본 텍스트 메시지
user_id Integer 필수 메시지를 받은 사용자의 ID
conversation_id String 필수 메시지가 작성된 채팅방 ID
send_time Timestamp 필수 메시지가 전송된 시각
update_time Timestamp 필수 메시지가 변경된 시각
blocks Object[] 선택 블록 요소의 목록
- Block Kit 구성 및 정책 문서 참고
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
message String 필수 오류 원인에 대한 설명
code String 필수 오류 상황을 구분하는 코드
invalid_parameter:
제공된 파라미터의 값이 올바르지 않음
invalid_authentication:
제공된 인증키가 유효하지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음

messages.send_attachments

conversations.upload 통해 전달받은 attachment_id를 사용하여 특정 채팅방에 첨부파일 메시지를 전송합니다.

Request

Request Syntax

이미지 메시지 전송의 경우

코드예제messages.send_attachments 이미지 전송 Request Syntax

curl -X POST https://api.kakaowork.com/v1/messages.send_attachments \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
   "conversation_id": 1,
   "type": "image",
	"attachment": 
      {	
			"attachment_ids": [1,2,3,4,5]
		}
   }'

파일 메시지 전송의 경우

코드예제messages.send_attachments 파일 전송 Request Syntax

curl -X POST https://api.kakaowork.com/v1/messages.send_attachments \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
   "conversation_id": 1,
   "type": "file",
	"attachment": 
      {	
			"attachment_id": 1
		}
   }'

동영상 메시지 전송의 경우

코드예제messages.send_attachments 동영상 전송 Request Syntax

curl -X POST https://api.kakaowork.com/v1/messages.send_attachments \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
   "conversation_id": 1,
   "type": "video",
	"attachment": 
      {			
			"attachment_id": 1,
         "thumbnail_attachment_id": 2
		}
   }'

API 요청 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/messages.send_attachments

Request Header

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

messages.send_attachments Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 필수 application/json

주의
카카오워크 API 호출 방식은 application/jsonapplication/x-www-form-urlencoded의 형식을 지원하고 있습니다.

  • 단, Messages API의 경우에는 application/json 형식만 허용합니다.

Request Elements

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

messages.send_attachments Request Elements
파라미터 타입 필수 여부 설명
conversation_id String 필수 메시지를 전송할 채팅방의 ID
type String 필수 첨부파일 메시지 Type
image: 이미지
file: 파일
video: 동영상
Object 필수 메세지를 전송할 첨부파일 정보
attachment_ids Long[] 필수 이미지 첨부파일 ID 리스트
- image일때만 필수
attachment_id Long 필수 파일 혹은 동영상 첨부파일 ID
- file or video일때만 필수
thumbnail_attachment_id Long 선택 동영상 썸네일 이미지 ID
- video일 때 사용, 없으면 file 형식으로 메세지 전송
안내
type이 image인 경우, attachment_ids, file 혹은 video인 경우, attachment_id이 반드시 값이 존재해야 합니다.
type이 video인 경우, thumbnail_attachment_id가 없으면 file로 대체됩니다.

Response

Response Syntax

이미지 메시지 전송 응답의 경우 코드예제messages.send_attachments 이미지 메시지 전송 Response Syntax

{
   "message":  {
      "blocks": [
        {
          "file_name": "test_1.png",
          "file_size": 34215,
          "file_url": "http://cloud-kage-sandbox3.k9e.io/dn/QRZAy/hyatNPo23y/LhtTmKNQ35aDepfKalfmwK/img.png",
          "height": 847,
          "id": "731557658721349600",
          "type": "image",
          "width": 537
        },
        {
         "file_name": "image.png",
         "file_size": 6186,
         "file_url": "https://kagedn.kakaoicdn.net/dn/LG4gA/hyU5YSrZ2G/yfYxfPCqMWs0xxGiFiPhvk/img.png",
         "height": 52,
         "id": "736221699251417088",
         "type": "image",
         "width": 197
         }
      ],
      "conversation_id": "10101305",
      "id": "731557740636119000",
      "send_time": 1720717757,
      "update_time": 1720727757,
      "user_id": "10871566",
    }
}

파일 메시지 전송 응답의 경우 코드예제messages.send_attachments 파일 메시지 전송 응답 Response Syntax

{
   "message":  {
      "blocks": [
        {
          "file_name": "file.hwp",
          "file_size": 19456,
          "file_url": "http://cloud-kage-sandbox3.k9e.io/dn/czZOwf/hyatL5aurD/C65C9WbGTAJm5HrTKkzJKk/original.hwp",
          "id": "731560186309603300",
          "type": "file",
        }
      ],
      "conversation_id": "10101305",
      "id": "731560550547169300",
      "send_time": 1720718426,
      "update_time": 1720728426,
      "user_id": "10871566",
    }
}

동영상 메시지 전송 응답의 경우 코드예제messages.send_attachments 동영상 메시지 전송 응답 Response Syntax

{
   "message":  {
      "blocks": [
        {
          "duration": 60,
          "file_name": "test_3.mp4",
          "file_size": 4947870,
          "file_url": "http://cloud-kage-sandbox3.k9e.io/dn/esatSt/hyatKZudY6/vca0Z3OLoL4yHyxsz0fMe1/original.mp4",
          "height": 200,
          "id": 731561420395487200,
          "rotation": 0,
          "thumbnail": {
            "file_name": "test_4.jpg",
            "file_size": 3737209,
            "file_url": "http://cloud-kage-sandbox3.k9e.io/dn/vK9DM/hyatP7usD2/xmL0zCVKiZ0I9FHW7KB5h1/img.jpg",
            "height": 4000,
            "id": 731561426078769200,
            "type": "image",
            "width": 3000
          },
          "type": "video",
          "width": 100
        }
      ],
      "conversation_id": "10101305",
      "id": "731560550547169300",
      "send_time": 1633001838,
      "update_time": 1633011838,
      "user_id": "10871566",
    }
}

Response Elements

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

messages.send_by Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, message필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object 선택 전송된 메시지 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅 메시지 ID
user_id String 필수 메시지를 받은 사용자의 ID
conversation_id String 필수 메시지가 작성된 채팅방 ID
send_time Timestamp 필수 메시지가 전송된 시각
update_time Timestamp 필수 메시지가 변경된 시각
blocks Object[] 필수 첨부파일 요소의 목록
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
message String 필수 오류 원인에 대한 설명
code String 필수 오류 상황을 구분하는 코드
bot_not_found:
APP_KEY가 유효하지 않음
conversation_not_found:
채팅방을 찾을 수 없음
invalid_parameter:
제공된 파라미터의 값이 올바르지 않음
invalid_authentication:
제공된 인증키가 유효하지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
bad_request:
필수 파라미터 관련 오류 발생
internal_server_error:
정의되지 않은 서버 오류 발생
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.