Concepts

This document introduces the features of the Talk Calendar APIs.

Overview

The Talk Calendar API lets your service leverage the features of Talk Calendar in your service, such as adding and managing events or calendars in a user's Talk Calendar. The Talk Calendar API also enables users to subscribe to your service's calendar. If your service owns a Kakao Talk Channel, you can publish or manage a public event so that users can follow your service's events.

Calendar types

On the web or app version of Talk Calendar, a user can see the user's calendar divided into three categories.

• 🅐 Talk Calendar
  • ⓐ My Calendar
  • ⓑ Sub-calendar
• 🅑 Shared Calendar
  • NOTE: As of now, the Talk Calendar API does not support the Shared Calendar, which is created when a Team chat is created.
• 🅒 Subscribed calendar

Each calendar has the following features:

Calendar type	Description	How to create a calendar
My Calendar (🅐 > ⓐ)	Primary calendar that is automatically created when a user starts to use the Talk Calendar service.	My calendar is automatically created for each user. NOTE: This calendar cannot be deleted because it is set as a default calendar.
Sub-calendar (🅐 > ⓑ)	Additional calendars that a user or a service has created.	A service can create a calendar through the Creating sub-calendar API. Users also can create a calendar in the Talk Calendar service.
Subscribed Calendar (🅒)	Calendar that Kakao Talk Channel publishes or manages to let users subscribe to the calendar based on interests.	A service can request to create a subscribed calendar at DevTalk.

Event types

Here are the types of events that can be handled with the Talk Calendar APIs.

Event type	Description	How to add	How to edit
Personal event	Events that a user has added to the user's My Calendar or sub-calendars	Users can create an event through the Creating event API. NOTE: The created event is added to a user's My Calendar or sub-calendars.	For event hosts, use the Editing event for host API. For event attendees, use the Editing event for attendee API.
Public event	Events that are published by a service's Kakao Talk Channel for marketing purpose	Your service can publish a public event through the Creating public event API. Users can add a public event published by your service to their own calendar by calling the Following public event API. NOTE: The public event is added to a user's My Calendar or sub-calendar.	Use the Editing event for attendee API.
Subscribed event	Events that are published by Kakao Talk Channel (Example: Kakao TV, Sports channel)	If a user subscribes to a subscribed calendar, all the events of the service are added to its subscribed calendar. If a user chooses to unsubscribe, all subscribed events are deleted. NOTE: The subscribed event is added to a user's Subscribed calendar.	Use the Editing event for attendee API.

Send a calendar message

If your service uses a public event or subscribed calendar, you can encourage users to add the event or calendar to their calendar by sending a Kakao Talk message through the Messaging API. For this, you need to configure a message with a follow or subscribe button by using the calendar template.

To implement this functionality, see the following documentation:

Purpose	Guide
To configure a calendar type of message	Message Template
To send a calendar message through Kakao Talk Sharing	JavaScript SDK Android SDK iOS SDK Flutter SDK
To send a calendar message through Kakao Talk Messaging IMPORTANT: To send a calendar message to all users who are linked to your app, set consent item and request permission.	REST API JavaScript SDK Android SDK iOS SDK Flutter SDK

Usage policy

Request permission

Before permission is granted to your app,

• You and your team members can test the Talk Calendar API by setting the 'Create, retrieve, edit/delete Talk Calendar and events' scope to 'Consent during use' in [My Application] > [Kakao Login] > [Consent items].
  • IMPORTANT: Only 30 API calls are allowed. Refer to Usage policy.
• You can create an event in your Talk Calendar, and edit or delete the registered events.
• You can retrieve the events registered in your calendar.
  • NOTE: In the case of the calendar or events that are created by your service, the detailed information of the calendar or events are retrieved. If calendars are not created by your service, only calendar IDs are returned. If events are not created by your service, only time information of the event is returned.

To apply the implemented Talk Calendar functionality to your actual service or to use more advanced features, your app must obtain permission. To request permission, go to DevTalk, select ➊'톡캘린더 API(Talk Calendar API)' > '톡캘린더 API 사용 신청(Request permission to use Talk Calendar API)' category > ➋[새글 쓰기(New Topic)].

The Kakao platform administrator decides whether to give permission to use the Talk Calendar API after reviewing the request form and lets you know the result.

After permission is granted to your app,

• You may set the 'Create, retrieve, edit/delete Talk Calendar and events' scope to 'Optional Consent' in [My Application] > [Kakao Login] > [Consent items].
• You can create, view, edit, and delete a public event.
• You can view subscribed calendars, let users to subscribe to or unsubscribe from a subscribed calendar.

To see the list of APIs that you can use after permission is granted, refer to Scope of support.

Quota

Kakao API applies monthly and daily quotas for stable service. You can check the currently applied quota information in the Quota. To increase the applied quota limit, contact us as consultation and partnership are required.

To increase allocated quota for the Talk Calendar API, you need to request permission. By default, you can use the API on a limited quota for testing.

Features

• Refer to Scope of support to know whether each Kakao SDK supports each feature.

Permission: Indicates the APIs with this tag attached require permission to use the APIs.

Feature		Description	Documentation
User calendar	Retrieve list of calendars	Retrieves user's all calendars, except for a Shared calendar.	REST API
	Create sub-calendar	Creates a sub-calendar on user's Talk Calendar.	REST API
	Edit sub-calendar	Edits a particular sub-calendar.	REST API
	Delete sub-calendar	Deletes a particular sub-calendar.	REST API
User event	Create event	Adds an event to a user's calendar. Users can see the created events under the Talk Calendar category in Talk Calendar.	REST API
	Retrieve list of events	Retrieves the events added on a user's calendar.	REST API
	Retrieve details of event	Retrieves the details of a user's personal event.	REST API
	Edit event for host	Edits a particular personal event that a user has created.	REST API
	Delete event	Deletes a user's personal event or public event.	REST API
Public event Permission	Create public event	Creates a public event.	REST API
	Retrieve list of public events	Retrieves all public events that your service has created.	REST API
	Retrieve details of public event	Retrieves the details of a particular public event that your service has created.	REST API
	Edit public event	Edits a particular public event.	REST API
	Delete public event	Deletes a particular public event.	REST API
	Add public event to user calendar	Adds a public event published by your service to user's calendar.	REST API
Subscribed calendar Permission	Retrieve list of subscribable calendars	Retrieves the list of the available calendars that a user can subscribe to.	REST API
	Subscribe	Subscribes to a service's subscribed calendar.	REST API
	Unsubscribe	Unsubscribes from a service's subscribed calendar.	REST API
Guest event	Edit event for attendee	Edits a particular public event or subscribed event added to a user's calendar.	REST API
Retrieve holidays and celebrations		Retrieves holidays and celebrations in the Republic of Korea.	REST API