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": "{그룹 채팅방의 이름}" }'
메서드 | 요청 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에 대한 상세는 다음과 같습니다.
표conversations.open Request Elements주의
반드시user_id
또는user_ids
둘 중 하나만 설정되어야 합니다.
- 두 개의 값이 모두 설정된 경우는 실패(
invalid_parameter
)로 처리합니다.
파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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}"
메서드 | 요청 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 : 성공, 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 의 경우, 설정한 채팅방의 이름을 반환 |
|||
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}"
메서드 | 요청 URL |
---|---|
GET | https://api.kakaowork.com/v1/conversations/{conversation_id}/users |
파라미터 | 타입 | 필수여부 | 설명 |
---|---|---|---|
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 리스트}" }'
메서드 | 요청 URL |
---|---|
POST | https://api.kakaowork.com/v1/conversations/{conversation_id}/invite |
파라미터 | 타입 | 필수여부 | 설명 |
---|---|---|---|
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 리스트}" }'
메서드 | 요청 URL |
---|---|
POST | https://api.kakaowork.com/v1/conversations/{conversation_id}/kick |
파라미터 | 타입 | 필수여부 | 설명 |
---|---|---|---|
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}'
메서드 | 요청 URL |
---|---|
POST | https://api.kakaowork.com/v1/conversations/{conversation_id}/edit |
파라미터 | 타입 | 필수여부 | 설명 |
---|---|---|---|
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"'
메서드 | 요청 URL |
---|---|
POST | https://api.kakaowork.com/v1/conversations/{conversation_id}/upload |
파라미터 | 타입 | 필수여부 | 설명 |
---|---|---|---|
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 | 필수 |
오류 원인에 대한 설명 |