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.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}, ...] }'

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 리스트
- 그룹 채팅방을 생성하는 경우 사용

Response

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:
제공된 인증키가 유효하지 않음
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
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 Elements

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

conversations.list Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, conversationcursor 필드가 함께 반환
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:
제공된 인증키가 유효하지 않음
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:
필요한 파라미터 값이 제공되지 않았음
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

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

Request Elements

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

conversations.users Request Elements
파라미터 타입 필수 여부 설명
conversation_id Integer 필수 조회하려고 하는 채팅방 고유 아이디

Response

Response Elements

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

conversations.users Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, users 필드와 함께 반환
false: 실패, error 필드와 함께 반환
Object[] 선택 채팅방에 참여중인 사용자 리스트
- API 호출 성공(true)일 경우 제공
id Integer 필수 멤버의 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:
제공된 인증키가 유효하지 않음
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:
필요한 파라미터 값이 제공되지 않았음
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

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
파라미터 타입 필수 여부 설명
conversation_id Integer 필수 사용자를 초대할 채팅방 고유 아이디
user_ids Integer[] 필수 채팅방에 초대할 사용자 ID 리스트

Response

Response Elements

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

conversations.invite Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: error 필드와 함께 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
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

Request Header

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

conversations.kick 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.kick Request Elements
파라미터 타입 필수 여부 설명
conversation_id Integer 필수 사용자를 내보내기 처리할 채팅방 고유 아이디
user_ids Integer[] 필수 채팅방에서 내보내기 처리할 사용자 ID 리스트

Response

Response Elements

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

conversations.kick Response Elements
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공
false: 실패, error 필드와 함께 반환
Object 선택 API 실행 오류 정보
- API 호출 실패(false)일 경우 제공
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:
필요한 파라미터 값이 제공되지 않았음
user_not_found:
멤버를 찾을 수 없음
message String 필수 오류 원인에 대한 설명
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.