톡캘린더

REST API

이 문서는 톡캘린더 REST API 사용법을 안내합니다.

이 문서에 포함된 기능 일부는 [도구] > [REST API 테스트]에서 사용해 볼 수 있습니다. 테스트 기능은 어드민 키로 호출할 수 없습니다.

시작하기 전에

캘린더 및 일정 ID 확인

캘린더 또는 일정을 지정하기 위해 필요한 캘린더 ID와 일정 ID를 확인하는 방법과 API 호출 순서에 대해 안내합니다.

캘린더 ID 확인

캘린더 종류	ID 확인 방법
기본 캘린더	`primary`로 고정
서브 캘린더	사용자 캘린더 > 목록 조회를 요청해 서브 캘린더 목록 확인 목록 내 캘린더 정보를 참고해 서브 캘린더 ID 확인(서비스가 생성하지 않은 캘린더는 ID만 확인 가능)
구독 캘린더	구독 캘린더 > 구독 가능 캘린더 목록 조회를 요청해 구독 가능 캘린더 목록 확인 목록 내 캘린더 정보를 참고해 구독 캘린더 ID 확인

일정 ID 확인

일정 종류	ID 확인 방법
일반 / 게스트 일정	캘린더 ID 확인으로 일정이 등록된 캘린더 ID 확인 확인한 캘린더 ID를 포함해 일반 일정 > 목록 조회 요청 목록 내 일정 정보를 참고해 일정 ID 확인
공개 일정	공개 일정 > 목록 조회 요청 목록 내 일정 정보를 참고해 일정 ID 확인

캘린더 메시지 전송

카카오톡으로 공개 일정과 구독 캘린더를 전달하는 캘린더 메시지를 보낼 수 있습니다. 사용자는 해당 메시지의 버튼으로 공개 일정을 사용자 캘린더에 추가하거나 구독 캘린더를 구독할 수 있습니다. 자세한 내용은 톡캘린더 메시지를 참고합니다.

사용자 캘린더

캘린더의 목록을 조회하고 관리할 수 있습니다. 캘린더 종류에 대한 설명은 캘린더 구분을 참고합니다.

목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://kapi.kakao.com/v2/api/calendar/calendars`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자 캘린더의 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
filter	`String`	목록을 가져올 캘린더 타입, 아래 중 하나 `USER`: 기본 캘린더, 서브 캘린더 `SUBSCRIBE`: 구독한 구독 캘린더 `ALL`: 전체 사용자 캘린더(기본값)	X

응답

본문

이름	타입	설명	필수
calendars	`Calendar[]`	기본 캘린더, 서브 캘린더 목록	X
subscribe_calendars	`Subscribe[]`	구독한 구독 캘린더 목록	X

Calendar

캘린더 생성/편집 시 값을 입력한 항목만 응답에 포함

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자 캘린더에 새로운 서브 캘린더를 생성합니다.

생성한 서브 캘린더에 일반 일정 생성하기 또는 공개 일정 > 사용자 캘린더에 추가로 서비스의 일정을 추가할 수 있습니다.

요청

헤더

이름	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 특정 서브 캘린더 설정을 수정합니다.

다른 서비스에서 생성한 서브 캘린더는 수정할 수 없습니다. 서비스에서 직접 생성한 서브 캘린더만 수정 가능합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
calendar_id	`String`	서브 캘린더 ID	O
name	`String`	캘린더 이름 (최대 50자)	X*
color	`String`	캘린더 색상, `Color` 중 하나(기본값: `BLUE`)	X*
reminder	`Integer`	종일이 아닌 일정의 기본 알림 설정, 5분 간격으로 설정 가능하며 `null` 전달 시 값 초기화	X*
reminder_all_day	`Integer`	종일 일정의 기본 알림 설정, 5분 간격으로 설정 가능하며 `null` 전달 시 값 초기화	X*

* name, color, reminder, reminder_all_day 중 1개 이상 필수

응답

본문

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 특정 서브 캘린더를 삭제합니다.

다른 서비스에서 생성한 서브 캘린더는 삭제할 수 없습니다. 서비스에서 직접 생성한 서브 캘린더만 삭제 가능합니다.

요청

헤더

이름	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 특정 캘린더에 일반 일정을 생성합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
calendar_id	`String`	일정을 생성할 캘린더 ID(기본값: `primary`) 중요: 기본 캘린더(`primary`) 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능	X
event	`EventCreate`	생성할 일정 정보	O

EventCreate

이름	타입	설명	필수
title	`String`	일정 제목(최대 50자)	O
time	`Time`	일정 시간	O
rrule	`String`	일정의 반복 주기(RFC5545의 `RRULE` 형식, 예: `FREQ=DAILY;UNTIL=20211208T155959Z`) 주의: 포함 시 반복 일정, 미포함 시 한 번으로 끝나는 일반 일정 생성	X
description	`String`	일정 설명(최대 5000자)	X
location	`Location`	일정 장소	X
reminders	`Integer[]`	미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 `reminder_all_day` 값) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 `reminder` 값) 참고: 빈 리스트를 전달하면 미지정과 동일하게 기본값 적용	X
color	`String`	일정 색상, `Color` 중 하나 (기본값: 해당 캘린더의 `color` 값)	X

응답

본문

이름	타입	설명	필수
event_id	`String`	생성한 일정 ID 참고: 반복 일정도 회차 구분 없는 ID로 응답, 회차별 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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

특정 캘린더에 등록된 일정 목록을 반환합니다.

요청

헤더

이름	설명	필수
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`	기한 일자의 타임존(IANA 타임존 데이터베이스의 이름, 기본값: `Asia/Seoul`)	X
from	`String`	일정을 조회할 기간의 시작 시각(UTC 기준 RFC3339 형식, 예: `2022-05-17T12:00:00Z`) 주의: `preset` 또는 `next_page_token` 값이 있는 경우 무시됨	X
to	`String`	일정을 조회할 기간의 종료 시각, `from` 이후 31일 이내의 값(UTC 기준 RFC3339 형식, 예: `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

응답

본문

이름	타입	설명	필수
events	`EventBrief[]`	가져온 일정 목록, 가져온 일정이 없어도 빈 리스트	O
has_next	`Boolean`	다음 페이지 존재 여부	O
after_url	`String`	다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 `has_next` 값이 `true`인 경우	X

EventBrief

서비스에서 만든 일정이 아닌 경우 time 필드만 응답에 포함

이름	타입	설명	필수
id	`String`	일정 ID 반복 일정은 회차별 ID로 응답, 일정 ID와 회차 시작 시각을 밑줄(`_`)로 이은 형식(회차 시작 시각은 RFC5545의 `DATE-TIME` 형식, 예: `6358e3987ec8e318d0b813bc_20220517T120000Z`)	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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 일반 일정 정보를 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
event_id	`String`	일정 ID 반복 일정은 회차별 ID 지정 필요, 일정 ID와 회차 시작 시각을 밑줄(`_`)로 이은 형식(회차 시작 시각은 RFC5545의 `DATE-TIME` 형식, 예: `6358e3987ec8e318d0b813bc_20220517T120000Z`)	O

응답

본문

이름	타입	설명	필수
event	`EventDetail`	일반 일정의 상세 정보	O

EventDetail

이름	타입	설명	필수
id	`String`	일정 ID 반복 일정은 회차별 ID로 응답, 일정 ID와 회차 시작 시각을 밑줄(`_`)로 이은 형식(회차 시작 시각은 RFC5545의 `DATE-TIME` 형식, 예: `6358e3987ec8e318d0b813bc_20220517T120000Z`)	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`	일정의 반복 주기(RFC5545의 `RRULE` 형식, 예: `FREQ=DAILY;UNTIL=20211208T155959Z`)	X
dt_start	`String`	반복 일정의 시작 시각(UTC 기준 RFC5545의 `DATE-TIME` 형식, 예: `20220517T120000Z`)	X
description	`String`	일정 설명(최대 5000자)	X
location	`Location`	일정 장소	X
reminders	`Integer[]`	미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전)	X
color	`String`	일정 색상, 일정 생성 또는 편집 시 지정하지 않은 경우 미포함, `Color` 중 하나	X
memo	`String`	일정 메모	X
banner	`Banner`	사용자 캘린더의 공개 일정, 또는 구독 캘린더의 일정 정보 상단 배너 정보 배너가 없는 경우 미사용	X

Banner

이름	타입	설명	필수
pc_image_url	`String`	PC 환경에서 사용되는 이미지 URL	X
mobile_image_url	`String`	모바일 환경에서 사용되는 이미지 URL	X
bg_color	`String`	일정 메시지에 여백이 있을 경우 채워지는 배경 색상 `Color` 중 하나(기본값: `null`(투명))	X
link	`Link`	배너의 링크 정보	X

Link

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 일반 일정 정보를 수정합니다.

기존 값 제거 시 파라미터 타입별 요청 값

원시(Primitive) 타입(Integer, Boolean, Double, String 등): null
그 외 타입: null 또는 {}

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
event_id	`String`	일정 ID 반복 일정은 회차별 ID 지정 필요, 일정 ID와 회차 시작 시각을 밑줄(`_`)로 이은 형식(회차 시작 시각은 RFC5545의 `DATE-TIME` 형식, 예: `6358e3987ec8e318d0b813bc_20220517T120000Z`)	O
calendar_id	`String`	캘린더 ID(기본값: 기존 유지) 주의: `event`를 포함하지 않은 경우 필수 중요: 기본 캘린더(`primary`) 또는 서비스에서 직접 생성한 서브 캘린더의 ID만 지정 가능	X
recur_update_type	`String`	반복 일정의 수정 범위, 아래 중 하나 `ALL`: 전체 일정 `THIS`: 이 일정만 `THIS_AND_FOLLOWING`: 이 일정과 이후 모든 일정 주의: 반복 일정인 경우 필수	X
event	`EventUpdate`	수정할 일정 정보 주의: `calendar_id`를 포함하지 않은 경우 필수	X

EventUpdate

이름	타입	설명	필수
title	`String`	일정 제목(최대 50자, 기본값: 기존 유지)	X
time	`Time`	일정 시간(기본값: 기존 유지)	X
rrule	`String`	일정의 반복 주기(RFC5545의 `RRULE` 형식, 예: `FREQ=DAILY;UNTIL=20211208T155959Z`, 기본값: 기존 유지)	X
description	`String`	일정 설명(최대 5000자, 기본값: 기존 유지)	X
location	`Location`	일정 장소(기본값: 기존 유지)	X
reminders	`Integer[]`	미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 기존 유지) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 기존 유지)	X
color	`String`	일정 색상, `Color` 중 하나 (기본값: 기존 유지)	X

응답

본문

이름	타입	설명	필수
event_id	`String`	일정 ID 주의: 반복 일정이 아닌 경우 필수, 반복 일정은 본문 없이 `HTTP 200` 상태 코드만 반환	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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 일반 일정을 삭제합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
event_id	`String`	일정 ID 반복 일정은 회차별 ID 지정 필요, 일정 ID와 회차 시작 시각을 밑줄(`_`)로 이은 형식(회차 시작 시각은 RFC5545의 `DATE-TIME` 형식, 예: `6358e3987ec8e318d0b813bc_20220517T120000Z`)	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"
}

공개 일정

일정 종류에 대한 설명은 일정 구분을 참고합니다.

생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://kapi.kakao.com/v2/api/calendar/public/create/event`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

카카오톡 채널의 공개 일정을 생성합니다.

앱과 연결된 카카오톡 채널의 공개 일정만 생성할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 참고: 카카오톡 채널 프로필 ID 확인 방법 중요: 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함	X
event	`EventPublic`	공개 일정 상세 정보	O

EventPublic

이름	타입	설명	필수
title	`String`	일정 제목(최대 50자)	O
time	`Time`	일정 시간	O
description	`String`	일정 설명(최대 5000자)	X
location	`Location`	일정 장소	X
reminders	`Integer[]`	미리 알림 설정(단위: 분), 5분 간격으로 최대 2개 설정 가능 종일 일정 범위: -1440(일정 당일이 끝나기 전) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 `reminder_all_day` 값) 종일 일정이 아닌 일정 범위: 0(일정 시작 시각) < 알림값 ≤ 43200(일정 시작 30일 전) (기본값: 해당 캘린더의 `reminder` 값) 참고: 빈 리스트를 전달하면 미지정과 동일하게 기본값 적용	X
color	`String`	일정 색상, `Color` 중 하나(기본값: `BLUE`)	X
notification_message	`NotificationMessage`	알림 메시지 설정	X

NotificationMessage

이름	타입	설명	필수
display_custom_button	`Boolean`	사용자 정의 버튼의 사용 여부 `true`: 사용자 정의 버튼 사용(기본값) `false`: 사용 안함	X
before_event_reminder	`EventReminder`	일정 시작 전 알림 메시지의 사용자 정의 설정	X
after_event_reminder	`EventReminder`	일정 시작 후 알림 메시지의 사용자 정의 설정	X

EventReminder

이름	타입	설명	필수
button	`Button`	알림 메시지의 사용자 정의 버튼 정보, 미포함 시 기본 사용자 정의 버튼(공유하기) 적용	X

Button

이름	타입	설명	필수
title	`String`	알림 메시지의 사용자 정의 버튼 문구, 아래 중 하나 `시청하기` `예매하기` `예약하기` `참여하기` `상세보기`	O
link	`Link`	알림 메시지의 사용자 정의 버튼 링크 정보	O

Link

이름	타입	설명	필수
web_url	`String`	PC 환경에서 사용되는 서비스 페이지 링크 URL [앱] > [제품 링크 관리] > [웹 도메인]에 등록된 도메인만 사용 가능, 올바르지 않은 URL 입력 시 사용자 정의 버튼 설정을 무시하고 기본 사용자 정의 버튼(공유하기) 적용	X*
mobile_web_url	`String`	모바일 환경에서 사용되는 서비스 페이지 링크 URL [앱] > [제품 링크 관리] > [웹 도메인]에 등록된 도메인만 사용 가능, 올바르지 않은 URL 입력 시 사용자 정의 버튼 설정을 무시하고 기본 사용자 정의 버튼(공유하기) 적용	X*

* web_url 또는 mobile_web_url 중 하나 필수

응답

본문

이름	타입	설명	필수
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`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

카카오톡 채널의 등록된 공개 일정 목록을 반환합니다.

앱과 연결된 카카오톡 채널의 공개 일정 목록만 가져올 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 참고: 카카오톡 채널 프로필 ID 확인 방법 중요: 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함	X
from	`String`	일정을 조회할 기간의 시작 시각(UTC 기준 RFC3339 형식, 예: `2022-05-17T12:00:00Z`)	O
to	`String`	일정을 조회할 기간의 종료 시각, `from` 이후 31일 이내의 값(UTC 기준 RFC3339 형식, 예: `2022-06-17T12:00:00Z`)	O
limit	`Integer`	페이지당 결과 수(최대: 30, 기본값: 10)	X
offset	`Integer`	조회 결과 목록 시작 지점(기본값: 0)	X

응답

본문

이름	타입	설명	필수
events	`EventPublicBrief[]`	조회 기간 내 공개 일정 목록	O
has_next	`Boolean`	다음 페이지 존재 여부	O
after_url	`String`	다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 `has_next` 값이 `true`인 경우	X

EventPublicBrief

이름	타입	설명	필수
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`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

카카오톡 채널의 공개 일정 정보를 반환합니다.

앱과 연결된 카카오톡 채널의 공개 일정만 조회할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 참고: 카카오톡 채널 프로필 ID 확인 방법 중요: 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 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

NotificationMessage

이름	타입	설명	필수
before_event_reminder	`EventReminder`	일정 시작 전 알림 메시지의 사용자 정의 설정	X
after_event_reminder	`EventReminder`	일정 시작 후 알림 메시지의 사용자 정의 설정	X

EventReminder

이름	타입	설명	필수
button	`Button`	알림 메시지의 사용자 정의 버튼 정보	X

Button

이름	타입	설명	필수
title	`String`	알림 메시지의 사용자 정의 버튼 문구	O
link	`Link`	알림 메시지의 사용자 정의 버튼 링크 정보, 기본 사용자 정의 버튼(공유하기) 사용 시 미포함	X

Link

이름	타입	설명	필수
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`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

카카오톡 채널의 공개 일정 정보를 수정합니다.

참고 사항

앱과 연결된 카카오톡 채널의 공개 일정만 수정할 수 있습니다.
기존 값 제거 방법은 기존 값 제거 시 파라미터 타입별 요청 값을 참고합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 참고: 카카오톡 채널 프로필 ID 확인 방법 중요: 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 ID를 반드시 전달해야 함	X
event_id	`String`	일정 ID	O
event	`EventUpdatePublic`	수정할 공개 일정 정보	O

EventUpdatePublic

이름	타입	설명	필수
title	`String`	일정 제목(최대 50자, 기본값: 기존 유지)	X
time	`Time`	일정 시간(기본값: 기존 유지)	X
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

응답

본문

이름	타입	설명	필수
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`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

카카오톡 채널의 공개 일정을 삭제합니다.

앱과 연결된 카카오톡 채널의 공개 일정만 삭제할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
channel_public_id	`String`	카카오톡 채널 프로필 ID 앱에 연결된 카카오톡 채널이 하나일 때는 해당 카카오톡 채널의 프로필 ID가 자동으로 적용되어 별도 지정 불필요 참고: 카카오톡 채널 프로필 ID 확인 방법 중요: 앱에 연결된 카카오톡 채널이 2개 이상인 경우, 대상 카카오톡 채널의 프로필 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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정 리다이렉트 URI 등록	동의항목 설정: `talk_calendar` 앱에 카카오톡 채널 연결	에러 코드 FAQ

공개 일정을 사용자 캘린더에 추가합니다.

일정 추가 조건

앱과 연결된 카카오톡의 공개 일정만 사용자 캘린더에 추가 가능
공개 일정이 변경 또는 삭제되면 사용자 캘린더에 추가된 공개 일정도 변경 또는 삭제될 수 있음
공개 일정에 색상(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`	어드민 키

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

구독 가능 캘린더 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
category_name	`String`	목록을 가져올 구독 가능 캘린더의 대분류 카테고리(기본값: 모든 카테고리) 주의: `subcategory_name`를 지정한 경우 필수	X
subcategory_name	`String`	목록을 가져올 구독 가능 캘린더의 소분류 카테고리(기본값: 모든 카테고리)	X

응답

본문

이름	타입	설명	필수
categories	`Category[]`	카테고리별로 분류된 구독 가능 캘린더 목록	O

Subcategory

이름	타입	설명	필수
subcategory_name	`String`	소분류 카테고리 이름, 소분류 카테고리 이름이 없는 경우 미포함	X
calendars	`Calendar[]`	소분류 카테고리로 분류된 구독 가능 캘린더 목록	O

Calendar

이름	타입	설명	필수
id	`String`	구독 가능 캘린더 ID	O
name	`String`	구독 가능 캘린더 이름	O
profile_image_url	`String`	구독 가능 캘린더 프로필 URL, 프로필 이미지가 없는 경우 미포함	X

예제

요청

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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

구독 가능 캘린더를 사용자 캘린더에 추가해 구독하도록 설정합니다.

요청

헤더

이름	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자가 구독 중인 캘린더를 구독 해제합니다.

요청

헤더

이름	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: `talk_calendar`	에러 코드 FAQ

사용자의 게스트 일정 정보를 수정합니다.

참고 사항

게스트 일정은 제한된 정보만 수정할 수 있으며 원본 일정의 정보에 영향을 주지 않습니다. 직접 생성한 일정을 수정하려면 일반 일정 > 수정을 호출합니다.
기존 값 제거 방법은 기존 값 제거 시 파라미터 타입별 요청 값을 참고합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
event_id	`String`	일정 ID	O
calendar_id	`String`	캘린더 ID(기본값: 기존 유지) 주의: `event`를 포함하지 않은 경우 필수	X
event	`EventGuest`	수정할 게스트 일정 정보, EventGuest 참고	X

EventGuest

이름	타입	설명	필수
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`	어드민 키

요구 사항	참고
-	에러 코드 FAQ

법정공휴일과 톡캘린더 서비스에서 지정한 일부 기념일 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
from	`String`	일정을 조회할 기간의 시작 시각(UTC 기준 RFC3339 형식, 예: `2022-05-17T12:00:00Z`)	O
to	`String`	일정을 조회할 기간의 종료 시각, `from` 이후 31일 이내의 값(UTC 기준 RFC3339 형식, 예: `2022-06-17T12:00:00Z`)	O

응답

본문

이름	타입	설명	필수
events	`EventSpecial[]`	가져온 공휴일 및 주요 기념일 목록	O

EventSpecial

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

할 일을 생성합니다.

반복 할 일은 한 건으로 표시되며, 현재 시간이 기한 일자를 지나면 다음 반복일로 기한 일자가 자동 수정됩니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
task	`Task`	할 일 정보	O

Task

이름	타입	설명	필수
content	`String`	내용(최대 1,000자)	O
due_info	`DueInfo`	기한 일자 정보(기본값: 기한 없음)	X

DueInfo

이름	타입	설명	필수
due_date	`String`	기한 일자, `yyyyMMdd` 형식(최대: `20501231`) 주의: 과거 시점으로 설정 불가	O
time_zone	`String`	기한 일자의 타임존(IANA 타임존 데이터베이스의 이름, 기본값: `Asia/Seoul`)	X
alarm_time	`String`	알림 시각, 5분 간격의 `HHmm` 형식(단위: 분, 기본값: 알림 없음)	X
recur	`Recur`	할 일의 반복 정보 포함 시 기한 일자부터 일정한 주기를 갖는 반복 할 일 생성, 미포함 시 한 번으로 끝나는 일반 할 일 생성(기본값: 반복 없음)	X

Recur

이름	타입	설명	필수
rrule	`String`	할 일의 반복 주기(RFC5545의 `RRULE` 형식, 예: `FREQ=DAILY;UNTIL=20211208T155959Z`) `UNTIL`은 `yyyyMMdd'T'000000Z`형식으로 `due_date` 이후 `rrule` 조건을 만족하는 날짜 하루 이상 지정 필요(최대: `20501231T000000Z`)	O
record_on	`Boolean`	[도전 기록 보기] 활성화 여부 `true`: 활성화 `false`: 비활성화(기본값)	X

응답

본문

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

할 일 정보를 반환합니다.

요청

헤더

이름	설명	필수
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`	기한 일자의 타임존(IANA 타임존 데이터베이스의 이름, 기본값: `Asia/Seoul`) 중요: 응답의 `status` 시각 계산 기준	X

응답

본문

이름	타입	설명	필수
tasks	`Task[]`	할 일 정보 목록 여러 건 조회 시 최근 수정 순서로 정렬 반복 할 일은 한 건으로 표시되며, 현재 시간이 기한 일자를 지나면 다음 반복일로 기한 일자 자동 수정	O
count	`Integer`	조회 범위 내 할 일 전체 개수, `limit`로 지정한 숫자 까지만 목록에 포함하며 미포함된 할 일 목록은 `after_url`로 조회 가능	O
has_next	`Boolean`	다음 목록 존재 여부	O
after_url	`String`	다음 페이지 URL 다음 페이지를 조회하기 위한 파라미터와 값을 포함한 URL이므로, 다음 페이지 요청 시 그대로 사용, 예제 참고 제공 조건: 응답의 `has_next` 값이 `true`인 경우	X

Task

이름	타입	설명	필수
task_id	`String`	할 일 ID	O
content	`String`	내용	O
status	`String`	할 일의 상태 `SCHEDULED`: 기한 일자 경과 전 `COMPLETED`: 완료 `DELAYED`: 기한 일자 경과	O
bookmark	`Boolean`	즐겨찾기 추가 여부	O
authorized	`Boolean`	수정 또는 삭제 가능 여부	O
due_info	`DueInfo`	기한 일자 정보	X

DueInfo

이름	타입	설명	필수
due_date	`String`	기한 일자, `yyyyMMdd` 형식	O
alarm_time	`String`	알림 시각, 5분 간격의 `HHmm` 형식(단위: 분)	X
recur	`Recur`	할 일의 반복 정보	X

Recur

이름	타입	설명	필수
rrule	`String`	할 일의 반복 주기(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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

특정 반복 할 일의 도전 기록을 반환합니다.

[도전 기록 보기]를 활성화한 할 일만 확인 가능합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
task_id	`String`	할 일 ID	O
from	`String`	조회 기간의 시작 연월, `yyyyMM` 형식	O
to	`String`	조회 기간의 종료 연월, `yyyyMM` 형식	O

응답

본문

이름	타입	설명	필수
records	`Record[]`	도전 기록 정보 목록, 완료 또는 실패 기록이 없거나 반복 할 일이 아닌 경우 빈 배열로 응답	X
start_at	`String`	도전 기록 시작 연월, `yyyyMM` 형식 중요: 도전 기록이 존재하는 경우만 응답에 포함	X
end_at	`String`	도전 기록 종료 연월, `yyyyMM` 형식 중요: 도전 기록이 존재하는 경우만 응답에 포함	X

Record

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

특정 할 일의 정보를 수정합니다.

카카오톡 프로필 스티커에 등록된 할 일은 수정할 수 없습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
task_id	`String`	할 일 ID	O
task	Task	할 일 정보	O

Task

이름	타입	설명	필수
content	`String`	내용(최대 1,000자, 기본값: 기존 유지)	X
bookmark	`Boolean`	북마크 설정 여부(기본값: 기존 유지)	X
due_info	`DueInfo`	기한 일자 정보(기본값: 기존 유지) `null` 전달 시 반복 정보도 함께 삭제되며 [도전 기록 보기] 비활성화	X

DueInfo

이름	타입	설명	필수
due_date	`String`	기한 일자, `yyyyMMdd` 형식(기본값: 기존 유지, 최대: `20501231`) 주의: 과거 시점으로 설정 불가	X
time_zone	`String`	기한 일자의 타임존(IANA 타임존 데이터베이스의 이름, 기본값: 기존 유지)	X
alarm_time	`String`	알림 시각, 5분 간격의 `HHmm` 형식(단위: 분, 기본값: 기존 유지)	X
recur	`Recur`	할 일의 반복 정보(기본값: 기존 유지)	X

Recur

이름	타입	설명	필수
rrule	`String`	할 일의 반복 주기(RFC5545의 `RRULE` 형식, 예: `FREQ=DAILY;UNTIL=20211208T155959Z`) `UNTIL`은 `yyyyMMdd'T'000000Z`형식으로 `due_date` 이후만 지정 가능하며 `rrule` 조건을 만족하는 날짜 하루 이상 필요(기본값: 기존 유지, 최대: `20501231T000000Z`)	X
record_on	`Boolean`	[도전 기록 보기] 활성화 여부(기본값: 기존 유지) `true`: 활성화 `false`: 비활성화	X

응답

본문

이름	타입	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

특정 할 일의 완료 여부를 설정합니다.

요청

헤더

이름	설명	필수
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`	액세스 토큰

요구 사항		참고
사용 권한 보유 카카오 로그인 사용 설정	리다이렉트 URI 등록 동의항목 설정: 이용 정책 참고	에러 코드 FAQ

특정 할 일을 삭제합니다.

카카오톡 프로필 스티커에 등록된 할 일은 삭제할 수 없습니다.

요청

헤더

이름	설명	필수
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}"
}

공통 파라미터

Location

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

Time

API별 필수 파라미터
- 일반 일정 > 생성: start_at, end_at
API별 기본값
- 일반 일정 > 생성
  - time_zone: Asia/Seoul
- 일반 일정 > 편집하기
  - start_at, end_at, time_zone, all_day, lunar: 기존 유지

이름	타입	설명	필수
start_at	`String`	일정 시작 시각, 5분 간격으로 설정 가능(UTC 기준 RFC3339 형식, 최대: `2050-12-31T14:50:00Z`) 주의: `all_day`가 `true`인 경우 `YYYY-MM-DDT00:00:00Z` 형식으로 지정 필요(다른 값 지정 시 에러 발생)	X
end_at	`String`	일정 종료 시각, `start_at`과 같은 형식, `start_at` 보다 미래 시점의 값 (최대: `2050-12-31T14:55:00Z`) 주의: `all_day`가 `true`인 경우 `YYYY-MM-DDT00:00:00Z`으로 설정 필요(다른 값 설정 시 에러 발생)	X
time_zone	`String`	타임존 설정(IANA 타임존 데이터베이스의 이름, 기본값: `Asia/Seoul`)	X
all_day	`Boolean`	종일 일정 여부(기본값: `false`)	X
lunar	`Boolean`	날짜 기준을 음력으로 설정(기본값: `false`)	X

TimeDefault

이름	타입	설명	필수
start_at	`String`	일정 시작 시각(UTC 기준 RFC3339 형식, 최대: `2050-12-31T14:50:00Z`)	O
end_at	`String`	일정 종료 시각, `start_at`과 같은 형식, `start_at` 보다 미래 시점의 값 (최대: `2050-12-31T14:55:00Z`)	O
all_day	`Boolean`	종일 일정 여부(기본값: `false`)	X

Color

파라미터에는 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

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

REST API

시작하기 전에

캘린더 및 일정 ID 확인

캘린더 ID 확인

일정 ID 확인

캘린더 메시지 전송

사용자 캘린더

목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

Calendar

Subscribe

예제

요청

응답

서브 캘린더 생성

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

서브 캘린더 수정

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

서브 캘린더 삭제

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

일반 일정

생성

기본 정보

요청

헤더

본문

EventCreate

응답

본문

예제

요청

응답

목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

EventBrief