REST API

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

일정 조회

기본 정보

메서드	호스트	Internal URL	External URL
`GET`	`kapi.kakao.com`	`/v1/internal/talk/calendar/events`	`/v1/api/talk/calendar/events`

권한	카카오 로그인 연결 상태	동의항목 설정	동의항목
필요	연결	카카오톡 일정 등록	필요

사용자의 톡캘린더 일정을 가져옵니다.

헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 사용자의 톡캘린더 일정 목록을 받습니다.

요청 시 from과 to 파라미터를 필수 전달해야 합니다. from 파라미터에 지정된 일시부터 to 파라미터에 지정된 일시까지의 기간을 대상으로 조회합니다. 일정은 업데이트된 시간 순서로 정렬됩니다.

응답은 최대 1,000개의 일정을 포함하며, 이를 초과하는 일정은 응답의 revision 값을 사용해 이어서 조회할 수 있습니다.

요청

헤더

이름	형식	설명
액세스 토큰 방식	`Authorization: Bearer ${ACCESS_TOKEN}`	서비스 앱에서 액세스 토큰으로 요청합니다.
서비스 앱 어드민 키 방식	Authorization: `KakaoAK ${SERVICE_APP_ADMIN_KEY}`	서비스 앱에서 어드민 키와 사용자 ID로 요청합니다.
위임 방식	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}`	내부 API 요청 시 사용 가능합니다. 서비스 앱 대신 위임(Delegation) 받은 플랫폼 앱이 대신 요청합니다. 서비스 앱 어드민 키가 아닌 플랫폼 앱 어드민 키를 사용합니다. 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나를 파라미터로 전달해 대상을 명시해야 합니다.

파라미터: 액세스 토큰 방식

이름	타입	설명	필수
from	`datetime`	일정을 조회할 기간의 시작 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
to	`datetime`	일정을 조회할 기간의 종료 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
limit	`Integer`	요청으로 받을 최대 일정 수 기간 내 최대값 이상의 일정이 존재할 경우 이후 결과를 조회할 때 사용할 `revision` 포함(최대 1,000)	X
revision	`Long`	마지막으로 일정을 조회한 시간 이전 요청 응답에서 받은 `revision` 값, 기본값일 경우 기간에 포함된 모든 일정 제공(기본값: 0)	X
holiday	`Boolean`	공휴일 정보 포함 여부 미지정 시 공휴일을 포함하지 않음	X

파라미터: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

이름	타입	설명	필수
target_id	`String`	일정을 조회할 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
from	`datetime`	일정을 조회할 기간의 시작 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
to	`datetime`	일정을 조회할 기간의 종료 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
limit	`Integer`	요청으로 받을 최대 일정 수 기간 내 최대값 이상의 일정이 존재할 경우 이후 결과를 조회할 때 사용할 `revision` 포함(최대 1,000)	X
revision	`Long`	마지막으로 일정을 조회한 시간 이전 요청 응답에서 받은 `revision` 값, 기본값일 경우 기간에 포함된 모든 일정 제공(기본값: 0)	X
holiday	`Boolean`	공휴일 정보 포함 여부 미지정 시 공휴일을 포함하지 않음	X

파라미터: 위임 방식

내부 API 요청 시에만 사용 가능합니다.
요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	일정 조회를 요청하는 서비스 앱의 키	O(Optional)
target_app_id	`String`	일정 조회를 요청하는 서비스 앱의 ID	O(Optional)
target_access_token	`String`	일정을 조회할 사용자의 액세스 토큰	O(Optional)
target_id	`String`	일정을 조회할 사용자의 ID	O(Optional)
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`:카카오톡 회원번호	O(Optional)
from	`datetime`	일정을 조회할 기간의 시작 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
to	`datetime`	일정을 조회할 기간의 종료 시각 `from`과 `to` 사이의 기간은 30일 이내여야 함(RFC3339 internet date/time 형식)	O
limit	`Integer`	요청으로 받을 최대 일정 수 기간 내 최대값 이상의 일정이 존재할 경우 이후 결과를 조회할 때 사용할 `revision` 포함(최대 1,000)	X
revision	`Long`	마지막으로 일정을 조회한 시간 이전 요청 응답에서 받은 `revision` 값, 기본값일 경우 기간에 포함된 모든 일정 제공(기본값: 0)	X
holiday	`Boolean`	공휴일 정보 포함 여부 미지정 시 공휴일을 포함하지 않음	X

응답

이름	타입	설명	필수
events	`EventResult[]`	가져온 일정 목록	O
holidays	`EventResult[]`	가져온 공휴일 목록 페이징(Paging) 없이 첫 번째 요청의 기간 내 모든 공휴일 정보 포함 제공 조건: 요청 시 `holiday` 파라미터 값을 `true`로 지정한 경우	X
after_url	`String`	다음 페이지 URL	O
hasNext	`Boolean`	다음 페이지가 있는지 여부	O

EventResult

이름	타입	설명	필수
event_id	`String`	등록된 이벤트 ID	O
subject	`String`	일정 제목(최대 100자)	O
start_at	`Datetime`	일정 시작 시각(RFC3339 internet date/time 형식)	O
end_at	`Datetime`	일정 종료 시각(RFC3339 internet date/time 형식)	O
all_day	`Boolean`	하루 종일로 설정된 일정인지 여부	O
rrule	`String`	반복 일정인 경우 반복 주기 규칙 일정은 RFC3339 internet date/time 형식을 따름	X
dt_start	`String`	반복 일정인 경우 반복 일정의 시작 시간	X
location	`Location`	장소 공휴일 일정인 경우 미포함	X
remainders_minutes	`Integer[]`	미리알림 시간, 최대 2개이며 분 단위 시간 간격을 의미 일정([0, 5, 15, 30, 60, 1440, 2880, 10080]) 또는 종일일정([-540, -720, 900, 2340]), 지정된 시간 전에 사용자 알림(예: 5분 전, 10분 전), 공휴일 일정인 경우 미포함 아래 `remainders_minutes` 표 참고	X
attend	`Integer`	참석 여부, 공휴일 일정인 경우 미포함	X
lunar	`Boolean`	음력 여부(기본값: `false`(양력))	O
note	`String`	일정 설명, 공휴일 일정인 경우 미포함	X
memo	`String`	일정 메모, 사용자가 초대 받은 일정에만 존재 공휴일 일정인 경우 미포함	X
color	`String`	일정 색상, 일정 작성자에게만 적용 공휴일 일정인 경우 미포함	X
holiday	`Boolean`	공휴일 일정인지 여부 공휴일인 경우에만 `true`로 포함	X

Location

이름	타입	설명
name	`String`	장소 이름
cId	`Interger`	장소 ID
addr	`String`	주소
lat	`Double`	위도
lng	`Double`	경도

remainders_minutes

값	설명
0	정시
5	5분 전
15	15분 전
30	30분 전
60	1일 전
2880	2일 전
10080	1주일 전
-720	종일 일정, 당일 12시 알림
-540	종일 일정, 당일 오전 9시 알림
-900	종일 일정, 1일 전 9시 알림
-2340	종일 일정, 2일 전 9시 알림

예제

요청: 액세스 토큰 방식

파라미터
- 일정을 조회할 기간의 시작 시각(from)
- 일정을 조회할 기간의 종료 시각(to)

curl -v --get "http://kapi.kakao.com/v1/internal/talk/calendar/events" \
    --data-urlencode "from=2019-08-20T21:00:00Z" \
    --data-urlencode "to=2019-08-22T21:00:00Z" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

요청: 서비스 앱 어드민 키 방식

파라미터
- 일정을 조회할 기간의 시작 시각(from)
- 일정을 조회할 기간의 종료 시각(to)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v --get "http://kapi.kakao.com/v1/internal/talk/calendar/events?target_id=1376016924426684995&target_id_type=user_id" \
    --data-urlencode "from=2019-08-20T21:00:00Z"
    --data-urlencode "to=2019-08-22T21:00:00Z" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

응답

{
  "events": [
    {
      "id": "chPUF5MFVwTfIwjMXjX",
      "subject": "아침운동",
      "start_at": "2019-08-20T21:00:00Z",
      "end_at": "2019-08-2022T:00:00Z",
      "all_day": false,
      "lunar": false,
      "attend": 1,
      "color": "FFFFFF",
      "remainders_minutes": [0, 1440],
      "note": "운동을 열심히"
    }

    // ...
  ],
  "holidays": [
    {
      // ...
    }
    // ...
  ],
  "after_url": "http://kapi.kakao.com/v1/internal/talk/calendar/events?from=2019-08-20T07:00:00+09:00&to=2019-09-19T08:00:00+09:00&holiday=true&limit=10&revision=1555647102278",
  "has_next": false
}

일정 등록하기

기본 정보

메서드	호스트	Internal URL	External URL
`POST`	`kapi.kakao.com`	`/v1/internal/talk/calendar/create/events`	`/v1/api/talk/calendar/create/events`

권한	카카오 로그인 연결 상태	동의항목 설정	동의항목
필요	연결	카카오톡 일정 등록	필요

사용자의 톡캘린더에 일정을 등록합니다.

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 등록된 일정 ID를 받습니다. 등록할 일정의 내용은 event 파라미터로 전달합니다.

Content-Type이 application/x-www-form-urlencoded인 경우 event 파라미터 이름과 값을 필수 전달해야 하며, application/json인 경우 일정 내용을 요청 바디(Body)에 JSON 객체로 포함해야 합니다.

요청

헤더

이름	형식	설명
액세스 토큰 방식	`Authorization: Bearer ${ACCESS_TOKEN}`	서비스 앱에서 액세스 토큰으로 요청합니다.
서비스 앱 어드민 키 방식	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}`	서비스 앱에서 어드민 키와 사용자 ID로 요청합니다.
위임 방식	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}`	내부 API 요청 시 사용 가능합니다. 서비스 앱 대신 위임(Delegation) 받은 플랫폼 앱이 대신 요청합니다. 서비스 앱 어드민 키가 아닌 플랫폼 앱 어드민 키를 사용합니다. 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나를 파라미터로 전달해 대상을 명시해야 합니다.

파라미터: 액세스 토큰 방식

이름	타입	설명	필수
event	`Event`	등록할 일정의 상세 내용	X

Event

이름	타입	설명	필수
subject	`String`	일정 이름(최대 100자)	O
start_at	`Datetime`	일정 시작 시각(RFC3339 internet date/time 형식)	O
end_at	`Datetime`	일정 종료 시각(RFC3339 internet date/time 형식)	O
all_day	`Boolean`	하루 종일로 설정된 일정인지 여부	X
location	`Location`	장소	X
remainders_minutes	`Integer[]`	미리알림 시간, 최대 2개이며 분 단위 시간 간격을 의미 일정([0, 5, 15, 30, 60, 1440, 2880, 10080]) 또는 종일일정([-540, -720, 900, 2340]), 지정된 시간 전에 사용자 알림(예: 5분 전, 10분 전)	X
attendees	`Integer[]`	일정에 초대할 친구 목록	X
lunar	`Boolean`	음력 여부(기본값: `false`(양력))	X
note	`String`	일정 설명	X
color	`String`	일정 색상, 일정 작성자에게만 적용	X

Location

이름	타입	설명
name	`String`	장소 이름
cId	`Integer`	장소 ID
addr	`String`	주소
lat	`Double`	위도
lng	`Double`	경도

파라미터: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

이름	타입	설명	필수
target_id	`String`	일정을 등록할 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
event	`Event`	등록할 일정의 상세 내용	X

파라미터: 위임 방식

내부 API 요청 시에만 사용 가능합니다.
요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	일정 등록을 요청하는 서비스 앱의 키	O(Optional)
target_app_id	`String`	일정 등록을 요청하는 서비스 앱의 ID	O(Optional)
target_access_token	`String`	일정을 등록할 사용자의 액세스 토큰	O(Optional)
target_id	`String`	일정을 등록할 사용자의 ID	O(Optional)
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`:카카오톡 회원번호	O(Optional)
event	`Event`	등록할 일정의 상세 내용	X

응답

이름	타입	설명	필수
id	`String`	등록한 일정의 ID	O

예제

요청: 액세스 토큰 방식

파라미터: 일정 내용, JSON 객체
Content-Type: application/json

curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/calendar/create/events" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
            "subject":"아침운동",
            "start_at":"2019-08-20T07:00:00+09:00",
            "end_at":"2019-08-20T08:00:00+09:00",
            "remainders_minutes":[0,1440],
            "attendees":[12345],
            "all_day": false,
            "lunar": false,
            "note": "운동을 열심히",
            "color": "FFFFFF"
        }'

요청: 서비스 앱 어드민 키 방식

파라미터
- 일정 내용(event)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)
Content-Type: application/x-www-form-urlencoded

curl -v -X POST "http://kapi.kakao.com/v1/internal/talk/calendar/create/events" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id=1376016924426684995" \
    -d "target_id_type=user_id" \
    --data-urlencode 'event={
            "subject":"아침운동",
            "start_at":"2019-08-20T07:00:00+09:00",
            "end_at":"2019-08-20T08:00:00+09:00",
            "remainders_minutes":[0,1440],
            "attendees":[12345],
            "all_day": false,
            "lunar": false,
            "note": "운동을 열심히",
            "color": "FFFFFF"
        }'

응답

{
  "id": "5be52b88c7defc122ba0a257"
}

일정 삭제하기

기본 정보

메서드	호스트	Internal URL	External URL
`DELETE`	`kapi.kakao.com`	`/v1/internal/talk/calendar/delete/events`	`/v1/api/talk/calendar/delete/events`

권한	카카오 로그인 연결 상태	동의항목 설정	동의항목
필요	연결	카카오톡 일정 등록	필요

사용자의 카카오톡의 톡 캘린더 일정을 삭제합니다.

헤더에 원하는 인증 정보를 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200 OK 응답을 받으며 응답 바디는 없습니다.

요청

헤더

이름	형식	설명
액세스 토큰 방식	`Authorization: Bearer ${ACCESS_TOKEN}`	서비스 앱에서 액세스 토큰으로 요청합니다.
서비스 앱 어드민 키 방식	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}`	서비스 앱에서 어드민 키와 사용자 ID로 요청합니다.
위임 방식	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}`	내부 API 요청 시 사용 가능합니다. 서비스 앱 대신 위임(Delegation) 받은 플랫폼 앱이 대신 요청합니다. 서비스 앱 어드민 키가 아닌 플랫폼 앱 어드민 키를 사용합니다. 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나를 파라미터로 전달해 대상을 명시해야 합니다.

파라미터: 액세스 토큰 방식

이름	타입	설명	필수
event_id	`String`	삭제할 일정 ID	O

파라미터: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

이름	타입	설명	필수
target_id	`String`	일정을 삭제할 사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
event_id	`String`	삭제할 일정 ID	O

파라미터: 위임 방식

내부 API 요청 시에만 사용 가능합니다.
요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	일정 삭제를 요청하는 서비스 앱의 키	O(Optional)
target_app_id	`String`	일정 삭제를 요청하는 서비스 앱의 ID	O(Optional)
target_access_token	`String`	일정을 삭제할 사용자의 액세스 토큰	O(Optional)
target_id	`String`	일정을 삭제할 사용자의 ID	O(Optional)
target_id_type	`String`	`target_id`의 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`:카카오톡 회원번호	O(Optional)
event_id	`String`	삭제할 일정 ID	O

예제

요청: 액세스 토큰 방식

파라미터: 삭제할 일정 ID(event_id)

curl -v -G -X DELETE "http://kapi.kakao.com/v1/internal/talk/calendar/delete/events" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "event_id=5be52b88c7defc122ba0a257"

요청: 서비스 앱 어드민 키 방식

파라미터
- 삭제할 일정 ID(event_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 회원번호(user_id)

curl -v -G -X DELETE "http://kapi.kakao.com/v1/internal/talk/calendar/delete/events" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "event_id=5be52b88c7defc122ba0a257" \
    -d "target_id=1376016924426684995" \
    -d "target_id_type=user_id"

응답

HTTP/1.1 200 OK

사이드 메뉴

오픈 문서

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

인공지능

플랫폼 API

API 제공

전용 API

어드민 API

더 보기

REST API

일정 조회

기본 정보

요청

헤더

파라미터: 액세스 토큰 방식

파라미터: 서비스 앱 어드민 키 방식

파라미터: 위임 방식

응답

EventResult

Location

remainders_minutes

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

응답

일정 등록하기

기본 정보

요청

헤더

파라미터: 액세스 토큰 방식

Event

Location

파라미터: 서비스 앱 어드민 키 방식

파라미터: 위임 방식

응답

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

응답

일정 삭제하기

기본 정보

요청

헤더

파라미터: 액세스 토큰 방식

파라미터: 서비스 앱 어드민 키 방식

파라미터: 위임 방식

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

응답

도움이 되었나요?

REST API

일정 조회

일정 등록하기

일정 삭제하기