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"}]}]}'
메서드 | 요청 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/json
과application/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": "{전송할 채팅 메시지}" }'
메서드 | 요청 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/json
과application/x-www-form-urlencoded
의 형식을 지원하고 있습니다.
- 단, Messages API의 경우에는
application/json
형식만 허용합니다.
Request Elements
Request Elements에 대한 상세는 다음과 같습니다.
표messages.send_by_email Request Elements파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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" }'
메서드 | 요청 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/json
과application/x-www-form-urlencoded
의 형식을 지원하고 있습니다.
- 단, Messages API의 경우에는
application/json
형식만 허용합니다.
Request Elements
Request Elements에 대한 상세는 다음과 같습니다.
표messages.send_by Request Elements파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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
}
}'
메서드 | 요청 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/json
과application/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 : 필요한 파라미터 값이 제공되지 않았음 |