이 문서는 톡캘린더 REST API 사용법을 안내합니다.
캘린더 또는 일정을 지정하기 위해 필요한 캘린더 ID와 일정 ID를 확인하는 방법과 API 호출 순서에 대해 안내합니다.
캘린더 종류 | ID 확인 방법 |
---|---|
기본 캘린더 | primary 로 고정 |
서브 캘린더 | 1. 사용자 캘린더 > 목록 가져오기를 요청해 서브 캘린더 목록 확인 2. 목록 내 캘린더 정보를 참고해 서브 캘린더 ID 확인(서비스가 생성하지 않은 캘린더는 ID만 확인 가능) |
구독 캘린더 | 1. 구독 캘린더 > 구독 가능 캘린더 목록 가져오기를 요청해 구독 가능 캘린더 목록 확인 2. 목록 내 캘린더 정보를 참고해 구독 캘린더 ID 확인 |
일정 종류 | ID 확인 방법 |
---|---|
일반 / 게스트 일정 | 1. 캘린더 ID 확인으로 일정이 등록된 캘린더 ID 확인 2. 확인한 캘린더 ID를 포함해 일반 일정 > 목록 가져오기 요청 3. 목록 내 일정 정보를 참고해 일정 ID 확인 |
공개 일정 | 1. 공개 일정 > 목록 가져오기 요청 2. 목록 내 일정 정보를 참고해 일정 ID 확인 |
아래는 대표적인 톡캘린더 API의 사용 시나리오에 대한 API 호출 순서와, 요청 또는 확인 필요 항목에 대해 안내합니다.
➊ 사용자에게 서비스의 서브 캘린더 추가를 요청하고 승인받습니다. ➋ 사용자 캘린더 > 목록 가져오기를 요청해 사용자의 캘린더 목록을 확인합니다. ➌ 사용자 캘린더 > 생성하기: 서브 캘린더를 요청합니다. ➋에서 확인한 캘린더 ID와 이름을 참고해 사용자 캘린더의 서브 캘린더 생성 조건을 지켜야합니다. ➍ 사용자에게 일반 일정 또는 공개 일정 추가를 요청하고 승인받습니다. ➎ 일반 일정은 일반 일정 > 생성하기를, 공개 일정은 공개 일정 > 사용자 캘린더에 추가하기를 요청합니다.
➊ 사용자에게 서비스의 구독 캘린더 구독을 요청하고 승인받습니다. ➋ 구독 가능 캘린더 목록 가져오기를 요청해 구독 가능 캘린더 목록을 확인합니다. ➌ 구독 캘린더 > 구독하기를 요청합니다. ➋에서 확인한 구독 캘린더 ID를 포함해야 합니다.
카카오톡으로 공개 일정과 구독 캘린더를 전달하는 캘린더 메시지를 보낼 수 있습니다. 사용자는 해당 메시지의 버튼으로 공개 일정을 사용자 캘린더에 추가하거나 구독 캘린더를 구독할 수 있습니다. 자세한 내용은 톡캘린더 메시지를 참고합니다.
캘린더의 목록을 조회하고 관리할 수 있습니다. 캘린더 종류에 대한 설명은 캘린더 구분을 참고합니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/calendars |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자 캘린더의 목록을 가져옵니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 GET
으로 요청합니다. filter
파라미터로 특정 타입의 캘린더 목록만 가져올 수도 있습니다.
요청 성공 시 응답은 캘린더 타입별 목록을 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
filter | String |
목록을 가져올 캘린더 타입, 다음 중 하나:USER : 기본 캘린더, 서브 캘린더SUBSCRIBE : 구독한 구독 캘린더ALL : 전체 사용자 캘린더(기본값) |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendars | Calendar[] |
기본 캘린더, 서브 캘린더 목록 | X |
subscribe_calendars | Subscribe[] |
구독한 구독 캘린더 목록 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
캘린더 ID 기본 캘린더의 경우 primary 로 고정 |
O |
name | String |
캘린더 이름 비고: 서비스에서 만든 캘린더인 경우 필수 |
X |
color | String |
캘린더 일정의 기본 색상, Color 중 하나비고: 서비스에서 만든 캘린더인 경우 필수 |
X |
reminder | Integer |
종일 일정이 아닌 일정의 기본 알림 시간 | X |
reminder_all_day | Integer |
종일 일정의 기본 알림 시간 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
캘린더 ID | O |
name | String |
캘린더 이름 비고: 서비스에서 만든 캘린더인 경우 필수 |
X |
color | String |
캘린더 일정의 기본 색상, Color 중 하나비고: 서비스에서 만든 캘린더인 경우 필수 |
X |
reminder | Integer |
종일 일정이 아닌 일정의 기본 알림 시간 | X |
reminder_all_day | Integer |
종일 일정의 기본 알림 시간 | X |
description | String |
채널에서 설정한 구독 캘린더 설명 | X |
profile_image_url | String |
구독 캘린더의 프로필 이미지 URL | X |
thumbnail_url | String |
구독 캘린더의 말풍선 썸네일 URL | X |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/calendars" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "filter=USER"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendars":[
{
"id":"primary",
},
{
"id":"user_6364dcb910662e4ed8823c96",
"name":"테스트 서브 캘린더",
"color":"ROYAL_BLUE",
"reminder":15,
"reminder_all_day":-540
},
{
"id":"user_6364df33d89d8b4150bbbbc6",
}
],
"subscribe_calendars":[
{
"id":"subscribe_62fc58a57499cb775018baf1",
"name":"테스트 구독 캘린더",
"color":"NAVY_BLUE",
"reminder":15,
"reminder_all_day":-540,
"profile_image_url":"http://t1.kakaocdn.net/calendar/event/700053900/62ce299e2e0c0300b49286cd/banner_mo.gif?831"
},
...
]
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/create/calendar |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자 캘린더에 새로운 서브 캘린더를 생성합니다. 생성한 서브 캘린더에 일반 일정 생성하기 또는 공개 일정 > 사용자 캘린더에 추가하기로 서비스의 일정을 추가할 수 있습니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 파라미터로 생성할 캘린더의 이름, 색상, 일반 일정의 기본 알림 설정값을 지정할 수 있습니다.
요청 성공 시 응답은 생성한 서브 캘린더의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
캘린더 이름 (최대 50자) | O |
color | String |
캘린더 색상, Color 중 하나(기본값: BLUE ) |
X |
reminder | Integer |
종일이 아닌 일정의 기본 알림 설정, 5분 간격으로 설정 가능 | X |
reminder_all_day | Integer |
종일 일정의 기본 알림 설정, 5분 간격으로 설정 가능 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
캘린더 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/create/calendar" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "name=서비스 캘린더" \
-d "color=RED" \
-d "reminder=15" \
-d "reminder_all_day=30"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendar_id": "user_6359e5226b03401878f0f2fe"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/update/calendar |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 특정 서브 캘린더 설정을 수정합니다. 다른 서비스에서 생성한 서브 캘린더는 수정할 수 없습니다. 서비스에서 직접 생성한 서브 캘린더만 수정 가능합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 서브 캘린더의 ID와 1개 이상의 수정할 캘린더 정보를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 수정한 서브 캘린더의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
name
, color
, reminder
, reminder_all_day
중 1개 이상 포함 필요이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
서브 캘린더 ID | O |
name | String |
캘린더 이름 (최대 50자) | X |
color | String |
캘린더 색상, Color 중 하나(기본값: BLUE ) |
X |
reminder | Integer |
종일이 아닌 일정의 기본 알림 설정, 5분 간격으로 설정 가능 | X |
reminder_all_day | Integer |
종일 일정의 기본 알림 설정, 5분 간격으로 설정 가능 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
서브 캘린더 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/calendar" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=user_6359e5226b03401878f0f2fe" \
-d "name=서비스 캘린더 수정" \
-d "color=BLUE" \
-d "reminder=20" \
-d "reminder_all_day=30"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendar_id": "user_6359e5226b03401878f0f2fe"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://kapi.kakao.com/v2/api/calendar/delete/calendar |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 특정 서브 캘린더를 삭제합니다. 다른 서비스에서 생성한 서브 캘린더는 삭제할 수 없습니다. 서비스에서 직접 생성한 서브 캘린더만 삭제 가능합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 DELETE
로 요청합니다. 서브 캘린더의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 삭제한 서브 캘린더의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
서브 캘린더 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
서브 캘린더 ID | O |
curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/delete/calendar" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=user_6359e5226b03401878f0f2fe"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendar_id": "user_6359e5226b03401878f0f2fe"
}
일정 종류에 대한 설명은 일정 구분을 참고합니다.
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/create/event |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 특정 캘린더에 일반 일정을 생성합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 일정을 생성할 캘린더의 ID와 일정 정보를 파라미터에 포함해야 합니다. 기본 캘린더(primary
) 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능합니다. ID를 지정하지 않으면 기본 캘린더에 일정이 생성됩니다.
rrule
파라미터를 포함하면 특정일까지 일정한 주기로 생성되는 반복 일정을, 포함하지 않으면 한 번으로 끝나는 일반 일정을 생성합니다. reminders
파라미터에 빈 리스트를 입력하면, 종일이 아닌 일정의 경우 등록된 캘린더의 reminder
값으로, 종일 일정은 reminder_all_day
값으로 설정됩니다.
요청 성공 시 응답은 생성한 일정의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
일정을 생성할 캘린더 ID(기본값: primary )비고: 기본 캘린더( primary ) 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능 |
X |
event | EventCreate |
생성할 일정 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
일정 제목(최대 50자) | O |
time | Time |
일정 시간 | O |
rrule | String |
일정의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z )주의: 해당 파라미터 포함 시 반복 일정 생성 |
X |
description | String |
일정 설명(최대 5000자) | X |
location | Location |
일정 장소 | X |
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 reminder 값)종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 reminder_all_day 값) |
X |
color | String |
일정 색상, Color 중 하나 (기본값: 해당 캘린더의 color 값) |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
생성한 일정 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/create/event" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=user_63759daa38e1f752188e0cc9" \
-d 'event={
"title": "일정 제목",
"time": {
"start_at": "2022-10-27T03:00:00Z",
"end_at": "2022-10-27T06:00:00Z",
"time_zone": "Asia/Seoul",
"all_day": false,
"lunar": false
},
"rrlue":"FREQ=DAILY;UNTIL=20221031T000000Z",
"description": "일정 설명",
"location": {
"name": "카카오",
"location_id": 18577297,
"address": "경기 성남시 분당구 판교역로 166",
"latitude": 37.39570088983171,
"longitude": 127.1104335101161
},
"reminders": [15, 30],
"color": "RED"
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"63630868d89d8b4150bbb712"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/events |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
특정 캘린더에 등록된 일정 목록을 가져옵니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 GET
으로 요청합니다. 파라미터로 캘린더의 ID, 조회 기간을 전달해야 합니다. limit
파라미터로 페이지당 결과 수를 지정할 수 있습니다.
요청 성공 시 응답은 조회 기간 내 일정 목록을 포함합니다. 서비스에서 만든 일정이 아닌 경우 일정 정보는 time
파라미터만 응답에 포함됩니다. 다음 페이지가 있을 경우, 액세스 토큰 헤더와 함께 after_url
로 요청하면 다음 페이지를 조회할 수 있습니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calender_id | String |
일정을 조회할 캘린더 ID(기본값: 전체 캘린더 조회) | X |
preset | String |
미리 정의된 일정 조회 기간, 다음 중 하나TODAY : 조회 당일THIS_WEEK : 일요일로 시작하는 조회일이 포함된 한 주THIS_MONTH : 1일로 시작하는 조회일이 포함된 한 달주의: from 과 to 가 포함되지 않은 경우 필수주의: next_page_token 가 포함된 경우 무시됨 |
X |
time_zone | String |
기한 일자의 타임존, UTC*, RFC5545의 TZID 형식(기본값: Asia/Seoul ) |
X |
from | String |
일정을 조회할 기간의 시작 시각, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-05-17T12:00:00Z )주의: preset 또는 next_page_token 가 포함된 경우 무시됨 |
X |
to | String |
일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-06-17T12:00:00Z )주의: preset 또는 next_page_token 가 포함된 경우 무시됨 |
X |
limit | Integer |
응답으로 받을 최대 일정 수(최대: 1000, 기본값: 100) 주의: preset 또는 next_page_token 가 포함된 경우 무시됨 |
X |
next_page_token | String |
다음 페이지 조회를 위한 from , to , limit 값이 포함된 조회 조건 토큰, 응답으로 받은 after_url 에서 확인 가능 |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
events | EventBrief[] |
가져온 일정 목록, 가져온 일정이 없어도 빈 리스트 | O |
has_next | Boolean |
다음 페이지 존재 여부 | O |
after_url | String |
다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 has_next 값이 true 인 경우 |
X |
time
필드만 응답에 포함이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
일정 ID | X |
title | String |
일정 제목 | X |
type | String |
일정 타입, 다음 중 하나USER : 일반 일정TEAM : 공유 일정PUBLIC : 공개 일정SUBSCRIBE : 구독 일정 |
X |
calendar_id | String |
캘린더 ID 기본 캘린더의 경우 primary 로 고정 |
X |
time | Time |
일정 시간 | O |
is_host | Boolean |
일정 작성자인지 여부, 공개/구독 일정 또는 초대 받은 일정인 경우 false |
X |
is_recur_event | Boolean |
반복 일정 여부 비고: type 이 USER 인 경우 필수 |
X |
color | String |
일정 색상, 일정 생성 또는 편집 시 지정하지 않은 경우 미포함, Color 중 하나 |
X |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/events" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=user_63759daa38e1f752188e0cc9" \
-d "from=2022-10-26T00:00:00Z" \
-d "to=2022-10-30T00:00:00Z" \
-d "limit=2"
curl -v -G GET "${AFTER_URL}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"events": [
{
"id": "6358e3987ec8e318d0b813bc",
"title": "test_event",
"type": "USER",
"calendar_id": "primary",
"time": {
"start_at": "2022-10-27T00:00:00Z",
"end_at": "2022-10-28T00:00:00Z",
"all_day": true,
"lunar": false
},
"is_owner": true,
"is_recur_event": false,
"color": "RED"
},
...
{
"time": {
"start_at": "2022-10-29T03:00:00Z",
"end_at": "2022-10-29T06:00:00Z",
"time_zone": "Asia/Seoul",
"all_day": false,
"lunar": false
}
}
],
"has_next": true,
"after_url": "http://kapi.kakao.com/v2/api/calendar/events?target_id=1376016924430355247&target_id_type=user_id&calendar_id=primary&next_page_token=eyJmIjoiMjAyMjEwMjZUMDAwMDAwWiIsInQiOiIyMDIyMTAzMFQwMDAwMDBaIiwibCI6MywicmV2IjoxNjY2Nzc0NjU0MzQ1LCJwbGkiOm51bGwsInFsIjpudWxsfQ%3D%3D"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/event |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 일반 일정 정보를 조회합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 GET
으로 요청합니다. 조회할 일정의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 일정의 상세 정보를 담은 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event | EventDetail |
일반 일정의 상세 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
일정 ID | O |
title | String |
일정 제목 | O |
type | String |
일정 타입, 다음 중 하나USER : 일반 일정TEAM : 공유 일정PUBLIC : 공개 일정SUBSCRIBE : 구독 일정 |
O |
calendar_id | String |
캘린더 ID 기본 캘린더의 경우 primary 로 고정 |
O |
time | Time |
일정 시간 | O |
is_host | Boolean |
일정 작성자인지 여부, 공개/구독 일정 또는 초대 받은 일정인 경우 false |
O |
is_recur_event | Boolean |
반복 일정 여부 비고: type 이 USER 인 경우 필수 |
X |
rrule | String |
일정의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z ) |
X |
dt_start | String |
반복 일정의 시작 시각, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-05-17T12:00:00Z ) |
X |
description | String |
일정 설명(최대 5000자) | X |
location | Location |
일정 장소 | X |
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) |
X |
color | String |
일정 색상, 일정 생성 또는 편집 시 지정하지 않은 경우 미포함, Color 중 하나 |
X |
color | String |
일정 색상, Color 중 하나 |
X |
memo | String |
일정 메모 | X |
banner | Banner |
사용자 캘린더의 공개 일정, 또는 구독 캘린더의 일정 정보 상단 배너 정보 배너가 없는 경우 미사용 |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
pc_image_url | String |
PC 환경에서 사용되는 이미지 URL | X |
mobile_image_url | String |
모바일 환경에서 사용되는 이미지 URL | X |
bg_color | String |
일정 메시지에 여백이 있을 경우 채워지는 배경 색상Color 중 하나(기본값: null (투명)) |
X |
link | Link |
배너의 링크 정보 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
web_url | String |
PC 환경에서 사용되는 서비스 페이지 링크 URL | X |
mobile_web_url | String |
모바일 환경에서 사용되는 서비스 페이지 링크 URL | X |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/event" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "event_id=6554545a5df8367886f9d2c5"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event": {
"id": "6554545a5df8367886f9d2c5",
"title": "일정 제목",
"type": "USER",
"calendar_id": "primary",
"is_recur_event": false,
"is_host": true,
"time": {
"start_at": "2022-10-27T03:00:00Z",
"end_at": "2022-10-27T06:00:00Z",
"time_zone": "Asia/Seoul",
"all_day": false,
"lunar": false
},
"description": "일정 설명",
"location": {
"name": "카카오",
"location_id": 18577297,
"address": "경기 성남시 분당구 판교역로 166",
"latitude": 37.39570088983171,
"longitude": 127.1104335101161
},
"reminders": [
15,
30
],
"color": "RED"
}
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/update/event/host |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 일반 일정 정보를 수정합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 일반 일정의 ID와 1개 이상의 수정 사항을 파라미터에 포함해야 합니다. 캘린더 ID는 기본 캘린더(primary
) 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능합니다.
기존 값을 제거하기 위한 파라미터 타입별 요청 값은 아래를 참고합니다.
String
: ""
(빈 문자열)Integer
, Long
: null
요청 성공 시 응답은 반복 일정이 아닌 경우, 수정된 일정의 ID를 포함한 JSON
객체입니다. 반복 일정의 경우 본문 없이 HTTP 200 상태 코드만 반환합니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID | O |
calendar_id | String |
캘린더 ID(기본값: 기존 유지) 주의: event 를 포함하지 않은 경우 필수비고: 기본 캘린더 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능 |
X |
recur_update_type | String |
반복 일정의 수정 범위, 다음 중 하나ALL : 전체 일정THIS : 이 일정만THIS_AND_FOLLOWING : 이 일정과 이후 모든 일정주의: 반복 일정인 경우 필수 |
X |
event | EventUpdate |
수정할 일정 정보 주의: calendar_id 를 포함하지 않은 경우 필수 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
일정 제목(최대 50자, 기본값: 기존 유지) | X |
time | Time |
일정 시간(기본값: 기존 유지) | X |
rrule | String |
일정의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z , 기본값: 기존 유지) |
X |
description | String |
일정 설명(최대 5000자, 기본값: 기존 유지) | X |
location | Location |
일정 장소(기본값: 기존 유지) | X |
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 기존 유지) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ (일정 시작 30일 전) (기본값: 기존 유지) |
X |
color | String |
일정 색상, Color 중 하나 (기본값: 기존 유지) |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID 주의: 반복 일정이 아닌 경우 필수 |
X |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/event/host" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "event_id=6375b0e938e1f752188e0fba" \
-d "calendar_id=primary" \
-d "recur_update_type=ALL" \
-d 'event={
"title":"일반 일정 제목 수정",
"time":{
"start_at":"2022-10-28T03:00:00Z",
"end_at":"2022-10-29T06:00:00Z",
"time_zone":"Asia/Seoul",
"all_day":false,
"lunar":false
},
"rrule":"FREQ=DAILY;UNTIL=20221031T000000Z",
"description":"일반 일정 설명 수정",
"location":{
"name":"카카오",
"location_id":18577297,
"address":"경기 성남시 분당구 판교역로 166",
"latitude":37.39570088983171,
"longitude":127.1104335101161
},
"reminders":[0,15],
"color":"RED"
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"6375b0e938e1f752188e0fba"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://kapi.kakao.com/v2/api/calendar/delete/event |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 일반 일정을 삭제합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 DELETE
로 요청합니다. 일반 일정의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 삭제한 일정의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID | O |
recur_update_type | String |
반복 일정의 수정 범위ALL : 전체 일정THIS : 이 일정만THIS_AND_FOLLOWING : 이 일정과 이후 모든 일정주의: 반복 일정인 경우 필수 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
삭제한 일정 ID 주의: 반복 일정이 아닌 경우 필수 |
X |
curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/delete/event" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "event_id=63630c44d89d8b4150bbb716"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"6351f57c7ec8e318d0b809a0"
}
일정 종류에 대한 설명은 일정 구분을 참고합니다.
공개 일정은 사용 권한이 필요한 기능입니다. 권한 획득 전, [도구] > [REST API 테스트]에서 developers-sample
앱으로 다음의 공개 일정 API를 테스트해 볼 수 있습니다.
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/public/create/event |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
카카오톡 채널의 공개 일정을 생성합니다. 앱과 연결된 카카오톡 채널의 공개 일정만 생성할 수 있습니다.
앱 어드민 키를 헤더에 담아 POST
로 요청합니다. 파라미터로 공개 일정을 소유할 카카오톡 채널의 프로필 ID, 생성할 공개 일정의 상세 정보를 전달해야 합니다. 일정 시작 전후 알림 메시지의 내용과 사용자 정의 버튼의 세부 사항을 설정할 수 있습니다.
요청 성공 시 응답은 생성된 공개 일정의 ID를 포함합니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
channel_public_id | String |
카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함 참고: 카카오톡 채널 프로필 ID 확인 방법 |
X |
event | EventPublic |
공개 일정 상세 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
일정 제목(최대 50자) | O |
time | Time |
일정 시간 | O |
description | String |
일정 설명(최대 5000자) | X |
location | Location |
일정 장소 | X |
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정의 경우: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 reminder 설정값)종일 일정이 아닌 일정의 경우: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 reminder_all_day 값) |
X |
color | String |
일정 색상, Color 중 하나(기본값: BLUE ) |
X |
notification_message | NotificationMessage |
알림 메시지 설정 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
display_custom_button | Boolean |
사용자 정의 버튼의 사용 여부true : 사용자 정의 버튼 사용(기본값)false : 사용 안함 |
X |
before_event_reminder | EventReminder |
일정 시작 전 알림 메시지의 사용자 정의 설정 | X |
after_event_reminder | EventReminder |
일정 시작 후 알림 메시지의 사용자 정의 설정 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
button | Button |
알림 메시지의 사용자 정의 버튼 정보, 미포함 시 기본 사용자 정의 버튼(공유하기) 적용 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
알림 메시지의 사용자 정의 버튼 문구, 다음 중 하나시청하기 예매하기 예약하기 참여하기 상세보기 |
O |
link | Link |
알림 메시지의 사용자 정의 버튼 링크 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
web_url | String |
PC 환경에서 사용되는 서비스 페이지 링크 URL 앱의 Web 플랫폼에 등록된 도메인만 사용 가능, 올바르지 않은 URL 입력 시 사용자 정의 버튼 설정을 무시하고 기본 사용자 정의 버튼(공유하기) 적용 비고: web_url 또는 mobile_web_url 중 하나 필수 |
X |
mobile_web_url | String |
모바일 환경에서 사용되는 서비스 페이지 링크 URL 앱의 Web 플랫폼에 등록된 도메인만 사용 가능, 올바르지 않은 URL 입력 시 사용자 정의 버튼 설정을 무시하고 기본 사용자 정의 버튼(공유하기) 적용 비고: web_url 또는 mobile_web_url 중 하나 필수 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
생성된 공개 일정 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/create/event" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "channel_public_id=_xnrxjem" \
-d 'event={
"title":"공개 일정 테스트",
"time":{
"start_at":"2022-12-10T03:00:00Z",
"end_at":"2022-12-10T06:00:00Z",
"time_zone":"Asia/Seoul",
"all_day":false,
"lunar":false
},
"description":"공개 일정 설명",
"location":{
"name":"카카오",
"location_id":18577297,
"address":"경기 성남시 분당구 판교역로 166",
"latitude":37.39570088983171,
"longitude":127.1104335101161
},
"reminders":[15,30],
"color":"RED",
"notification_message":{
"display_custom_button": true,
"before_event_reminder":{
"button":{
"title":"예약하기",
"link":{
"web_url":"https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
}
}
},
"after_event_reminder":{
"button":{
"title":"참여하기",
"link":{
"web_url":"https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
}
}
}
}
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"6377474a71fdf754fbbf6465"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/public/events |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
카카오톡 채널의 등록된 공개 일정 목록을 가져옵니다. 앱과 연결된 카카오톡 채널의 공개 일정 목록만 가져올 수 있습니다.
앱 어드민 키를 헤더에 담아 GET
으로 요청합니다. 파라미터로 카카오톡 채널의 프로필 ID, 조회 기간을 전달해야 합니다. 조회 가능 기간은 최대 31일입니다. limit
파라미터로 페이지당 결과 수, offset
파라미터로 목록 시작 지점을 지정할 수 있습니다.
요청 성공 시 응답은 카카오톡 채널의 조회 기간 내 일정 목록을 포함합니다. 다음 페이지가 있을 경우, 앱 어드민 키 헤더와 함께 after_url
로 요청하면 다음 페이지를 조회할 수 있습니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
channel_public_id | String |
카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함 참고: 카카오톡 채널 프로필 ID 확인 방법 |
X |
from | String |
일정을 조회할 기간의 시작 시각, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-05-17T12:00:00Z ) |
O |
to | String |
일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-06-17T12:00:00Z ) |
O |
limit | Integer |
페이지당 결과 수(최대: 30, 기본값: 10) | X |
offset | Integer |
목록 시작 지점(기본값: 0) | X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
events | EventPublicBrief[] |
조회 기간 내 공개 일정 목록 | O |
has_next | Boolean |
다음 페이지 존재 여부 | O |
after_url | String |
다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 has_next 값이 true 인 경우 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
일정 ID | O |
title | String |
일정 제목(최대 50자) | O |
type | String |
일정 타입, PUBLIC 으로 고정 |
O |
time | Time |
일정 시간 | O |
color | String |
일정 색상, Color 중 하나(기본값: BLUE ) |
X |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/public/events" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "channel_public_id=_xnrxjem" \
-d "from=2022-12-01T00:00:00Z" \
-d "to=2022-12-11T00:00:00Z" \
-d "limit=3"
curl -v GET "${AFTER_URL}" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"events": [
{
"id": "638db634577cba184608ef56",
"title": "공개 일정",
"type": "PUBLIC",
"time": {
"start_at": "2022-12-10T03:00:00Z",
"end_at": "2022-12-10T06:00:00Z",
"all_day": false
},
"color": "RED"
},
...
],
"has_next": false,
"after_url": "http://kapi.kakao.com/v2/api/calendar/public/events?channel_public_id=_xnrxjem&from=2022-12-01T00%3A00%3A00Z&to=2022-12-11T00%3A00%3A00Z&offset=2"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/public/event |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
카카오톡 채널의 공개 일정 정보를 조회합니다. 앱과 연결된 카카오톡 채널의 공개 일정만 조회할 수 있습니다.
앱 어드민 키를 헤더에 담아 GET
으로 요청합니다. 파라미터로 카카오톡 채널의 프로필 ID, 공개 일정 ID를 전달해야 합니다.
요청 성공 시 응답은 공개 일정 상세 정보를 포함합니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
channel_public_id | String |
카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함 참고: 카카오톡 채널 프로필 ID 확인 방법 |
X |
event_id | String |
공개 일정 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
일정 ID | O |
title | String |
일정 제목(최대 50자) | O |
type | String |
일정 타입, PUBLIC 으로 고정 |
O |
time | Time |
일정 시간 | O |
description | String |
일정 설명(최대 5000자) | X |
location | Location |
일정 장소 | X |
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정의 경우: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) 종일 일정이 아닌 일정의 경우: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) |
X |
color | String |
캘린더 색상, Color 중 하나 |
X |
notification_message | NotificationMessage |
알림 메시지 설정 알림 메시지 사용 시 응답에 포함 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
before_event_reminder | EventReminder |
일정 시작 전 알림 메시지의 사용자 정의 설정 | X |
after_event_reminder | EventReminder |
일정 시작 후 알림 메시지의 사용자 정의 설정 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
button | Button |
알림 메시지의 사용자 정의 버튼 정보 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
title | String |
알림 메시지의 사용자 정의 버튼 문구 | O |
link | Link |
알림 메시지의 사용자 정의 버튼 링크 정보, 기본 사용자 정의 버튼(공유하기) 사용 시 미포함 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
web_url | String |
PC 환경에서 사용되는 서비스 페이지 링크 URL | O |
mobile_web_url | String |
모바일 환경에서 사용되는 서비스 페이지 링크 URL | O |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/public/event" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "channel_public_id=_xnrxjem" \
-d "event_id=637b2d3471fdf754fbbf6e94"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event": {
"id": "638db6d5577cba184608ef58",
"title": "공개 일정 테스트",
"type": "PUBLIC",
"time": {
"start_at": "2022-12-10T03:00:00Z",
"end_at": "2022-12-10T06:00:00Z",
"time_zone": "Asia/Seoul",
"all_day": false,
"lunar": false
},
"description": "공개 일정 설명",
"location": {
"name": "카카오",
"location_id": 18577297,
"address": "경기 성남시 분당구 판교역로 166",
"latitude": 37.39570088983171,
"longitude": 127.1104335101161
},
"reminders": [
15, 30
],
"color": "RED",
"notification_message": {
"before_event_reminder": {
"button": {
"title": "예약하기",
"link": {
"web_url": "https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url": "https://pf.kakao.com/_ZRQBh/43170951"
}
}
},
"after_event_reminder": {
"button": {
"title": "참여하기",
"link": {
"web_url": "https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url": "https://pf.kakao.com/_ZRQBh/43170951"
}
}
}
}
}
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/public/update/event |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
카카오톡 채널의 공개 일정 정보를 수정합니다. 앱과 연결된 카카오톡 채널의 공개 일정만 수정할 수 있습니다.
앱 어드민 키를 헤더에 담아 POST
로 요청합니다. 파라미터로 공개 일정 수정사항을 전달해야 합니다. 파라미터에 포함하지 않은 항목은 기존 정보를 유지합니다.
기존 값을 제거하기 위한 파라미터 타입별 요청 값은 아래를 참고합니다.
String
: ""
(빈 문자열)Integer
, Long
: null
요청 성공 시 응답은 수정한 공개 일정 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
channel_public_id | String |
카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함 참고: 카카오톡 채널 프로필 ID 확인 방법 |
X |
event_id | String |
일정 ID | O |
event | EventPublic |
공개 일정 상세 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
공개 일정 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/update/event" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "channel_public_id=_xnrxjem" \
-d "event_id=638db6d5577cba184608ef58" \
-d 'event={
"title":"공개 일정 수정 테스트",
"time":{
"start_at":"2022-12-10T03:00:00Z",
"end_at":"2022-12-10T06:00:00Z",
"time_zone":"Asia/Seoul",
"all_day":false,
"lunar":false
},
"description":"공개 일정 수정 설명",
"location":{
"name":"카카오",
"location_id":18577297,
"address":"경기 성남시 분당구 판교역로 166",
"latitude":37.39570088983171,
"longitude":127.1104335101161
},
"reminders":[15,30],
"color":"RED",
"notification_message":{
"before_event_reminder":{
"title":"예약하기",
"link":{
"web_url":"https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
}
},
"after_event_reminder":{
"title":"참여하기",
"link":{
"web_url":"https://pf.kakao.com/_ZRQBh/43170951",
"mobile_web_url":"https://pf.kakao.com/_ZRQBh/43170951"
}
}
}
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"638db6d5577cba184608ef58"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://kapi.kakao.com/v2/api/calendar/public/delete/event |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
카카오톡 채널의 공개 일정을 삭제합니다. 앱과 연결된 카카오톡 채널의 공개 일정만 삭제할 수 있습니다.
앱 어드민 키를 헤더에 담아 DELETE
로 요청합니다. 파라미터로 카카오톡 채널의 프로필 ID, 공개 일정 ID를 전달해야 합니다.
요청 성공 시 응답은 수정한 공개 일정 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
channel_public_id | String |
카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함 참고: 카카오톡 채널 프로필 ID 확인 방법 |
X |
event_id | String |
공개 일정 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
공개 일정 ID | O |
curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/public/delete/event" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "channel_public_id=_xnrxjem" \
-d "event_id=637b3bc671fdf754fbbf6f08"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"637b3bc671fdf754fbbf6f08"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/public/follow |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
공개 일정을 사용자 캘린더에 추가합니다. 앱과 연결된 카카오톡의 공개 일정만 사용자 캘린더에 추가할 수 있습니다. 공개 일정이 변경 또는 삭제될 경우, 사용자 캘린더에 추가된 공개 일정도 변경 또는 삭제될 수 있습니다.
액세스 토큰을 헤더에 담아 POST
로 요청합니다. 파라미터로 공개 일정을 추가할 사용자 캘린더 ID, 공개 일정 ID를 전달해야 합니다.
요청 성공 시 응답은 사용자 캘린더에 추가된 공개 일정 ID를 포함합니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
공개 일정에 지정된 색상(color
)이 없는 경우, 대상 캘린더의 기본 색상으로 등록됩니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
공개 일정 ID | O |
calendar_id | String |
사용자 캘린더 ID(기본값: primary ) |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
공개 일정 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/public/follow" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "event_id=637b3d0471fdf754fbbf6f0e" \
-d "calendar_id=user_6375c8e638e1f752188e114e"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"637b3d0471fdf754fbbf6f0e"
}
캘린더 종류에 대한 설명은 캘린더 구분을 참고합니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/subscribable/calendars |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
구독 가능 캘린더 목록을 가져옵니다.
앱 어드민 키를 헤더에 담아 파라미터와 함께 GET
으로 요청합니다. category_name
, subcategory_name
파라미터로 특정 카테고리의 목록만 가져올 수도 있습니다.
요청 성공 시 응답은 카테고리별 구독 캘린더의 ID와 정보 목록을 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
category_name | String |
목록을 가져올 구독 가능 캘린더의 대분류 카테고리(기본값: 모든 카테고리) 주의: subcategory_name 를 지정한 경우 필수 |
X |
subcategory_name | String |
목록을 가져올 구독 가능 캘린더의 소분류 카테고리(기본값: 모든 카테고리) | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
categories | Category[] |
카테고리별로 분류된 구독 가능 캘린더 목록 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
대분류 카테고리 이름 | O |
subcategories | Subcategory[] |
소분류 카테고리 목록 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
소분류 카테고리 이름, 소분류 카테고리 이름이 없는 경우 미포함 | X |
calendars | Calendars[] |
소분류 카테고리로 분류된 구독 가능 캘린더 목록 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
구독 가능 캘린더 ID | O |
name | String |
구독 가능 캘린더 이름 | O |
profile_image_url | String |
구독 가능 캘린더 프로필 URL | O |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/subscribable/calendars" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"categories":[
{
"category_name":"대분류",
"subcategories":[
{
"subcategory_name":"소분류",
"calendars":[
{
"id":"subscribe_5efad4e3890efb10051630f2",
"name":"구독 가능 캘린더 1",
"profile_image_url":"http://t1.daumcdn.net/media/img-section/sports13/logo/team/6/K05_300300.png"
},
{
"id":"subscribe_5efc1e655642c30ba8a6743b",
"name":"구독 가능 캘린더 2"
}
]
}
]
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/subscribe |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
구독 가능 캘린더를 사용자 캘린더에 추가합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 구독 캘린더의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 사용자 캘린더에 추가한 구독 캘린더의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
구독 캘린더 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
구독 캘린더 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/subscribe" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=subscribe_5efad4e3890efb10051630f2"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendar_id":"subscribe_5efad4e3890efb10051630f2"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://kapi.kakao.com/v2/api/calendar/unsubscribe |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자가 구독 중인 캘린더를 구독 해제합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 DELETE
로 요청합니다. 구독 캘린더의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 구독 해제한 구독 캘린더의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
구독 캘린더 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
calendar_id | String |
구독 캘린더 ID | O |
curl -v -G -X DELETE "https://kapi.kakao.com/v2/api/calendar/unsubscribe" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "calendar_id=subscribe_5efad4e3890efb10051630f2"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"calendar_id":"subscribe_5efad4e3890efb10051630f2"
}
일정 종류에 대한 설명은 일정 구분을 참고합니다.
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v2/api/calendar/update/event/guest |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 톡캘린더 및 일정 생성, 조회, 편집/삭제 |
사용자의 게스트 일정 정보를 수정합니다. 게스트 일정은 제한된 정보만 수정할 수 있으며 원본 일정의 정보에 영향을 주지 않습니다. 직접 생성한 일정을 수정하려면 일반 일정 > 수정하기를 호출합니다.
액세스 토큰을 헤더에 담아 파라미터와 함께 POST
로 요청합니다. 게스트 일정의 ID와 1개 이상의 수정 사항을 파라미터에 포함해야 합니다.
기존 값을 제거하기 위한 파라미터 타입별 요청 값은 아래를 참고합니다.
String
: ""
(빈 문자열)Integer
, Long
: null
요청 성공 시 응답은 수정된 일정의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID | O |
calendar_id | String |
캘린더 ID(기본값: 기존 유지) 주의: event 를 포함하지 않은 경우 필수 |
X |
event | EventGuest |
수정할 게스트 일정 정보, EventGuest 참고 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
reminders | Integer[] |
미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 기존 유지) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 기존 유지) |
X |
color | String |
일정 색상, Color 중 하나 (기본값: 기존 유지) |
X |
memo | String |
일정에 대한 메모(최대 5000자, 기본값: 기존 유지) | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
event_id | String |
일정 ID | O |
curl -v -X POST "https://kapi.kakao.com/v2/api/calendar/update/event/guest" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "event_id=6351f57c7ec8e318d0b809a0" \
-d 'event={
"reminders":[30,45],
"color":"RED",
"memo":"메모 수정"
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"event_id":"6351f57c7ec8e318d0b809a0"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v2/api/calendar/holidays |
서비스 앱 어드민 키 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
- | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
- | - |
법정공휴일과 톡캘린더 서비스에서 지정한 일부 기념일 목록을 조회합니다.
앱 어드민 키를 헤더에 담아 파라미터와 함께 GET
으로 요청합니다.
요청 성공 시 응답은 각 공휴일 및 주요 기념일 정보 목록을 포함한 JSON
객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} 인증 방식, 서비스 앱 어드민 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
from | String |
일정을 조회할 기간의 시작 시각, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-05-17T12:00:00Z ) |
O |
to | String |
일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545의 DATE-TIME 형식(예: 2022-06-17T12:00:00Z ) |
O |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
events | EventSpecial[] |
가져온 공휴일 및 주요 기념일 목록 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
일정 ID | O |
title | String |
일정 제목(최대 50자) | O |
time | TimeDefault |
일정 시간 | O |
holiday | Boolean |
공휴일 여부 | O |
curl -v -G GET "https://kapi.kakao.com/v2/api/calendar/holidays" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "from=2022-10-01T00:00:00Z" \
-d "to=2022-10-20T00:00:00Z"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"events":[
{
"id":"S5d5ba43907d5351aba275d72",
"title":"국군의날",
"time":{
"start_at":"2022-10-01T00:00:00Z",
"end_at":"2022-10-02T00:00:00Z",
"all_day":true
},
"holiday":false
},
{
"id":"S5d5ba43907d5351aba275d73",
"title":"개천절",
"time":{
"start_at":"2022-10-03T00:00:00Z",
"end_at":"2022-10-04T00:00:00Z",
"all_day":true
},
"holiday":true
},
{
"id":"S5d5ba43907d5351aba275d74",
"title":"한글날",
"time":{
"start_at":"2022-10-09T00:00:00Z",
"end_at":"2022-10-10T00:00:00Z",
"all_day":true
},
"holiday":true
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/api/calendar/create/task |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
할 일을 생성합니다.
액세스 토큰을 헤더에 담아 POST
로 요청합니다.
rrule
을 포함하면 기한 일자부터 일정한 주기를 갖는 반복 할 일을, 포함하지 않으면 한 번으로 끝나는 일반 할 일을 생성합니다.
반복 할 일은 한 건으로 표시되며, 현재 시간이 기한 일자를 지나면 다음 반복일로 기한 일자가 자동 수정됩니다. 반복 할 일의 record_on
을 true
로 설정하면 [도전 기록 보기]를 활성화해 완료 기록을 확인할 수 있습니다.
요청 성공 시 응답은 생성한 할 일 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task | Task |
할 일 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
내용(최대 1,000자) | O |
due_info | DueInfo |
기한 일자 정보(기본값: 기한 없음) | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
due_date | String |
기한 일자, yyyyMMdd 형식주의: 과거 시점으로 설정 불가 |
O |
time_zone | String |
기한 일자의 타임존, UTC*, RFC5545의 TZID 형식(기본값: Asia/Seoul ) |
X |
alarm_time | String |
알림 시각, 5분 간격의 HHmm 형식(단위: 분, 기본값: 알림 없음) |
X |
recur | Recur |
할 일의 반복 정보(기본값: 반복 없음) | X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
rrule | String |
할 일의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z )UNTIL 은 yyyyMMdd'T'000000Z 형식으로 due_date 이후만 지정 가능하며 rrule 조건을 만족하는 날짜 하루 이상 필요 |
O |
record_on | Boolean |
[도전 기록 보기] 활성화 여부true : 활성화false : 비활성화(기본값) |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
생성한 할 일 ID | O |
curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/create/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d 'task={
"content": "오늘의 할 일",
"due_info": {
"due_date": "${DUE_DATE}",
"time_zone": "Asia/Seoul",
"alarm_time": "0900",
"recur": {
"rrule": "FREQ=DAILY;COUNT=3",
"record_on": true
}
}
}'
HTTP/1.1 200 OK
{
"task_id": "${TASK_ID}"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v1/api/calendar/tasks |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
할 일 정보를 조회합니다.
액세스 토큰을 헤더에 담아 GET
으로 요청합니다.
파라미터로 할 일 ID를 포함해 특정 건을 조회하거나, 조회할 기간을 포함해 여러 건을 조회할 수 있습니다. 여러 건 조회 시 최근 수정 순서로 정렬됩니다. 반복 할 일은 한 건으로 표시되며, 현재 시간이 기한 일자를 지나면 다음 반복일로 기한 일자가 자동 수정됩니다.
요청 성공 시 응답은 할 일 정보를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID 주의: 해당 파라미터 포함 시 ID에 해당하는 할 일 단건만 조회하며, 다른 요청 파라미터는 모두 무시됨 |
X |
from | String |
조회 기간의 시작 시각, yyyyMMdd 형식비고: task_id 미포함 시 필수 |
X |
to | String |
조회 기간의 종료 시각, yyyyMMdd 형식from 이후 31일 이내의 값비고: task_id 미포함 시 필수 |
X |
task_status | String |
조회할 할 일 상태, 다음 중 하나COMPLETED : 완료TODO : 미완료(기본값)ALL :전체(TODO 상태 우선 표시) |
X |
task_filter | String |
조회할 할 일 조건(기본값: 전체 할 일 조회) 쉼표(",")를 구분자로 여러 값 전달 가능(예: "authorized,bookmark"), 다음 중 하나 authorized : 수정 또는 삭제 가능한 할 일bookmark : 즐겨찾기에 추가한 할 일 |
X |
offset | Integer |
조회 결과 목록 시작 지점(기본값: 0) | X |
limit | Integer |
페이지당 결과 수(기본값: 100, 최대 1000) | X |
time_zone | String |
기한 일자의 타임존, UTC*, RFC5545의 TZID 형식(기본값: Asia/Seoul )비고: 응답의 status 시각 계산 기준 |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task | Task[] |
할 일 정보 목록 | O |
count | Integer |
조회 범위 내 할 일 전체 개수, limit 로 지정한 숫자 까지만 목록에 포함하며 미포함된 할 일 목록은 after_url 로 조회 가능 |
O |
has_next | Boolean |
다음 목록 존재 여부 | O |
after_url | String |
다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 has_next 값이 true 인 경우 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID | O |
content | String |
내용 | O |
status | String |
할 일의 상태SCHEDULED : 기한 일자 경과 전COMPLETED : 완료DELAYED : 기한 일자 경과 |
O |
bookmark | Boolean |
즐겨찾기 추가 여부 | O |
authorized | Boolean |
수정 또는 삭제 가능 여부 | O |
due_info | DueInfo |
기한 일자 정보 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
due_date | String |
기한 일자, yyyyMMdd 형식 |
O |
alarm_time | String |
알림 시각, 5분 간격의 HHmm 형식(단위: 분) |
X |
recur | Recur |
할 일의 반복 정보 | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
rrule | String |
할 일의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z ) |
O |
record_on | Boolean |
[도전 기록 보기] 활성화 여부true : 활성화false : 비활성화 |
O |
is_ended | Boolean |
반복 할 일의 완료 여부, 마지막 반복 할 일을 완료한 경우 true |
O |
curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/tasks" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "time_zone=Asia/Seoul" \
-d "task_id=${TASK_ID}"
curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/tasks" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "from=20231208" \
-d "to=20231215" \
-d "time_zone=Asia/Seoul" \
-d "task_status=ALL" \
-d "task_filter=authorized" \
-d "offset=0" \
-d "limit=4"
HTTP/1.1 200 OK
{
"tasks": [
{
"task_id": "${TASK_ID}",
"content": "테스트 할 일 1",
"status": "SCHEDULED",
"bookmark": false,
"authorized": true
},
{
"task_id": "${TASK_ID}",
"content": "테스트 할 일 2",
"status": "DELAYED",
"bookmark": true,
"authorized": true,
"due_info": {
"due_date": "20231211",
"alarm_time": "0900"
}
},
{
"task_id": "${TASK_ID}",
"content": "테스트 할 일 3",
"status": "SCHEDULED",
"bookmark": false,
"authorized": true,
"due_info": {
"due_date": "20231212",
"alarm_time": "0900",
"recur": {
"rrule": "FREQ=DAILY;",
"record_on": false,
"is_ended": false
}
}
},
{
"task_id": "${TASK_ID}",
"content": "테스트 할 일 4",
"status": "SCHEDULED",
"bookmark": false,
"authorized": true,
"due_info": {
"due_date": "20231212",
"alarm_time": "0900",
"recur": {
"rrule": "FREQ=DAILY;",
"record_on": false,
"is_ended": false
}
}
}
],
"count": 22,
"has_next": true,
"after_url": "https://kapi.kakao.com/v1/api/calendar/tasks?task_status=ALL&target_id_type=user_id&limit=4&target_id=${TASK_ID}&from=20231208&to=20231215&task_filter=authorized&time_zone=Asia%2FSeoul&offset=4"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v1/api/calendar/task/records |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
특정 반복 할 일의 도전 기록을 확인합니다. [도전 기록 보기]를 활성화한 할 일만 확인 가능합니다.
액세스 토큰을 헤더에 담아 GET
으로 요청합니다. 파라미터로 할 일 ID를 포함해야 합니다. 조회 기간을 지정하면 해당 기간 내의 기록만 확인할 수 있습니다.
요청 성공 시 응답은 일자별 완료 여부를 포함한 JSON
객체입니다. 대상이 반복 할 일이 아니거나, 완료 또는 실패 기록이 없는 경우 records
에 빈 배열이 포함됩니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID | O |
from | String |
조회 기간의 시작 연월, yyyyMM 형식 |
X |
to | String |
조회 기간의 종료 연월, yyyyMM 형식 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
records | Record[] |
도전 기록 정보 목록, 완료 또는 실패 기록이 없거나 반복 할 일이 아닌 경우 빈 배열로 응답 | X |
start_at | String |
도전 기록 시작 연월, yyyyMM 형식비고: 도전 기록이 존재하는 경우만 응답에 포함 |
X |
end_at | String |
도전 기록 종료 연월, yyyyMM 형식비고: 도전 기록이 존재하는 경우만 응답에 포함 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
date | String |
도전 일자, yyyyMMdd 형식 |
O |
complete | Boolean |
해당 도전 일자의 할 일 완료 여부 | O |
curl -v -G GET "https://kapi.kakao.com/v1/api/calendar/task/records" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "task_id=${TASK_ID}" \
-d "from=202311" \
-d "to=202312"
HTTP/1.1 200 OK
{
"records": [
{
"date": "20231211",
"complete": true
}
],
"start_at": "202312",
"end_at": "202312"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/api/calendar/update/task |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
특정 할 일의 정보를 수정합니다. 카카오톡 프로필 스티커에 등록된 할 일은 수정할 수 없습니다.
액세스 토큰을 헤더에 담아 POST
로 요청합니다. 할 일의 ID와 1개 이상의 수정 사항을 파라미터에 포함해야 합니다. 파라미터에 할당된 값을 삭제하려면 null
을 전달합니다.
할 일의 기한 일자를 삭제하면 반복 정보도 함께 삭제되며, 반복 할 일에서만 설정 가능한 도전 기록 보기도 비활성화 됩니다.
요청 성공 시 응답은 수정된 할 일의 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID | O |
task | Task | 할 일 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
content | String |
내용(최대 1,000자, 기본값: 기존 유지) | X |
bookmark | Boolean |
북마크 설정 여부(기본값: 기존 유지) | X |
due_info | DueInfo |
기한 일자 정보(기본값: 기존 유지) | X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
due_date | String |
기한 일자, yyyyMMdd 형식(기본값: 기존 유지)주의: 과거 시점으로 설정 불가 |
X |
time_zone | String |
기한 일자의 타임존, UTC*, RFC5545의 TZID 형식(기본값: 기존 유지) |
X |
alarm_time | String |
알림 시각, 5분 간격의 HHmm 형식(단위: 분, 기본값: 기존 유지) |
X |
recur | Recur |
할 일의 반복 정보(기본값: 기존 유지) | X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
rrule | String |
할 일의 반복 주기, UTC*, RFC5545의 RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z )UNTIL 은 yyyyMMdd'T'000000Z 형식으로 due_date 이후만 지정 가능하며 rrule 조건을 만족하는 날짜 하루 이상 필요(기본값: 기존 유지) |
X |
record_on | Boolean |
[도전 기록 보기] 활성화 여부(기본값: 기존 유지)true : 활성화false : 비활성화 |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
수정한 할 일 ID | O |
curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d 'task={
"content": "테스트 할 일 수정",
"due_info": {
"due_date": "${DUE_DATE}",
"time_zone": "Asia/Seoul",
"alarm_time": "0900",
"recur": {
"rrule": "FREQ=DAILY;",
"record_on": false
}
},
"bookmark": true
}' \
-d "task_id=${TASK_ID}"
curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d 'task={
"due_info": null
}' \
-d "task_id=${TASK_ID}"
curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/update/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d 'task={
"due_info": {
"due_date": "${DUE_DATE}",
"time_zone": "Asia/Seoul",
"alarm_time": "0900",
"recur": null
}
}' \
-d "task_id=${TASK_ID}"
HTTP/1.1 200 OK
{
"task_id": "${TASK_ID}"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/api/calendar/complete/task |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
특정 할 일의 완료 여부를 설정합니다.
액세스 토큰을 헤더에 담아 POST
로 요청합니다. 파라미터로 할 일 ID와 완료 여부를 함께 전달해야 합니다.
요청 성공 시 응답은 생성한 할 일 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID | O |
complete | Boolean |
할 일의 완료 여부true : 완료false : 미완료 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
완료 여부를 설정한 할 일 ID | O |
curl -v -X POST "https://kapi.kakao.com/v1/api/calendar/complete/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "task_id=${TASK_ID}" \
-d "complete=true"
HTTP/1.1 200 OK
{
"task_id": "${TASK_ID}"
}
메서드 | URL | 인증 방식 |
---|---|---|
DELETE |
https://kapi.kakao.com/v1/api/calendar/delete/task |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
---|---|---|---|
필요: 사용 권한 | 플랫폼 등록 카카오 로그인 활성화 동의항목 |
필요 | 필요: 이용 정책 참고 |
특정 할 일을 삭제합니다. 카카오톡 프로필 스티커에 등록된 할 일은 삭제할 수 없습니다.
액세스 토큰을 헤더에 담아 DELETE
로 요청합니다. 파라미터로 할 일 ID를 포함해야 합니다.
요청 성공 시 응답은 삭제한 할 일 ID를 포함한 JSON
객체입니다. 요청 실패 시 에러 코드에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
할 일 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
task_id | String |
삭제한 할 일 ID | O |
curl -v -G -X DELETE "https://kapi.kakao.com/v1/api/calendar/delete/task" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "task_id=${TASK_ID}"
HTTP/1.1 200 OK
{
"task_id": "${TASK_ID}"
}
API별 필수 파라미터
name
API별 기본값
location_id
, address
, latitude
, longitude
: 없음name
, location_id
, address
, latitude
, longitude
: 기존 유지이름 | 타입 | 설명 | 필수 |
---|---|---|---|
name | String |
장소 이름(최대 100자) | X |
location_id | Long |
장소 ID | X |
address | String |
주소 | X |
latitude | Double |
위도 | X |
longitude | Double |
경도 | X |
API별 필수 파라미터
start_at
, end_at
API별 기본값
time_zone
: Asia/Seoul
start_at
, end_at
, time_zone
, all_day
, lunar
: 기존 유지이름 | 타입 | 설명 | 필수 |
---|---|---|---|
start_at | String |
일정 시작 시각, 5분 간격으로 설정 가능 UTC*, RFC5545의 DATE-TIME 형식(예: 2022-05-17T12:00:00Z )주의: all_day 가 true 인 경우 YYYY-MM-DDT00:00:00Z 으로 설정(다른 값 설정 시 에러 발생) |
X |
end_at | String |
일정 종료 시각, start_at 과 같은 형식, start_at 보다 미래 시점의 값주의: all_day 가 true 인 경우 YYYY-MM-DDT00:00:00Z 으로 설정 필요(다른 값 설정 시 에러 발생) |
X |
time_zone | String |
타임존 설정, UTC*, RFC5545의 TZID 형식(기본값: Asia/Seoul ) |
X |
all_day | Boolean |
종일 일정 여부(기본값: false ) |
X |
lunar | Boolean |
날짜 기준을 음력으로 설정(기본값: false ) |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
start_at | String |
일정 시작 시각, UTC*, RFC5545의 DATE-TIME 형식 |
O |
end_at | String |
일정 종료 시각, start_at 과 같은 형식, start_at 보다 미래 시점의 값 |
O |
all_day | Boolean |
종일 일정 여부(기본값: false ) |
X |
* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고
파라미터에는 Name
에 해당하는 색상명(예: BLUE
)을 포함해야 합니다. 16진수 색상 코드는 확인용 참고 수치입니다.
이름 | 16진수 색상 코드 |
---|---|
BLUE | 2C88DE |
ROYAL_BLUE | 2D69E0 |
NAVY_BLUE | 223788 |
RED | D42726 |
PINK | ED5683 |
ORANGE | FF9429 |
GREEN | 149959 |
LIME | 7CB343 |
OLIVE | A4AD15 |
MINT | 5CC5BE |
MAGENTA | AB47BC |
VIOLET | 8A4B9B |
LAVENDER | 7986CB |
BROWN | 945C1F |
GRAY | 666666 |