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

페이지 이동경로

Conversations

채팅방을 생성하기 위해 다음과 같은 API를 사용합니다.

Conversations API 리스트
API 명 설명
conversations.open Bot과 멤버 간 채팅방 생성
conversations.list Bot이 생성한 채팅방 조회
conversations.users Bot이 생성한 채팅방에 있는 사용자 목록 조회
conversations.invite Bot이 생성한 특정 채팅방에 사용자를 초대
conversations.kick Bot이 생성한 특정 채팅방에 있는 사용자를 내보내기
conversations.edit Bot이 생성한 단체 채팅방(group 타입)의 설정 변경
conversations.upload Bot이 생성한 특정 채팅방에 첨부파일 전송을 위한 사전 업로드

conversations.open

Bot과 멤버 간 1:1(일대일) 또는 그룹 채팅방을 생성합니다. 1:1 채팅방의 경우 이미 채팅방이 생성되어 있으면, 채팅방을 새로 시작하지 않고 해당 채팅방의 정보를 반환합니다.

Request

Request Syntax

1:1 채팅방의 경우

코드예제conversation.open 1:1 채팅방 Request Syntax

  curl -X POST https://api.kakaowork.com/v1/conversations.open \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{ "user_id": {채팅 상대방의 사용자 ID} }'

그룹 채팅방의 경우

코드예제conversation.open 그룹 채팅방 Request Syntax

  curl -X POST https://api.kakaowork.com/v1/conversations.open \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json" \
   -d '{ "user_ids": [{채팅 상대방의 사용자 ID}, ...], "conversation_name": "{그룹 채팅방의 이름}" }'

API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations.open

Request Header

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

conversations.open Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Request Elements

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

주의
반드시 user_id 또는 user_ids 둘 중 하나만 설정되어야 합니다.

  • 두 개의 값이 모두 설정된 경우는 실패(invalid_parameter)로 처리합니다.
conversations.open Request Elements
파라미터 타입 필수 여부 설명
user_id Integer 선택 멤버의 고유 ID
- 특정 멤버와 1:1 채팅방을 생성하는 경우 사용
user_ids Integer[] 선택 채팅방에 참여하고자 하는 멤버의 고유 ID 리스트
- 그룹 채팅방을 생성하는 경우 사용
conversation_name String 선택 그룹 채팅방을 생성하는 경우 그룹 채팅방의 이름
- 최대 60자
- 그룹 채팅방이 아니거나 공백만 입력 시, 입력한 채팅방명을 무시하고 생성

Response

Response Syntax

코드예제conversations.open Response Syntax

{
  "conversation": {
    "avatar_url": null,
    "id": "1",
    "name": "test1 (test1.a), test2 (test2.b), test3 (test3.c)",
    "type": "group",
    "users_count": 4
  },
  "success": true
}

Response Elements

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

conversations.open Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversation 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object 선택 개설된 채팅방 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅방 ID
type String 필수 채팅방의 종류를 구분
dm: 일대일(1:1) 채팅방
group: 그룹 채팅방
users_count Integer 필수 개설된 채팅방에 참여 중인 Bot과 멤버 수의 합
avatar_url String 선택 채팅방 이미지 URL
dm의 경우, 상대방의 프로필 이미지를 반환
group의 경우, 대표 이미지 URL을 반환
name String 선택 채팅방의 이름
dm의 경우, 상대방의 이름을 반환
group의 경우, 설정한 채팅방의 이름을 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
bad_request:
채팅방 이름을 규칙에 맞지 않게 입력한 경우
message String 필수 오류 원인에 대한 설명

conversations.list

Bot이 생성한 채팅방 리스트를 조회합니다.

Request

Request Syntax

코드예제conversations.list Request Syntax

  curl -X GET https://api.kakaowork.com/v1/conversations.list \
   -H "Authorization: Bearer {YOUR_APP_KEY}"

API 호출 방식
메서드 요청 URL
GET https://api.kakaowork.com/v1/conversations.list

Request Header

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

conversations.list Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Request Elements

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

conversations.list Request Elements
파라미터 타입 필수 여부 설명
limit String 선택 한 번에 가져올 수 있는 데이터 개수
- 기본값: 10, 최대값: 100
cursor String 선택 다음 API 호출 시에 사용할 페이징 커서(Cursor)
안내
Pagination의 자세한 규칙은 Pagination을 참고하시기 바랍니다.

Response

Response Syntax

코드예제conversations.list Response Syntax

{
  "conversations": [
    {
      "avatar_url": null,
      "id": "1",
      "name": "test1 (test1.a), test2 (test2.b), test3 (test3.c)",
      "type": "group",
      "users_count": 4
    },
    {
      "avatar_url": null,
      "id": "2",
      "name": "test1 (test1.a), test2 (test2.b)",
      "type": "group",
      "users_count": 3
    }
  ],
  "cursor": "Y3Vyc29yX2lkPTEwMDAwMDAwMDE2MiZsaW1pdD0z",
  "success": true
}

Response Elements

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

conversations.list Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversationscursor 필드가 함께 반환
false: 실패, error 필드와 함께 반환
Object[] 선택 개설된 채팅방 정보 리스트
- API 호출 성공(true)일 경우 제공
id String 필수 채팅방 ID
type String 필수 채팅방의 종류를 구분
dm: 일대일(1:1) 채팅방
group: 그룹 채팅방
users_count Integer 필수 개설된 채팅방에 참여 중인 Bot과 멤버 수의 합
avatar_url String 선택 채팅방 이미지 URL
dm의 경우, 상대방의 프로필 이미지를 반환
group의 경우, 대표 이미지 URL을 반환
name String 선택 채팅방의 이름
dm의 경우, 상대방의 이름을 반환
group의 경우, 설정한 채팅방의 이름을 반환
cursor String 선택 다음 API 호출 시에 쓰일 페이징 커서(Cursor)
- API 호출 성공(true)일 경우 제공
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명

conversations.users

Bot이 생성한 특정 채팅방에 참여한 사용자 리스트를 조회합니다.

Request

Request Syntax

코드예제conversations.users Request Syntax

  curl -X GET https://api.kakaowork.com/v1/conversations/{conversation_id}/users \
   -H "Authorization: Bearer {YOUR_APP_KEY}"

API 호출 방식
메서드 요청 URL
GET https://api.kakaowork.com/v1/conversations/{conversation_id}/users
API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 조회하려는 채팅방 고유 아이디

Request Header

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

conversations.users Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Response

Response Syntax

코드예제conversations.users Response Syntax

{
        "success": true,
        "users": [
                {
                        "avatar_url": "http://test.avatar.com/img1.jpg",
                        "department": "test팀",
                        "display_name": "test1 (test1.a)",
                        "id": "1",
                        "name": "test1",
                        "nickname": "test1.a",
                        "position": "대리",
                        "responsibility": "팀장",
                        "space_id": "1",
                        "vacation_end_time": null,
                        "vacation_start_time": null,
                        "work_end_time": 1622687365,
                        "work_start_time": 1622509200
                },
                {
                        "avatar_url": "http://test.avatar.com/img2.jpg",
                        "department": "test팀",
                        "display_name": "test2 (test2.b)",
                        "id": "2",
                        "name": "test2",
                        "nickname": "test2.b",
                        "position": "대리",
                        "responsibility": "팀원",
                        "space_id": "1",
                        "vacation_end_time": 1622687365,
                        "vacation_start_time": 1622509200,
                        "work_end_time": null,
                        "work_start_time": null
                },
                {
                        "avatar_url": "http://test.avatar.com/img3.jpg",
                        "department": null,
                        "display_name": "test3 (test3.c)",
                        "id": "3",
                        "name": "test3",
                        "nickname": "test3.c",
                        "position": null,
                        "responsibility": null,
                        "space_id": "1",
                        "vacation_end_time": null,
                        "vacation_start_time": null,
                        "work_end_time": null,
                        "work_start_time": null
                }, ...
        ]
}

Response Elements

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

conversations.users Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, users 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object[] 선택 채팅방에 참여중인 사용자 리스트
- API 호출 성공(true)일 경우 제공
id String 필수 멤버의 ID
space_id String 필수 멤버가 속한 워크스페이스의 ID
name String 필수 멤버의 이름
nickname String 선택 멤버의 닉네임
- null: 어드민이 닉네임 사용을 허용하지 않은 경우
avatar_url String 선택 멤버의 프로필 사진 URL
department String 선택 부서명
position String 선택 직급명
- null: 어드민이 닉네임 사용을 허용하지 않은 경우
responsibility String 선택 직책명
- null: 어드민이 닉네임 사용을 허용하지 않은 경우
work_start_time Timestamp 선택 근무 시작 시각(Unix time 값)
work_end_time Timestamp 선택 근무 종료 시각(Unix time 값)
vacation_start_time Timestamp 선택 휴가 시작 시각(Unix time 값)
vacation_end_time Timestamp 선택 휴가 종료 시각(Unix time 값)
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명

conversations.invite

Bot이 생성한 특정 그룹 채팅방에 사용자를 초대합니다. 단 대화방 생성시 사용자와의 1:1 대화방으로 생성한 경우에는 다른 사용자를 초대할 수 없습니다.

Request

Request Syntax

코드예제conversations.invite Request Syntax

  curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/invite \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json;charset=utf-8"  \
   -d '{ "user_ids": "{채팅방에 초대할 상대방 사용자 ID 리스트}" }'

API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations/{conversation_id}/invite
API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 사용자를 초대할 채팅방 고유 아이디

Request Header

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

conversations.invite Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Request Elements

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

conversations.invite Request Elements
파라미터 타입 필수 여부 설명
user_ids Integer[] 필수 채팅방에 초대할 사용자 ID 리스트

Response

Response Syntax

코드예제conversations.invite Response Syntax

{
  "conversation": {
    "avatar_url": null,
    "id": "1",
    "name": "test1 (test1.a), test2 (test2.b), test3 (test3.c)",
    "type": "group",
    "users_count": 4
  },
  "success": true
}

Response Elements

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

conversations.invite Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: 실패, error 필드와 함께 반환
Object 선택 개설된 채팅방 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅방 ID
type String 필수 채팅방의 종류를 구분
dm: 일대일(1:1) 채팅방
group: 그룹 채팅방
users_count Integer 필수 개설된 채팅방에 참여 중인 Bot과 멤버 수의 합
avatar_url String 선택 채팅방 이미지 URL
dm의 경우, 상대방의 프로필 이미지를 반환
group의 경우, 대표 이미지 URL을 반환
name String 선택 채팅방의 이름
dm의 경우, 상대방의 이름을 반환
group의 경우, 설정한 채팅방의 이름을 반환
cursor String 선택 다음 API 호출 시에 사용할 페이징 커서
- API 호출 성공(true)일 경우 제공
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명

conversations.kick

Bot이 생성한 특정 그룹 채팅방에 있는 사용자를 내보냅니다. 단 대화방 생성시 사용자와의 1:1 채팅방으로 생성한 대화방은 사용자를 내보내기할 수 없습니다.

주의
Bot 유저를 제외한 나머지 사용자가 모두 나가면 채팅방은 자동적으로 삭제처리되어 더 이상 접근할 수 없습니다.

Request

Request Syntax

코드예제conversations.kick Request Syntax

  curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/kick \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json;charset=utf-8"  \
   -d '{ "user_ids": "{채팅방에서 내보내기 처리할 사용자 ID 리스트}" }'

API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations/{conversation_id}/kick
API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 사용자를 내보내기 처리할 채팅방 고유 아이디

Request Header

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

conversations.kick Request Header
파라미터 타입 필수 여부 설명
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Request Elements

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

conversations.kick Request Elements
파라미터 타입 필수 여부 설명
user_ids Integer[] 필수 채팅방에서 내보내기 처리할 사용자 ID 리스트

Response

Response Syntax

코드예제conversations.kick Response Syntax

{
  "conversation": {
    "avatar_url": null,
    "id": "1",
    "name": "test1 (test1.a), test2 (test2.b), test3 (test3.c)",
    "type": "group",
    "users_count": 4
  },
  "success": true
}

Response Elements

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

conversations.kick Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: 실패, error 필드와 함께 반환
Object 선택 개설된 채팅방 정보
- API 호출 성공(true)일 경우 제공
id String 필수 채팅방 ID
type String 필수 채팅방의 종류를 구분
dm: 일대일(1:1) 채팅방
group: 그룹 채팅방
users_count Integer 필수 개설된 채팅방에 참여 중인 Bot과 멤버 수의 합
avatar_url String 선택 채팅방 이미지 URL
dm의 경우, 상대방의 프로필 이미지를 반환
group의 경우, 대표 이미지 URL을 반환
name String 선택 채팅방의 이름
dm의 경우, 상대방의 이름을 반환
group의 경우, 설정한 채팅방의 이름을 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명

conversations.edit

이 API는 Bot이 생성한 단체 채팅방(group 타입)의 설정을 변경합니다. 변경 범위는 ‘채팅방 이름’과 ‘구성원들의 초대 허용 여부’입니다. 이 API는 단체 채팅방의 설정만 변경하며, 1:1 대화방의 설정은 변경할 수 없습니다.

Request

Request Syntax

코드예제conversations.edit Request Syntax

curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/edit \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json;charset=utf-8"  \
   -d '{"name": "{변경할 채팅방 이름}", "allow_invite": false}'

API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations/{conversation_id}/edit
API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 설정을 변경할 채팅방의 고유 아이디

Request Header

파라미터 타입 필수여부 설명
Authorization String 필수 Bearer {YOUR_APP_KEY}
- {YOUR_APP_KEY}: Bot 등록 요청 후에 획득한 인증키(App Key)
Content-Type String 선택 application/json 또는 application/x-www-form-urlencoded

Request Elements

파라미터 타입 필수여부 설명
name String 선택 변경할 채팅방 이름
- “”일 경우 채팅방 이름을 변경하지 않음
- 채팅방 이름은 최대 60자로 제한
allow_invite Boolean 선택 구성원들이 다른 구성원을 초대할 수 있는지 허용 여부
true: 초대 허용
false: 초대를 허용하지 않음

Response

Response Syntax

코드예제conversations.edit Response Syntax

{
  "conversation": {
    "avatar_url": null,
    "id": "1",
    "name": "test1 (test1.a), test2 (test2.b), test3 (test3.c)",
    "type": "group",
    "allow_invite": true,
    "users_count": 4
  },
  "success": true
}

Response Elements

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

필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversation 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object[] 선택 개설된 채팅방 정보
- API 호출 성공(true)일 경우 제공
avatar_url String 선택 채팅방 이미지 URL
dm의 경우, 상대방의 프로필 이미지를 반환
group의 경우, 대표 이미지 URL을 반환
id String 필수 채팅방 ID
name String 선택 채팅방의 이름
dm의 경우, 상대방의 이름을 반환
group의 경우, 설정한 채팅방의 이름을 반환
type String 필수 채팅방의 종류를 구분
dm: 일대일(1:1) 채팅방
group: 그룹 채팅방
allow_invite Boolean 선택 채팅방의 구성원이 다른 사용자를 초대할 수 있는지 여부
-true: 구성원이 다른 사용자 초대 가능
-false: 봇을 제외한 대화상대 초대 불가
users_count Integer 필수 개설된 채팅방에 참여 중인 Bot과 멤버 수의 합
cursor String 선택 다음 API 호출시에 쓰일 페이징 커서
- API 호출 성공(true)일 경우 제공
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명

conversations.upload

이 API는 Bot이 생성한 특정 채팅방에 첨부파일 전송을 위해 파일을 업로드 합니다. 메시지 작성을 위해서는 업로드 이후 메시지 작성 API(messages/send_attachments)를 다시 호출하여야 합니다.

Request

Request Syntax

코드예제conversations.upload Request Syntax

curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/upload \
--header 'Authorization: Bearer {YOUR_APP_KEY}' \
--header 'Content-Type: multipart/form-data' \
--form 'metas="[{\"file_name\": \"test_3.mp4\", \"file_type\": \"video\", \"file_size\": 1024854, \"duration\": 60, \"width\": 300, \"height\": 200, \"rotation\": 0},{\"file_name\": \"test_4.jpg\", \"file_type\": \"image\", \"file_size\":1024}]"' \
--form 'attachments[]=@"/Users/test_3.mp4"' \
--form 'attachments[]=@"/Users/test_4.jpg"'

API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations/{conversation_id}/upload
API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 설정을 변경할 채팅방의 고유 아이디

Request Header

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

Request Elements

파라미터 타입 필수여부 설명
attachments[] Binary[] 필수 첨부파일 목록
image
- 지원 확장자: png jpg jpeg gif bmp
-허용 사이즈: 15mb
file
- 지원 확장자: 전체 허용
-허용 사이즈: 약 1GB (실제 1.05GB)
video
- 지원 확장자: png mp4 m4v avi asf wmv mkv ts mpg mpeg mov flv ogv
-허용 사이즈: 300mb
Object[] 필수 첨부파일들 메타 정보
file_name String 필수 확장자 포함한 파일명
file_type String 필수 업로드 형식
image: 이미지
file: 파일
video: 동영상
file_size Long 필수 바이트 단위 파일 사이즈
duration Long 선택 동영상 길이(단위 초) -video일때만 사용
- 없으면 file로 대체
width Long 선택 동영상 넓이 크기(픽셀 단위) -video일때만 사용
- 없으면 file로 대체
height Long 선택 동영상 높이 크기(픽셀 단위) -video일때만 사용
- 없으면 file로 대체
rotation Integer 선택 비디오 시계방향 기준 회전 각도 -video일때만 사용
- 없으면 file로 대체
안내
duration, width, height, rotationvideo일때만 사용, 없으면 file로 대체됩니다
최대 업로드 가능한 파일 수는 5개, 총 약 1GB (실제 1.05GB)까지입니다.
파일 순서에 맞게 metas 정보를 입력해야 합니다
주의
1시간 이상 메시지에 첨부되지 않은 파일은 사용되지 않는 파일로 간주하여 삭제 처리합니다.

Response

Response Syntax

코드예제conversations.upload Response Syntax

{
  "attachments": [
    {
      "attachment_id": 731530924668067840,
      "file_name": "test_1.mp4",
      "url": "http://cloud-kage-sandbox3.k9e.io/dn/C0tbi/hyatPsSfdq/QKA6twEbs1atDvjkfI8NL1/original.mp4",
      "access_key": "C0tbi/hyatPsSfdq/QKA6twEbs1atDvjkfI8NL1"
    },
    {
      "attachment_id": 731530930460401664,
      "file_name": "test_2.jpg",
      "url": "http://cloud-kage-sandbox3.k9e.io/dn/bxOhKV/hyatL5atRC/c2x4k45LybriZcpVfu1SpK/img.jpg",
      "access_key": "bxOhKV/hyatL5atRC/c2x4k45LybriZcpVfu1SpK"
    },
    {
      "attachment_id": 731531724425359360,
      "file_name": "test_3.hwp",
      "url": "http://cloud-kage-sandbox3.k9e.io/dn/bstw9R/hyatQeeqFc/j9kIJ9u3DpD8VECMhHKsSk/original.hwp",
      "access_key": "bstw9R/hyatQeeqFc/j9kIJ9u3DpD8VECMhHKsSk"
    }
  ],
  "success": true
}

Response Elements

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

필드 타입 필수여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversation 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object[] 필수 업로드된 첨부파일 정보
- API 호출 성공(true)일 경우 제공
attachment_id Long 필수 첨부파일 ID
url String 필수 업로드된 첨부파일 URL
file_name String 필수 업로드된 첨부파일명
access_key String 필수 업로드된 첨부파일의 access key
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
code String 필수 오류 상황을 구분하는 코드
bot_not_found:
APP_KEY가 유효하지 않음
conversation_not_found:
채팅방을 찾을 수 없음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
unauthorized:
인증키가 제공되지 않음
bad_request:
필수 파라미터 관련 오류 발생
internal_server_error:
정의되지 않은 서버 오류 발생
expired_authentication:
제공된 인증키가 만료됨
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
missing_parameter:
필요한 파라미터 값이 제공되지 않았음
message String 필수 오류 원인에 대한 설명
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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