Overview

This topic introduces the Calendar product, including how to activate Calendar, the API capabilities exposed by Calendar, and how to integrate Calendar capabilities.

What is Calendar

DingTalk Calendar is deeply integrated with instant messaging. Colleagues can share events, easily start event meetings, and view important matters at a glance, enabling more efficient team collaboration and a great experience for employees. For more information, see DingTalk User Guide - Calendar.

Precise notifications for event meetings

Create a meeting event with one click. Invitations are sent directly to each attendee as chat messages, ensuring nothing is missed.

Unified event management

Connect with Alibaba Mail to view and edit events in a unified way within the DingTalk calendar. Update in one place and sync everywhere, so you never miss a meeting or schedule.

How to activate Calendar

On mobile: Tap Collaboration > Calendar, or tap Calendar in the toolbar. On desktop: Click Calendar.

Open capabilities overview

API list

Calendar provides a rich set of open APIs. Developers can use these APIs to integrate Calendar with their organization’s business systems.

Notes

The New Event, Update Event, Add Event Attendees, and Delete Event Attendees APIs each support up to 500 attendees per operation, and a maximum of 5,000 attendees per event.
To add or remove event attendees, we recommend using the Add Event Attendees and Delete Event Attendees APIs.

User access control

API	Description	New specification (new Server API)	Legacy specification (Server API)
Create access control	Add access control to the specified calendar.	Create access control	-
Delete access control	Delete access control.	Delete access control	-
Get access control list	Get the calendar access control list.	Get access control list	-

Event

API	Description	New specification (new Server API)	Legacy specification (Server API)
New Event	Create an event.	New Event	-
Delete Event	Delete the specified event.	Delete Event	-
Update event	Update information about a single event.	Update event	-
Query event details	Query the details of a single event.	Query event details	-
Query event list	Query a user’s events within a given time range.	Query event list	-
Query event view	Query the event view of a user’s primary DingTalk calendar within a time range.	Query event view	-

Event attendees

API	Description	New specification (new Server API)	Legacy specification (Server API)
Add event attendees	Add event attendees.	Add event attendees
Delete event attendees	Remove the specified users from the event attendees.	Delete event attendees	-
Get event attendees	Get the list of event attendees.	Get event attendees	-
Set event invitation response status	Set the response status of an event invitation.	Set event invitation response status	-

Free/busy

API	Description	New specification (new Server API)	Legacy specification (Server API)
Get user free/busy information	Query the free/busy information of a specified user list within a given time range.	Get user free/busy information	-

Calendar

API	Description	New specification (new Server API)	Legacy specification (Server API)
Query calendar	Call this API to query a user’s calendar.	Query calendar	-
Subscribe to public calendar	Call this API to subscribe to a public calendar.	Subscribe to public calendar	-
Unsubscribe from public calendar	Call this API to unsubscribe from a public calendar.	Unsubscribe from public calendar	-
Create subscription calendar	Call this API to create a subscription calendar.	Create subscription calendar	-
Query subscription calendar details	Call this API to query the details of a subscription calendar.	Query subscription calendar details	-
Update subscription calendar	Call this API to update information about a single subscription calendar.	Update subscription calendar	-
Delete subscription calendar	Call this API to delete a subscription calendar.	Delete subscription calendar	-

Check-in

API	Description	New specification (new Server API)	Legacy specification (Server API)
View check-in details of a single event	Call this API to view the check-in details of a single event.	View check-in details of a single event	-
Check in for a single event	Check in for the specified event by event ID.	Check in for a single event	-
Check out for a single event	Check out for the specified event by event ID.	Check out for a single event	-
View check-in details of a single event	Query the list of checked-in and not-checked-in users for a single event by event ID.	View check-out details of a single event	-
Get check-in link	Query the check-in link by calendar ID, user unionId, and event eventId.	Get check-in link	-
Get check-out link	Query the check-out link by calendar ID, user unionId, and event eventId.	Get check-out link	-

Room

API	Description	New specification (new Server API)	Legacy specification (Server API)
Get room free/busy information	Get room free/busy information.	Get room free/busy information	-
Book a room	Book a room.	Book a room	-
Cancel a room booking	Cancel a room booking.	Cancel a room booking	-

Callback event list

Calendar supports callback events triggered when a user makes event changes.

Tutorials

DingTalk provides example workflows for common scenarios such as creating and deleting events, and managing event attendees:

Glossary

Permission value	Description
free_busy_reader	Check free/busy
title_reader	View title
reader	View details
writer	Create and edit

Resource definitions

Attribute	Type	Description
id	String	The globally unique ID of the event.
summary	String	Event title.
description	String	Event description.
start	Object	Event start time.
start.date	String	Event start date in the format yyyy-MM-dd. Required for all-day events; must be empty for non-all-day events.
start.dateTime	String	Event start time in ISO-8601 date-time format. Required for non-all-day events; must be empty for all-day events.
start.timeZone	String	Time zone of the event start time. Required for non-all-day events; must be empty for all-day events.
end	Object	Event end time.
end.date	String	Event end date in the format yyyy-MM-dd. Required for all-day events; must be empty for non-all-day events.
end.dateTime	String	Event end time in ISO-8601 date-time format. Required for non-all-day events; must be empty for all-day events.
end.timeZone	String	Time zone of the event end time. Must match the time zone of the start time, in TZ database name format. Required for non-all-day events; must be empty for all-day events.
isAllDay	Boolean	Whether the event is an all-day event.
recurrence	Object	Event recurrence rule.
recurrence.pattern	Object	Recurrence pattern.
recurrence.pattern.type	String	Recurrence pattern type: - daily: Repeats every `interval` days. - weekly: Repeats on `daysOfWeek` every `interval` weeks. - absoluteMonthly: Repeats on the `dayOfMonth` day every `interval` months. - relativeMonthly: Repeats on `daysOfWeek` of the `index` week every `interval` months. - absoluteYearly: Repeats every `interval` years.
recurrence.pattern.dayOfMonth	Integer	When `type=absoluteMonthly`, specifies the day of the month.
recurrence.pattern.daysOfWeek	String	Specifies the day of the week as a lowercase English word. Separate multiple values with commas.
recurrence.pattern.index	String	When `type=relativeMonthly`, specifies the week of the month: - first - second - third - fourth - last `last` indicates the last week of the month.
recurrence.pattern.interval	Integer	The recurrence interval. The unit varies by type. For example, when `type=daily`, the interval is in days; when `type=absoluteYearly`, the interval is in years.
recurrence.range	Object	Recurrence range.
recurrence.range.type	String	Recurrence range type: - noEnd: Never ends. - endDate: Ends on a specified date. - numbered: Ends after a specified number of occurrences.
recurrence.range.endDate	String	The end date of the recurrence.
recurrence.range.numberOfOccurrences	Integer	The number of occurrences.
attendees	Array	List of event attendees.
attendees.id	String	The unionId of the user.
attendees.displayName	String	User name.
attendees.responseStatus	String	Attendee status: - needsAction: No action taken (default status). - accepted: Accepted. - declined: Declined. - tentative: Tentatively accepted.
attendees.self	Boolean	Whether this is the current operating user.
organizer	Object	Event organizer.
organizer.id	String	The unionId of the organizer.
organizer.displayName	String	The user name of the organizer.
organizer.responseStatus	String	The response status of the organizer.
organizer.self	Boolean	Whether this is the current user.
location	Object	Event location.
location.displayName	String	Location name.
reminders	Array	Event reminders.
reminders.method	String	Reminder method: - dingtalk: In-app reminder. - sms: SMS reminder. - phone: Phone reminder.
reminders.minutes	String	How many minutes before the event to send the reminder.
onlineMeetingInfo	Object	Create an online meeting along with the event.
onlineMeetingInfo.type	String	Online meeting type: - dingtalk: DingTalk video meeting.
onlineMeetingInfo.conferenceId	String	Meeting ID.
onlineMeetingInfo.url	String	Meeting URL.
onlineMeetingInfo.extraInfo	Map	Additional extended information.
seriesMasterId	String	The master event ID of a recurring event. Empty for non-recurring events.
createTime	String	Created time.
updateTime	String	Update time.
status	String	Event status: - confirmed: Normal. - cancelled: Cancelled.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

What is Calendar

Precise notifications for event meetings

Unified event management

How to activate Calendar

Open capabilities overview

API list

Notes

User access control

Event

Event attendees

Free/busy

Calendar

Check-in

Room

Callback event list

Tutorials

Glossary

Resource definitions

​What is Calendar

​Precise notifications for event meetings

​Unified event management

​How to activate Calendar

​Open capabilities overview

​API list

​Notes

​User access control

​Event

​Event attendees

​Free/busy

​Calendar

​Check-in

​Room

​Callback event list

​Tutorials

​Glossary

​Resource definitions

What is Calendar

Precise notifications for event meetings

Unified event management

How to activate Calendar

Open capabilities overview

API list

Notes

User access control

Event

Event attendees

Free/busy

Calendar

Check-in

Room

Callback event list

Tutorials

Glossary

Resource definitions