API 공통 가이드

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

API Request

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

API 호출 방식

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

안내
카카오워크 API 호출 방식은 두 가지를 모두 허용하지만, 복잡한 데이터를 전달받아야 하는 API들은 application/json으로 표현된 데이터만 허용합니다.

코드예제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 호출 성공 응답

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

공통 Error

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

코드예제API 호출 실패 응답

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

필드 타입 표기

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

Pagination

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

기본 규칙

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

• 목록이 빈 배열일 경우
• cursor가 null일 경우

첫 번째 호출

목록 조회 단위인 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 정보가 포함됩니다.

응답 예시

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..."
  }