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. |