페이지 이동경로
  • 문서>
  • 톡캘린더>
  • REST API

톡캘린더

REST API

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

시작하기 전에

캘린더 및 일정 ID 확인

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

캘린더 ID 확인
캘린더 종류 ID 확인 방법
기본 캘린더 primary로 고정
서브 캘린더 1. 사용자 캘린더 > 목록 가져오기를 요청해 서브 캘린더 목록 확인
2. 목록 내 캘린더 정보를 참고해 서브 캘린더 ID 확인(서비스가 생성하지 않은 캘린더는 ID만 확인 가능)
구독 캘린더 1. 구독 캘린더 > 구독 가능 캘린더 목록 가져오기를 요청해 구독 가능 캘린더 목록 확인
2. 목록 내 캘린더 정보를 참고해 구독 캘린더 ID 확인
일정 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
Calendar
  • 캘린더 생성/편집 시 값을 입력한 항목만 응답에 포함
이름 타입 설명 필수
id String 캘린더 ID
기본 캘린더의 경우 primary로 고정
O
name String 캘린더 이름

비고: 서비스에서 만든 캘린더인 경우 필수
X
color String 캘린더 일정의 기본 색상, Color 중 하나

비고: 서비스에서 만든 캘린더인 경우 필수
X
reminder Integer 종일 일정이 아닌 일정의 기본 알림 시간 X
reminder_all_day Integer 종일 일정의 기본 알림 시간 X
Subscribe
  • 캘린더 생성/편집 시 값을 입력한 항목만 응답에 포함
이름 타입 설명 필수
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 종일이 아닌 일정의 기본 알림 설정 X
reminder_all_day Integer 종일 일정의 기본 알림 설정 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 종일이 아닌 일정의 기본 알림 설정 X
reminder_all_day Integer 종일 일정의 기본 알림 설정 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 -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와 일정 정보를 파라미터에 포함해야 합니다. ID를 지정하지 않으면 기본 캘린더(캘린더 ID: primary)에 일정이 생성됩니다.

rrule 파라미터를 포함하면 특정일까지 일정한 주기로 생성되는 반복 일정을, 포함하지 않으면 한 번으로 끝나는 일반 일정을 생성합니다. reminders 파라미터에 빈 리스트를 입력하면, 종일이 아닌 일정의 경우 등록된 캘린더의 reminder 값으로, 종일 일정은 reminder_all_day 값으로 설정됩니다.

요청 성공 시 응답은 생성한 일정의 ID를 포함한 JSON 객체입니다. 요청 실패 시 에러 코드로 사유를 확인합니다.

요청
헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
본문
이름 타입 설명 필수
calendar_id String 일정을 생성할 캘린더 ID(기본값: primary) X
event EventCreate 생성할 일정 정보 O
EventCreate
이름 타입 설명 필수
title String 일정 제목(최대 50자) O
time Time 일정 시간 O
rrule String 일정의 반복 주기, UTC*, RFC5545RRULE 형식(예: 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 O
from String 일정을 조회할 기간의 시작 시각, UTC*, RFC5545DATE-TIME 형식(예: 2022-05-17T12:00:00Z)

주의: next_page_token값이 있는 경우 무시됨
O
to String 일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545DATE-TIME 형식(예: 2022-06-17T12:00:00Z)

주의: next_page_token값이 있는 경우 무시됨
O
limit Integer 응답으로 받을 최대 일정 수(최대: 1000, 기본값: 100)

주의: 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
EventBriref
  • 서비스에서 만든 일정이 아닌 경우 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 반복 일정 여부

비고: typeUSER인 경우 필수
X
color String 일정 색상, 일정 생성 또는 편집 시 지정하지 않은 경우 미포함, Color 중 하나 X
예제
요청
curl -X 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 -X 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
EventDetail
이름 타입 설명 필수
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 반복 일정 여부

비고: typeUSER인 경우 필수
X
rrule String 일정의 반복 주기, UTC*, RFC5545RRULE 형식(예: FREQ=DAILY;UNTIL=20211208T155959Z) X
dt_start String 반복 일정의 시작 시각, UTC*, RFC5545DATE-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 참고

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 -X GET "https://kapi.kakao.com/v2/api/calendar/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",
        "title": "일정 제목",
        "type": "PUBLIC",
        "calendar_id": "primary",
        "time": {
            "start_at": "2022-10-21T15:00:00Z",
            "end_at": "2022-10-21T18:00:00Z",
            "all_day": false,
            "lunar": false
        },
        "is_host": false,
        "description": "공개 일정 설명",
        "location": {
            "name": "카카오",
            "location_id": 18577297,
            "address": "경기 성남시 분당구 판교역로 166",
            "latitude": 37.39570088983171,
            "longitude": 127.1104335101161
        },
        "reminders": [15, 30],
        "color": "RED",
        "memo": "test_memo",
        "banner": {
            "pc_image_url": "https://p.kakaocdn.net/th/talkp/wkbZPRnplE/QlS4bqerAYSEBGkpnYHh91/6tfwkz_640x640_s.jpg",
            "mobile_image_url": "https://p.kakaocdn.net/th/talkp/wkbZPRnplE/QlS4bqerAYSEBGkpnYHh91/6tfwkz_640x640_s.jpg",
            "bg_color": "FFFFFF",
            "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/update/event/host 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요: 사용 권한 플랫폼 등록
카카오 로그인 활성화
동의 항목
필요 필요:
톡캘린더 및 일정 생성, 조회, 편집/삭제

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

액세스 토큰을 헤더에 담아 파라미터와 함께 POST로 요청합니다. 일반 일정의 ID와 1개 이상의 수정 사항을 파라미터에 포함해야 일정 또는 일정이 등록된 캘린더를 수정할 수 있습니다.

기존 값을 제거하기 위한 파라미터 타입별 요청 값은 아래를 참고합니다.

  • String: "" (빈 문자열)
  • Integer, Long: null

요청 성공 시 응답은 반복 일정이 아닌 경우, 수정된 일정의 ID를 포함한 JSON 객체입니다. 반복 일정의 경우 본문 없이 HTTP 200 상태 코드만 반환합니다. 요청 실패 시 에러 코드로 사유를 확인합니다.

요청
헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
본문
이름 타입 설명 필수
event_id String 일정 ID O
calendar_id String 캘린더 ID(기본값: 기존 유지)

주의: event를 포함하지 않은 경우 필수
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 일정의 반복 주기, UTC*, RFC5545RRULE 형식(예: 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 -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

{
  "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 -X DELETE "https://kapi.kakao.com/v2/api/calendar/delete/event" \
    -d "event_id=63630c44d89d8b4150bbb716" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
응답
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
EventPublic
이름 타입 설명 필수
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
NotificationMessage
이름 타입 설명 필수
before_event_reminder EventReminder 일정 시작 전 알림 메시지의 사용자 정의 버튼 문구 및 링크 설정
(기본값: 기본 공유하기 버튼 적용)
X
after_event_reminder EventReminder 일정 시작 후 알림 메시지의 사용자 정의 버튼 문구 및 링크 설정
(기본값: 기본 공유하기 버튼 적용)
X
EventReminder
이름 타입 설명 필수
title String 알림 메시지의 사용자 정의 버튼 문구
다음 중 하나: 시청하기, 예매하기, 예약하기, 참여하기
O
link Link 알림 메시지의 사용자 정의 버튼 링크 정보 O
Link
이름 타입 설명 필수
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 "http://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":{
            "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
{
    "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*, RFC5545DATE-TIME 형식(예: 2022-05-17T12:00:00Z) O
to String 일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545DATE-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
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-11-11T00:00:00Z" \
    -d "limit=3"
요청, 다음 페이지 요청
curl -v GET "${AFTER_URL}" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
응답
HTTP/1.1 200 OK
{
    "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
NotificationMessage
이름 타입 설명 필수
before_event_reminder EventReminder 일정 시작 전 알림 메시지의 사용자 정의 버튼 문구 및 링크 설정 X
after_event_reminder EventReminder 일정 시작 후 알림 메시지의 사용자 정의 버튼 문구 및 링크 설정 X
EventReminder
이름 타입 설명 필수
link Link 알림 메시지의 사용자 정의 버튼 링크 정보 O
title String 알림 메시지의 사용자 정의 버튼 문구 O
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
{
    "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": {
                "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"
                }
            }
        }
    }
}

수정하기

기본 정보
메서드 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 "http://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
{
    "event_id":"637b2d3471fdf754fbbf6e94"
}

삭제하기

기본 정보
메서드 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 -X DELETE "https://kapi.kakao.com/v2/api/calendar/public/delete/event?channel_public_id=_xnrxjem&event_id=637b3bc671fdf754fbbf6f08" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
응답
HTTP/1.1 200 OK
{
    "event_id":"637b2d3471fdf754fbbf6e94"
}

사용자 캘린더에 추가하기

기본 정보
메서드 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
{
    "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
Category
이름 타입 설명 필수
name String 대분류 카테고리 이름 O
subcategories Subcategory[] 소분류 카테고리 목록 O
Subcategory
이름 타입 설명 필수
name String 소분류 카테고리 이름, 소분류 카테고리 이름이 없는 경우 미포함 X
calendars Calendars[] 소분류 카테고리로 분류된 구독 가능 캘린더 목록 O
Calendars
이름 타입 설명 필수
id String 구독 가능 캘린더 ID O
name String 구독 가능 캘린더 이름 O
profile_image_url String 구독 가능 캘린더 프로필 URL O
예제
요청
curl -v -X GET "https://kapi.kakao.com/v2/api/calendar/subscribable/calendars" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "category_name=대분류 카테고리 이름" \
    -d "subcategory_name=소분류 카테고리 이름"
응답
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 -X DELETE "https://kapi.kakao.com/v2/api/calendar/unsubscribe?calendar_id=subscribe_5efad4e3890efb10051630f2" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
응답
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
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 -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*, RFC5545DATE-TIME 형식(예: 2022-05-17T12:00:00Z) O
to String 일정을 조회할 기간의 종료 시각, from 이후 31일 이내의 값, UTC*, RFC5545DATE-TIME 형식(예: 2022-06-17T12:00:00Z) O

* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고

응답

본문
이름 타입 설명 필수
events EventSpecial[] 가져온 공휴일 및 주요 기념일 목록 O
EventSpecial
이름 타입 설명 필수
id String 일정 ID O
title String 일정 제목(최대 50자) O
time TimeDefault 일정 시간 O
holiday Boolean 공휴일 여부 O

예제

요청
curl -v -X 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
    }
  ]
}

공통 파라미터

Location

이름 타입 설명 필수
name String 장소 이름(최대 100자) X
location_id Long 장소 ID X
address String 주소 X
latitude Double 위도 X
longitude Double 경도 X

Time

이름 타입 설명 필수
start_at String 일정 시작 시각, UTC*, RFC5545DATE-TIME 형식(예: 2022-05-17T12:00:00Z)

주의: all_daytrue인 경우 YYYY-MM-DDT00:00:00Z으로 설정(다른 값 설정 시 에러 발생)
X
end_at String 일정 종료 시각, start_at과 같은 형식, start_at 보다 미래 시점의 값

주의: all_daytrue인 경우 YYYY-MM-DDT00:00:00Z으로 설정 필요(다른 값 설정 시 에러 발생)
X
time_zone String 타임존 설정, UTC*, RFC5545TZID 형식(예: Asia/Seoul) X
all_day Boolean 종일 일정 여부(기본값: false) X
lunar Boolean 날짜 기준을 음력으로 설정(기본값: false) X

* UTC: 한국 시간(KST)과 9시간 차이, RFC3339: Date and Time on the Internet 참고

TimeDefault

이름 타입 설명 필수
start_at String 일정 시작 시각, UTC*, RFC5545DATE-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 참고

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