Kakao Work::Web API 레퍼런스::API 공통 가이드

페이지 이동경로

API 공통 가이드

API 공통 가이드는 카카오워크 Web API를 사용하여 Bot을 개발할 때 미리 알아야 하는 내용을 설명합니다.

API 공통 사항
공통 사항 설명
HTTP/HTTPS 사용 가능 Extension Service API는 HTTP와 HTTPS 프로토콜 모두 사용 가능
API 사용 제한 원활한 카카오워크 서비스 제공을 위하여 과도한 API 사용은 예고 없이 제한될 수 있음
- 구체적인 제한 사항은 추후 확정될 예정
- API 사용에서 지속적인 제한이 발생한다면 호출 빈도를 조절하여 사용 가능

API Request

카카오워크에서 제공하고 있는 API의 요청 URL 형태는 다음과 같습니다. HTTP RPC 스타일의 API 요청(Request)에서는 파라미터를 다음과 같은 방법으로 전달할 수 있습니다.

API 호출 방식

카카오워크 Web API 호출 방식은 일반적으로 아래와 같이 2가지 방식을 모두 허용하지만, 주로 application/json 방식 사용을 선호합니다.

API 호출 방식
메서드 구분 파라미터 전달
GET URL 요청 URL에 표기된 쿼리 파라미터
POST Body Request Body에 application/json으로 표현된 데이터
Request Body에 application/x-www-form-urlencoded로 표현된 데이터
안내
카카오워크 API 호출 방식은 2가지를 모두 허용하지만, 복잡한 데이터를 전달받아야 하는 API들은 application/json으로 표현된 데이터만 허용합니다.
JSON만 허용하는 API
구분 대분류 API 명
Messages - messages.send
- messages.send_by_email
Reactive 반응형 메시지 submit_action
반응형 Modal request_modal
submit_modal

코드예제HTTP 요청 방식

POST /v1/conversations.open
Content-type: application/x-www-form-urlencoded
Authorization: Bearer {YOUR_APP_KEY}

user_id={OPPONENT_USER_ID}
POST /v1/conversations.open
Content-type: application/json
Authorization: Bearer {YOUR_APP_KEY}

{"user_id": {OPPONENT_USER_ID}}

API 인증

카카오워크의 Web API는 Bot 생성 시에 자동으로 부여받은 인증키(App Key)를 HTTP 요청(Request)의 Authorization 헤더를 통해 전달하여 어떤 Bot에서 받은 요청인지 인증 및 권한 검사를 수행합니다.
App Key 발급 및 확인 방법에 대한 자세한 내용은 Bot 시작 가이드를 참고하시기 바랍니다.

코드예제CURL 요청

  curl -X POST https://api.kakaowork.com/v1/conversations.open \
   -H "Authorization: Bearer {YOUR_APP_KEY}" \
   -d "user_id={USER_ID}"

API Response

모든 카카오워크 API 응답(Response)은 아래 테이블과 같은 구조를 갖는 JSON 객체로 표현됩니다. 따라서 Content Type은 application/json으로 고정됩니다.

공통 Response

모든 카카오워크 API 응답은 다음의 구조를 갖는 JSON 객체로 표현됩니다. 호출된 API의 성공 혹은 실패 여부는 success 필드의 값을 통해 확인할 수 있습니다.

  • success 필드 값이 true인 경우에는 API 호출에 문제없이 성공한 것을 의미합니다.
  • success 필드 값이 false인 경우에는 API 호출 실패를 나타냅니다.

공통 Response
필드 타입 필수 여부 설명
success Boolean 필수 API 호출 실행 결과
true: 성공, {entity name} 필드와 함께 반환
false: 실패, error 필드와 함께 반환
{entity name} Any 선택 API 응답(Response) 데이터
- 변수명과 값은 API 종류에 따라 개별 정의됨
- API 호출 성공(true)일 경우 제공
error Object 선택 오류 원인에 대한 설명
- API 호출 실패(false)일 경우 제공

코드예제API 호출 성공 응답

{
  "success": true,
  "user": { /* ... user entity ... */ }
}

공통 Error

API 호출이 실패한 경우, error 필드를 통해 오류에 대해 상세한 정보를 얻을 수 있습니다.

공통 Error
필드 타입 필수 여부 설명
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:
필요한 파라미터 값이 제공되지 않았음
message String 필수 오류 원인에 대한 설명

코드예제API 호출 실패 응답

{
  "success": false,
  "error": {
    "code": "missing_parameter",
    "message": "user_id parameter is missing."
  }
}

필드 타입 표기

API 응답(Response)은 기본적으로 JSON 타입을 따르며, 추가로 확장된 타입은 아래 표| 필드 타입 표기를 따릅니다.

필드 타입 표기
타입 표기 설명
{Type}[] 특정 타입의 값을 요소로 갖는 배열(Array)
- 배열 타입의 값이 없을 때 null이 아닌 빈 배열([])로 표현
   ex) String[]: 문자열(String) 타입의 값을 요소로 갖는 배열(Array)
Timestamp Unix Time(유닉스 시간)으로 표현된 숫자(Number)
- 시각을 표현하는 용도로 사용

Pagination

Pagination이 적용된 목록 조회 API는 아래와 같은 규칙이 적용됩니다.

기본 규칙

API 응답이 아래 두 조건 중 하나라도 충족할 경우, 더 이상 조회할 내용이 없는 것으로 판단합니다.

  • 목록이 빈 배열일 경우
  • cursornull일 경우

첫 번째 호출

목록 조회 단위인 limit를 파라미터로 지정합니다. 파라미터를 지정하지 않으면 API에 정의된 기본값이 사용됩니다.

코드예제첫 번째 호출

# limit=50으로 조회
  curl -X GET https://api.kakaowork.com/v1/users.list?limit=50 

# limit=10으로 조회(기본값)
  curl -X GET https://api.kakaowork.com/v1/users.list 

첫 번째 호출 이후의 모든 호출

바로 이전 API 호출 응답의 cursor만 파라미터로 지정합니다. cursor 외 다른 파라미터를 같이 호출하면, 실패 응답이 반환됩니다.

코드예제첫 번째 호출 이후의 모든 호출

  curl -X GET https://api.kakaowork.com/v1/users.list?cursor={이전 호출의 응답으로 받은 cursor} 

# 호출 값 예시
  curl -X GET https://api.kakaowork.com/v1/users.list?cursor=Y3Vyc29yX2lkPTE1JmxpbWl0PTEw 

API Rate Limit

API Rate Limit는 특정한 시간 내에 호출할 수 있는 API의 제한을 의미하며, 카카오워크에서는 DDoS 공격 예방과 안정적인 서비스 운영을 위해 Rate Limit를 설정하고 있습니다. 1분 동안 API Rate Limit를 초과하는 API 호출이 발생하는 경우에는 해당 요청(Request)이 실패하며, 다음 1분이 되었을 때 호출 요청 횟수가 0으로 갱신됩니다.

Response

Response Header

API Rate Limit는 워크스페이스 단위로 사용량이 정해지며, 모든 응답(Response)에는 다음의 Response Header 정보가 포함됩니다.

Rate Limit 관련 Response Header 정보
파라미터 설명
ratelimit-limit 분당 허용되는 최대 요청 횟수
ratelimit-remaining 잔여 분(minute) 동안 가능한 요청 횟수
ratelimit-reset 시작된 ratelimit 시간 단위가 갱신되는 시간(millisecond)
retry-after 요청 갱신 시간까지 남은 초(second)
- ratelimit를 초과한 경우에만 _code: 429와 함께 반환

응답 예시

API 호출 시 분당 요청이 200회가 넘어가는 경우에는 다음과 같이 정상 응답을 반환하지 않고, _code: 429를 반환합니다.

코드예제응답 예시

  curl -X GET -D - https://api.kakaowork.com/v1/users.list
  HTTP/2 429
  (중략)
  ratelimit-limit: 200
  ratelimit-remaining: 0
  ratelimit-reset: 1624427839
  retry-after: 9

  {
     "documentation_url": "https://docs.kakaoi.ai/kakao_work/",
     "message": "API rate limit exceeded for [\"Bearer 45d9888a.930fa1da90af49419d166cc9bd2e1234\"]. That's antakawork..."
  }

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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