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

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.delegate_host Bot이 방장인 특정 채팅방에서 다른 참여자에게 방장 권한을 위임
conversations.leave Bot을 특정 채팅방에서 나가기 처리

conversations.open

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

채널 기능이 활성화된 워크스페이스에서는 channel_type을 지정하여 공개 채널(public)도 생성할 수 있습니다.

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": "{그룹 채팅방의 이름}" }'

채널의 경우

코드예제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": "{채널의 이름}", "channel_type": "public" }'

표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자
- 그룹 채팅방이 아니거나 공백만 입력 시, 입력한 채팅방명을 무시하고 생성
channel_type String 선택 채널을 생성하는 경우의 채널 유형
- public: 공개 채널(현재 지원되는 유일한 값)
- 지정 시 user_ids 동반 필수
- 채널 기능이 활성화된 워크스페이스에서만 사용 가능

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,
    "channel_type": "none"
  },
  "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의 경우, 설정한 채팅방의 이름을 반환
channel_type String 필수 채팅방/채널의 유형
none: 채널이 아닌 일반 채팅방
public: 공개 채널
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:
채팅방 이름을 규칙에 맞지 않게 입력한 경우
channel_not_supported:
채널 기능이 활성화되지 않은 워크스페이스에서 채널 생성을 요청한 경우
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
파라미터 타입 필수 여부 설명
type String 선택 조회할 채팅방 유형 필터
- all: 채널과 일반 채팅방 전체(기본값)
- channel: 채널만
- normal: 일반 채팅방만
- 채널 기능이 활성화되지 않은 워크스페이스에서는 무시되며 일반 채팅방만 반환
limit String 선택 한 번에 가져올 수 있는 데이터 개수
- 기본값: 10, 최대값: 100
cursor String 선택 다음 API 호출 시에 사용할 페이징 커서(Cursor)
안내
Pagination의 자세한 규칙은 Pagination을 참고하시기 바랍니다.

Response

Response Syntax

코드예제conversations.list Response Syntax 

{
  "conversations": [
    {
      "avatar_url": null,
      "id": "1",
      "name": "공지 채널",
      "type": "group",
      "users_count": 4,
      "channel_type": "public"
    },
    {
      "avatar_url": null,
      "id": "2",
      "name": "test1 (test1.a), test2 (test2.b)",
      "type": "group",
      "users_count": 3,
      "channel_type": "none"
    }
  ],
  "cursor": "Y3Vyc29yX2lkPTEwMDAwMDAwMDE2MiZsaW1pdD0z",
  "success": true
}

Response Elements

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

표conversations.list Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversations와 cursor 필드가 함께 반환
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의 경우, 설정한 채팅방의 이름을 반환
channel_type String 필수 채팅방/채널의 유형
none: 채널이 아닌 일반 채팅방
public: 공개 채널
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,
    "channel_type": "none"
  },
  "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의 경우, 설정한 채팅방의 이름을 반환
channel_type String 필수 채팅방/채널의 유형
none: 채널이 아닌 일반 채팅방
public: 공개 채널
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, rotation은 video일때만 사용, 없으면 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 필수 오류 원인에 대한 설명

conversations.delegate_host

Bot이 방장인 채팅방에서 다른 참여자에게 방장 권한을 위임합니다. 위임 대상은 반드시 해당 채팅방의 참여자여야 합니다.

단체 채팅방(group 타입) 및 채널에서 사용할 수 있으며, dm 등 그 외 타입은 지원하지 않습니다. Bot이 방장인 채팅방을 나가려면 먼저 이 API로 방장 권한을 위임한 후 나가야 합니다.

Request

Request Syntax

코드예제conversations.delegate_host Request Syntax 

  curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/delegate_host \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json;charset=utf-8"  \
   -d '{ "user_id": "{방장을 위임받을 대상 사용자 ID}" }'

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

Request Header

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

표conversations.delegate_host 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.delegate_host Request Elements
파라미터 타입 필수 여부 설명
user_id Integer 필수 방장을 위임받을 대상 사용자 ID
- 해당 채팅방의 참여자여야 함

Response

Response Syntax

코드예제conversations.delegate_host Response Syntax 

{
  "success": true
}

Response Elements

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

표conversations.delegate_host Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: 실패, error 필드와 함께 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
code String 필수 오류 상황을 구분하는 코드
conversation_not_found:
채팅방이 존재하지 않거나 비활성화된 상태
invalid_parameter:
채팅방 타입이 방장 위임을 지원하지 않음
대상 user_id가 해당 채팅방의 참여자가 아님
대상 사용자가 이미 방장임
forbidden:
요청한 Bot이 해당 채팅방의 방장이 아님
invalid_authentication:
제공된 인증키가 유효하지 않음
unauthorized:
인증키가 제공되지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
expired_authentication:
제공된 인증키가 만료됨
missing_parameter:
필요한 파라미터 값이 제공되지 않았음
internal_server_error:
정의되지 않은 서버 오류 발생
invalid_content_type:
요청이 API가 요구하는 Content Type과 다름
message String 필수 오류 원인에 대한 설명

conversations.leave

Bot을 해당 채팅방에서 나가게 합니다.

dm 타입의 채팅방은 실제로 나가지 않고 채팅방 목록에서만 숨김(마스킹) 처리됩니다. 이후 같은 상대와 다시 채팅방을 열면 마스킹이 해제되어 채팅방이 목록에 다시 나타나고, 이전 대화 내용도 그대로 다시 보입니다. 완전한 삭제가 아니므로 민감한 정보가 남을 수 있다는 점에 유의하세요. group, 채널 타입은 실제로 채팅방에서 나가며, 이 때 Bot이 방장인 경우에는 나갈 수 없으므로 먼저 conversations.delegate_host로 방장 권한을 위임한 후 나가야 합니다. im 등 그 외 타입은 지원하지 않습니다.

Request

Request Syntax

코드예제conversations.leave Request Syntax 

  curl -X POST https://api.kakaowork.com/v1/conversations/{conversation_id}/leave \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -H "Content-Type: application/json;charset=utf-8"

표API 호출 방식
메서드 요청 URL
POST https://api.kakaowork.com/v1/conversations/{conversation_id}/leave
표API 호출 방식 Path Parameter
파라미터 타입 필수여부 설명
conversation_id Integer 필수 Bot이 나갈 채팅방 고유 아이디

Request Header

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

표conversations.leave 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

요구하는 파라미터가 없습니다.

Response

Response Syntax

코드예제conversations.leave Response Syntax 

{
  "success": true
}

Response Elements

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

표conversations.leave Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: 실패, error 필드와 함께 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
code String 필수 오류 상황을 구분하는 코드
conversation_not_found:
채팅방이 존재하지 않거나 비활성화된 상태
forbidden:
Bot이 방장이라 나갈 수 없음(group, 채널 타입)
invalid_parameter:
나가기를 지원하지 않는 채팅방 타입
invalid_authentication:
제공된 인증키가 유효하지 않음
unauthorized:
인증키가 제공되지 않음
api_not_found:
요청 API의 URL 혹은 HTTP 메서드와 다름
expired_authentication:
제공된 인증키가 만료됨
internal_server_error:
정의되지 않은 서버 오류 발생
message String 필수 오류 원인에 대한 설명
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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