이해하기

이 문서는 톡캘린더 API를 소개합니다.

기능 소개

톡캘린더는 카카오톡 채팅방에서 일정을 만들고, 할 일을 등록해 손쉽게 관리할 수 있는 서비스입니다. 톡캘린더 API는 캘린더, 일정, 할 일을 등록하고 관리하는 기능을 제공합니다.

캘린더

톡캘린더는 캘린더에 일정을 추가하고 관리합니다. 캘린더는 사용자 캘린더, 공유 캘린더, 구독 캘린더가 있습니다. 공유 캘린더 관련 API는 추후 지원 예정입니다.

• 🅐 기본 캘린더
• 🅑 서브 캘린더
• 🅒 공유 캘린더(지원 예정)
• 🅓 사용자가 구독한 구독 캘린더

사용자 캘린더

사용자가 관리하는 캘린더입니다. 기본 캘린더, 서브 캘린더, 구독한 구독 캘린더가 있습니다.

캘린더 종류	설명
기본 캘린더	카카오계정 단위로 기본 제공, 추가 또는 삭제 불가
서브 캘린더	사용자가 일정을 구분해 관리하기 위해 추가로 생성한, 기본 캘린더와 같은 기능의 캘린더 서비스는 한 사용자에게 최대 3개까지 서브 캘린더를 생성 가능 사용자별 서브 캘린더의 최대 갯수: 99개 한 서비스에서 같은 이름 중복 생성 불가
구독 캘린더	구독 캘린더를 구독하면 사용자 캘린더에 추가됨

구독 캘린더

카카오톡 채널 관리자가 발행하고 관리하는 관심사 기반의 캘린더입니다. 사용자는 구독 캘린더를 구독해 일정을 확인하고 관리할 수 있습니다.

일정

톡캘린더의 일정은 용도에 따라 구분되며, 사용 가능한 기능에 차이가 있습니다.

일반 일정

사용자가 직접 사용자 캘린더에 추가, 수정, 삭제할 수 있는 일정입니다. 구독 캘린더에는 추가할 수 없습니다.

공개 일정

카카오톡 채널이 주체가 되어 마케팅(Marketing) 목적으로 만든 일정입니다. 공개 일정을 생성하려면 카카오톡 채널 연결이 필요합니다. 생성한 공개 일정을 사용자의 특정 캘린더에 추가해 사용자의 게스트 일정으로 만들 수 있습니다.

구독 일정

구독 캘린더 내의 일정입니다. 구독 캘린더를 구독하면 해당 캘린더 내 모든 구독 일정은 게스트 일정이 됩니다.

게스트 일정

사용자의 특정 캘린더에 추가된 공개 일정과 구독한 구독 캘린더 내의 구독 일정입니다. 사용자는 게스트 일정을 제한적으로 수정할 수 있으며, 수정 사항은 사용자의 캘린더에만 반영됩니다. 채널에서 직접 공개 일정 > 수정하기로 수정한 공개/구독 일정의 변경 사항은 사용자 캘린더의 게스트 일정에도 반영됩니다.

할 일

사용자가 해야할 일의 세부 내용을 작성해 할 일로 등록할 수 있습니다. 필요에 따라 시간 정보와 완료 기록을 확인할 수 있는 [도전 기록 보기]를 설정하면 할 일을 누락 없이 완료하도록 관리할 수 있습니다.

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

톡캘린더 메시지

톡캘린더 API 사용 서비스는 사용자가 카카오톡 나와의 채팅 또는 친구에게 캘린더 메시지를 보내는 기능을 구현할 수 있습니다. 캘린더 메시지는 서비스의 구독 캘린더나 공개 일정을 사용자 캘린더에 추가하는 기능을 제공합니다.

현재 캘린더 메시지는 카카오톡 메시지 API와 카카오톡 공유 API로 전송 가능합니다. 캘린더 메시지 사용 방법은 다음 문서에서 확인할 수 있습니다.

• 메시지: 카카오톡 메시지 API 기능 소개, 이용 정책 안내
• 메시지 템플릿: 캘린더 메시지 구성 요소 안내, 현재 기본 템플릿만 지원
• 카카오톡 메시지, 카카오톡 공유: 캘린더 메시지 기본 템플릿을 사용한 메시지 전송 방법 안내
• 카카오톡 소셜: 사용자의 친구에게 카카오톡 메시지를 보내고자 할 경우, 카카오톡 친구 정보를 받아오는 기능 안내

이용 정책

사용 권한 신청

톡캘린더 API는 사용 권한이 주어진 앱에서만 사용할 수 있습니다. 사용 권한을 받기 전에는 앱의 팀원에게만 사용 가능하도록 기능 동작이 제한됩니다. 실제 서비스에서 모든 사용자에게 기능을 사용하려면 [내 애플리케이션] > [앱 권한 신청]에서 사용 권한을 신청해야 합니다.

사용 권한 신청 전 아래 과정을 선행해야 합니다.

1. 동의항목을 참고해 아래 기능별 필요 동의항목 설정
   • 캘린더, 일정: [톡캘린더 및 일정 생성, 조회, 편집/삭제(talk_calendar)]
   • 할 일: [톡캘린더 내 할 일 생성, 조회, 편집/삭제(talk_calendar_task)]
2. 톡캘린더 API를 사용한 기능 구현
3. 앱의 팀원을 대상으로 기능이 정상 동작하는지 확인

사용 권한을 받으면 서비스의 모든 사용자에게 톡캘린더 API 기능을 제공할 수 있습니다.

쿼터

카카오 API는 원활한 서비스 제공을 위해 월간 및 일일 쿼터(Quota, 사용량 제한)를 적용합니다. 현재 적용 중인 쿼터 정보는 쿼터에서 확인할 수 있습니다. 적용된 쿼터 한도를 상향하기 위해서는 협의 및 제휴가 필요하므로 별도 문의합니다.

단, 톡캘린더 API는 할당된 사용량을 늘리려면 사용 권한 신청이 필요합니다. 사용 권한을 받기 전에는 테스트를 위해 제한적으로 API를 사용할 수 있습니다.

지원하는 기능

• 각 API 및 기능의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.

API 및 기능		설명	문서
사용자 캘린더	목록 가져오기	사용자의 캘린더 목록을 가져옵니다.	REST API
	생성하기: 서브 캘린더	사용자의 캘린더에 새로운 서브 캘린더를 생성합니다.	REST API
	수정하기: 서브 캘린더	사용자의 특정 캘린더 설정을 수정합니다.	REST API
	삭제하기: 서브 캘린더	사용자의 특정 캘린더를 삭제합니다.	REST API
일반 일정	생성하기	사용자의 특정 캘린더에 일반 일정을 생성합니다.	REST API
	목록 가져오기	사용자의 특정 캘린더에 등록된 일정 목록을 가져옵니다.	REST API
	상세 조회하기	사용자의 일반 일정 정보를 조회합니다.	REST API
	수정하기	사용자의 일반 일정 정보를 수정합니다.	REST API
	삭제하기	사용자의 일반 일정을 삭제합니다.	REST API
공개 일정	생성하기	카카오톡 채널의 공개 일정을 생성합니다.	REST API
	목록 가져오기	카카오톡 채널의 등록된 공개 일정 목록을 가져옵니다.	REST API
	상세 조회하기	카카오톡 채널의 공개 일정 정보를 조회합니다.	REST API
	수정하기	카카오톡 채널의 공개 일정 정보를 수정합니다.	REST API
	삭제하기	카카오톡 채널의 공개 일정을 삭제합니다.	REST API
	사용자 캘린더에 추가하기	공개 일정을 사용자 캘린더에 추가합니다.	REST API
구독 캘린더	구독 가능 캘린더 목록 가져오기	특정 카카오톡 채널의 구독 가능 캘린더 목록을 가져옵니다.	REST API
	구독하기	구독 가능 캘린더를 사용자 캘린더에 추가합니다.	REST API
	구독 해제하기	사용자가 구독 중인 캘린더를 구독 해제합니다.	REST API
게스트 일정	수정하기	사용자의 특정 캘린더에 추가한 일정을 수정합니다.	REST API
공휴일 및 주요 기념일 조회하기		법정공휴일과 톡캘린더 서비스에서 지정한 일부 기념일 목록을 조회합니다.	REST API
할 일	생성하기	할 일을 생성합니다.	REST API
	조회하기	할 일 정보를 조회합니다.	REST API
	도전 기록 보기	특정 반복 할 일의 도전 기록을 확인합니다.	REST API
	수정하기	특정 할 일의 정보를 수정합니다.	REST API
	완료 여부 설정하기	특정 할 일의 완료 여부를 설정합니다.	REST API
	삭제하기	특정 할 일을 삭제합니다.	REST API