SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdingtalk-calendar

dingtalk-calendar

Office & productivity

View repository

Updated 10-15 16:28

About this skill

DingTalk Schedule Skill

Responsible for operations of the DingTalk Calendar API. This document is thestrategy guide; for the complete request format, see references/api.md。

dt_helper.sh located in this SKILL.md sibling directory's scripts/dt_helper.sh。

Core Concepts

  • In the path, userId: in the schedule API path /v1.0/calendar/users/{userId}/... , the {userId} is unionId(consistent with to-dos and documents), not staffId.
  • Primary calendar: the personal default calendar's calendarId is fixed to the string primary(lowercase). Create/query/list/update/delete all target .../calendars/primary/events...。
  • Time format：start / end, free/busy startTime/endTime, list timeMin/timeMax must use UTC ISO8601 with milliseconds, for example 2026-03-24T07:02:48.000Z. Omitting milliseconds easily triggers ParsedISO8601TimestampError。
  • Modify schedule: the HTTP method is PUT(the same path corresponding to the "partial update" semantics), and the request body must include the schedule id and the fields to change (such as summary）。
  • Video conference: when creating a schedule, add "onlineMeetingInfo":{"type":"dingtalk"}to the request body; the response includes onlineMeetingInfo.url , etc.
  • Meeting room: first query by meeting room availability interface using roomIds + time window; then on an existing schedule add meeting room(requires the enterprise's meeting room roomId, queryable in the admin console or open platform). For integration testing, the environment variable TEST_MEETING_ROOM_IDScan be used (comma-separated).
  • Check-in/check-out: after the schedule is created, you can GET check-in/check-out link and distribute it to attendees; organizers/participants POST check-in; for details use GET signin / signOut list interface (see api.md). Whether it links with offline meetings and approval flows is subject to DingTalk-side capabilities.

Scenario routing (classify first, then call the API)

User intent Preferred API direction
Book a meeting room, check whether a meeting room is available POST .../meetingRooms/schedules/query
Add a meeting room to an existing schedule POST .../events/{eventId}/meetingRooms
Want a check-in code, check-out link GET .../signInLinks、GET .../signOutLinks
Repeat weekly, repeat daily When creating a schedule, include recurrence(see api.md)
Only check people's free/busy status (not for meeting rooms) POST .../querySchedule

Workflow (before each execution)

  1. Identify the task → after classifying according to the table above, then select the specific API (see references/api.md）。
  2. Validate configuration → bash scripts/dt_helper.sh --get read DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID、DINGTALK_MY_OPERATOR_ID(when unionId is missing, --to-unionid）。
  3. Collect missing items → ask once and --set write to ~/.dingtalk-skills/config。
  4. Obtain a new-version Token → NEW_TOKEN=$(bash scripts/dt_helper.sh --token), request header x-acs-dingtalk-access-token。
  5. Execute the API → write multi-line logic to /tmp/<task>.sh then execute; heredoc is prohibited.

Validate configuration by task

  • General required：DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID; before calling, unionId（DINGTALK_MY_OPERATOR_ID is required or generated via --to-unionid ).

The API must not be called before validation passes. Credentials are displayed as only the first 4 characters + ****。

Required configuration

Configuration key Required Description
DINGTALK_APP_KEY ✅ Client ID（AppKey）
DINGTALK_APP_SECRET ✅ Client Secret
DINGTALK_MY_USER_ID ✅ Current user userId (admin console contacts)
DINGTALK_MY_OPERATOR_ID ✅ Current user unionId (--to-unionid can be written)

Identity identifier description

Identifier Description
userId Enterprise employee ID, visible in the admin console
unionId Both the calendar path parameters and the user identifiers in the body use unionId

userId → unionId: useLegacy version access_token call POST https://oapi.dingtalk.com/topapi/v2/user/get(see references/api.md), take result.unionid(no underscore).

Execution script template

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
NEW_TOKEN=$(bash "$HELPER" --token)
UNION_ID=$(bash "$HELPER" --get DINGTALK_MY_OPERATOR_ID)
CAL_ID="primary"

curl -s -X POST "https://api.dingtalk.com/v1.0/calendar/users/${UNION_ID}/calendars/${CAL_ID}/events" \
  -H "x-acs-dingtalk-access-token: $NEW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"summary":"周会","start":{"dateTime":"2026-03-25T02:00:00.000Z","timeZone":"UTC"},"end":{"dateTime":"2026-03-25T03:00:00.000Z","timeZone":"UTC"}}'

When Token is abnormal:bash "$HELPER" --token --nocache

references/api.md lookup index

grep -A 35 "^## 1. 创建日程" references/api.md
grep -A 25 "^## 2. 查询单个日程" references/api.md
grep -A 30 "^## 3. 查询日程列表" references/api.md
grep -A 25 "^## 4. 更新日程" references/api.md
grep -A 15 "^## 5. 删除日程" references/api.md
grep -A 28 "^## 6. 查询闲忙" references/api.md
grep -A 22 "^## 7. 视频会议" references/api.md
grep -A 28 "^## 8. 查询会议室忙闲" references/api.md
grep -A 25 "^## 9. 添加与移除会议室" references/api.md
grep -A 18 "^## 10. 签到与签退链接" references/api.md
grep -A 22 "^## 11. 签到与签退详情列表" references/api.md
grep -A 18 "^## 12. 签到与签退操作" references/api.md
grep -A 35 "^## 13. 循环日程" references/api.md
grep -A 15 "^## 14. 订阅日历" references/api.md
grep -A 15 "^## 错误码" references/api.md
grep -A 18 "^## 所需应用权限" references/api.md