본문 바로가기 메뉴 바로가기

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

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

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/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) 메시지
- 메시지 최대 길이는 3,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:
제공된 인증키가 유효하지 않음
invalid_representation:
유효하지 않은 포맷의 Body 데이터
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
too_many_requests:
API 사용 한도가 초과됨
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/json과 application/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) 메시지
- 메시지 최대 길이는 3,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:
제공된 인증키가 유효하지 않음
invalid_representation:
유효하지 않은 포맷의 Body 데이터
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
too_many_requests:
API 사용 한도가 초과됨
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/json과 application/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) 메시지
- 메시지 최대 길이는 3,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:
제공된 인증키가 유효하지 않음
invalid_representation:
유효하지 않은 포맷의 Body 데이터
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
internal_server_error:
정의되지 않은 서버 오류 발생
too_many_requests:
API 사용 한도가 초과됨
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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