이해하기
이 문서는 톡캘린더 API를 소개합니다.
톡캘린더는 카카오톡 채팅방에서 빠르게 일정을 만들고, 일상의 할 일을 등록해 손쉽게 관리할 수 있는 서비스입니다. 톡캘린더 API를 활용하면 사용자의 캘린더, 일정, 할 일을 추가하고 관리하는 기능을 서비스에서 제공할 수 있습니다. 카카오톡 채널 관리자는 마케팅 영역이 포함된 일정을 공유해 광고 효과를 더욱 높일 수 있습니다.
톡캘린더 API는 사용 권한이 주어진 앱에서만 사용할 수 있습니다. 사용 권한이 없는 앱 또는 테스트 앱에서는, 앱의 멤버만 호출할 수 있고 응답 범위도 해당 멤버로 제한됩니다.
아래를 참고해 사용 권한을 신청합니다.
- 동의항목을 참고해 아래 기능별 필요 동의항목 설정
- 캘린더, 일정: [톡캘린더 및 일정 생성, 조회, 편집/삭제(
talk_calendar)] - 할 일: [톡캘린더 내 할 일 생성, 조회, 편집/삭제(
talk_calendar_task)]
- 캘린더, 일정: [톡캘린더 및 일정 생성, 조회, 편집/삭제(
- 톡캘린더 API를 사용한 기능 구현
- 앱의 멤버를 대상으로 기능이 정상 동작하는지 확인
- 앱 관리 페이지의 [앱] > [추가 기능 신청]에서 사용 권한 신청
사용 권한을 받으면 서비스의 모든 사용자에게 톡캘린더 API 기능을 제공할 수 있습니다.
톡캘린더 API의 공개 일정 기능을 사용하려면 카카오톡 채널 연결이 필요합니다. 카카오톡 채널 연결 여부는 사용 권한 신청과 무관하지만, 가급적 사용 권한 신청 시 미리 설정과 동작을 확인할 것을 권장합니다.
톡캘린더는 캘린더에 일정을 추가하고 관리합니다. 캘린더는 사용자 캘린더, 공유 캘린더, 구독 캘린더가 있습니다. 공유 캘린더 관련 API는 추후 지원 예정입니다.
[A] 기본 캘린더
[B] 서브 캘린더
[C] 공유 캘린더(지원 예정)
[D] 사용자가 구독한 구독 캘린더
캘린더 관계
사용자가 관리하는 캘린더입니다. 기본 캘린더, 서브 캘린더, 구독한 구독 캘린더가 있습니다.
| 캘린더 종류 | 설명 |
|---|---|
| 기본 캘린더 | 카카오계정 단위로 기본 제공, 추가 또는 삭제 불가 |
| 서브 캘린더 | 사용자가 일정을 구분해 관리하기 위해 추가로 생성한, 기본 캘린더와 같은 기능의 캘린더 서비스는 한 사용자에게 최대 3개까지 서브 캘린더를 생성 가능 사용자별 서브 캘린더의 최대 갯수: 99개 한 서비스에서 같은 이름 중복 생성 불가 |
| 구독 캘린더 | 구독 캘린더를 구독하면 사용자 캘린더에 추가됨 |
카카오톡 채널 관리자가 발행하고 관리하는 관심사 기반의 캘린더입니다. 사용자는 구독 캘린더를 구독해 일정을 확인하고 관리할 수 있습니다.
톡캘린더의 일정은 용도에 따라 구분되며, 사용 가능한 기능에 차이가 있습니다.
사용자가 직접 사용자 캘린더에 추가, 수정, 삭제할 수 있는 일정입니다. 구독 캘린더에는 추가할 수 없습니다.
카카오톡 채널이 주체가 되어 마케팅(Marketing) 목적으로 만든 일정입니다. 공개 일정을 생성하려면 카카오톡 채널 연결이 필요합니다. 생성한 공개 일정을 사용자의 특정 캘린더에 추가해 사용자의 게스트 일정으로 만들 수 있습니다.
카카오톡 채널에 대한 자세한 내용은 카카오톡 채널을 참고합니다.
구독 캘린더 내의 일정입니다. 구독 캘린더를 구독하면 해당 캘린더 내 모든 구독 일정은 게스트 일정이 됩니다.
사용자의 특정 캘린더에 추가된 공개 일정입니다. 사용자는 게스트 일정을 제한적으로 수정할 수 있으며, 수정 사항은 사용자의 캘린더에만 반영됩니다. 채널에서 직접 공개 일정 > 수정으로 수정한 공개/구독 일정의 변경 사항은 사용자 캘린더의 게스트 일정에도 반영됩니다.
사용자가 해야할 일의 세부 내용을 작성해 할 일로 등록할 수 있습니다. 필요에 따라 시간 정보와 완료 기록을 확인할 수 있는 [도전 기록 보기]를 설정하면 할 일을 누락 없이 완료하도록 관리할 수 있습니다.
등록한 할 일은 조회, 수정, 삭제할 수 있습니다. 카카오톡 프로필 스티커에 등록된 할 일은 삭제할 수 없습니다.
톡캘린더 API 사용 서비스는 사용자가 카카오톡 나와의 채팅 또는 친구에게 캘린더 메시지를 보내는 기능을 구현할 수 있습니다. 캘린더 메시지는 서비스의 구독 캘린더나 공개 일정을 사용자 캘린더에 추가하는 기능을 제공합니다.
현재 캘린더 메시지는 카카오톡 메시지 API와 카카오톡 공유 API로 전송 가능합니다. 캘린더 메시지 사용 방법은 아래 문서에서 확인할 수 있습니다.
- 메시지: 카카오톡 메시지 API 기능 소개, 이용 정책 안내
- 메시지 템플릿: 캘린더 메시지 구성 요소 안내, 현재 기본 템플릿만 지원
- 카카오톡 메시지, 카카오톡 공유: 캘린더 메시지 기본 템플릿을 사용한 메시지 전송 방법 안내
- 카카오톡 소셜: 사용자의 친구에게 카카오톡 메시지를 보내고자 할 경우, 카카오톡 친구 정보를 받아오는 기능 안내
카카오 API는 원활한 서비스 제공을 위해 월간 및 일간 쿼터(Quota)를 적용합니다. 현재 적용 중인 쿼터 정보는 쿼터에서 확인할 수 있습니다. 적용된 쿼터 한도를 상향하기 위해서는 협의 및 제휴가 필요하므로 별도 문의합니다.
단, 톡캘린더 API는 할당된 사용량을 늘리려면 사용 권한 신청이 필요합니다. 사용 권한을 받기 전에는 테스트를 위해 제한적으로 API를 사용할 수 있습니다.
각 API의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.
| API | 메서드 | URL | 설명 |
|---|---|---|---|
| 목록 조회 | GET | https://kapi.kakao.com/v2/api/calendar/calendars | 사용자 캘린더의 목록을 가져옵니다. |
| 서브 캘린더 생성 | POST | https://kapi.kakao.com/v2/api/calendar/create/calendar | 사용자 캘린더에 새로운 서브 캘린더를 생성합니다. |
| 서브 캘린더 수정 | POST | https://kapi.kakao.com/v2/api/calendar/update/calendar | 사용자의 특정 서브 캘린더 설정을 수정합니다. |
| 서브 캘린더 삭제 | DELETE | https://kapi.kakao.com/v2/api/calendar/delete/calendar | 사용자의 특정 서브 캘린더를 삭제합니다. |
| 생성 | POST | https://kapi.kakao.com/v2/api/calendar/create/event | 사용자의 특정 캘린더에 일반 일정을 생성합니다. |
| 목록 조회 | GET | https://kapi.kakao.com/v2/api/calendar/events | 특정 캘린더에 등록된 일정 목록을 가져옵니다. |
| 상세 조회 | GET | https://kapi.kakao.com/v2/api/calendar/event | 사용자의 일반 일정 정보를 조회합니다. |
| 수정 | POST | https://kapi.kakao.com/v2/api/calendar/update/event/host | 사용자의 일반 일정 정보를 수정합니다. |
| 삭제 | DELETE | https://kapi.kakao.com/v2/api/calendar/delete/event | 사용자의 일반 일정을 삭제합니다. |
| 생성 | POST | https://kapi.kakao.com/v2/api/calendar/public/create/event | 카카오톡 채널의 공개 일정을 생성합니다. |
| 목록 조회 | GET | https://kapi.kakao.com/v2/api/calendar/public/events | 카카오톡 채널의 등록된 공개 일정 목록을 가져옵니다. |
| 상세 조회 | GET | https://kapi.kakao.com/v2/api/calendar/public/event | 카카오톡 채널의 공개 일정 정보를 조회합니다. |
| 수정 | POST | https://kapi.kakao.com/v2/api/calendar/public/update/event | 카카오톡 채널의 공개 일정 정보를 수정합니다. |
| 삭제 | DELETE | https://kapi.kakao.com/v2/api/calendar/public/delete/event | 카카오톡 채널의 공개 일정을 삭제합니다. |
| 사용자 캘린더에 추가 | POST | https://kapi.kakao.com/v2/api/calendar/public/follow | 공개 일정을 사용자 캘린더에 추가합니다. |
| 구독 가능 캘린더 목록 조회 | GET | https://kapi.kakao.com/v2/api/calendar/subscribable/calendars | 구독 가능 캘린더 목록을 가져옵니다. |
| 구독 | POST | https://kapi.kakao.com/v2/api/calendar/subscribe | 구독 가능 캘린더를 사용자 캘린더에 추가해 구독하도록 설정합니다. |
| 구독 해제 | DELETE | https://kapi.kakao.com/v2/api/calendar/unsubscribe | 사용자가 구독 중인 캘린더를 구독 해제합니다. |
| 수정 | POST | https://kapi.kakao.com/v2/api/calendar/update/event/guest | 사용자의 게스트 일정 정보를 수정합니다. |
| 공휴일 및 주요 기념일 조회 | GET | https://kapi.kakao.com/v2/api/calendar/holidays | 법정공휴일과 톡캘린더 서비스에서 지정한 일부 기념일 목록을 조회합니다. |
| 생성 | POST | https://kapi.kakao.com/v1/api/calendar/create/task | 할 일을 생성합니다. |
| 조회 | GET | https://kapi.kakao.com/v1/api/calendar/tasks | 할 일 정보를 조회합니다. |
| 도전 기록 조회 | GET | https://kapi.kakao.com/v1/api/calendar/task/records | 특정 반복 할 일의 도전 기록을 확인합니다. |
| 수정 | POST | https://kapi.kakao.com/v1/api/calendar/update/task | 특정 할 일의 정보를 수정합니다. |
| 완료 여부 설정 | POST | https://kapi.kakao.com/v1/api/calendar/complete/task | 특정 할 일의 완료 여부를 설정합니다. |
| 삭제 | DELETE | https://kapi.kakao.com/v1/api/calendar/delete/task | 특정 할 일을 삭제합니다. |