dingtalk-calendar

Original：🇨🇳 Chinese

Translated

1 scripts

DingTalk Schedule and Calendar. This skill is used when users mention "DingTalk schedule", "calendar", "create schedule", "new meeting", "video conference", "DingTalk meeting", "meeting room", "book meeting room", "meeting room availability", "available meeting room", "check-in", "check-out", "check-in link", "check-out link", "recurring schedule", "repeating schedule", "recurrence", "query schedule", "schedule list", "modify schedule", "delete schedule", "availability", "busy/free status", "querySchedule", "calendar", "dingtalk schedule", "schedule reminder". Supported features: Schedule CRUD under primary calendar, user busy/free status, video conference, meeting room availability and schedule binding, check-in/check-out and corresponding links, recurrence rules; Features requiring Calendar.Calendar.Write permission such as subscribing to public calendars can be found in api.md.

2installs

Sourcebreath57/dingtalk-skills

Added on2026-04-11

NPX Install

npx skill4agent add breath57/dingtalk-skills dingtalk-calendar

SKILL.md Content (Chinese)

View Translation Comparison →

DingTalk Schedule Skill

Responsible for operating DingTalk Calendar API. This document is a policy guide; for complete request formats, refer to

references/api.md

.

dt_helper.sh
is located in
scripts/dt_helper.sh
at the same level as this
SKILL.md
.

Core Concepts

userId
in the path: The
```
{userId}
```
in the schedule API path
```
/v1.0/calendar/users/{userId}/...
```
is unionId (consistent with to-dos and documents), not staffId.
Primary Calendar: The
```
calendarId
```
of the personal default calendar uses the fixed string primary
(lowercase). All create/query/list/update/delete operations target
```
.../calendars/primary/events...
```
.
Time Format:
```
start
```
/
```
end
```
,
```
startTime
```
/
```
endTime
```
for busy/free status,
```
timeMin
```
/
```
timeMax
```
for list queries must use UTC ISO8601 with milliseconds, for example
```
2026-03-24T07:02:48.000Z
```
. Omitting milliseconds can easily trigger
```
ParsedISO8601TimestampError
```
.
Modify Schedule: The HTTP method is PUT (same path as the "partial update" semantics), the request body needs to include the schedule
```
id
```
and the fields to be modified (such as
```
summary
```
).
Video Conference: Add
```
"onlineMeetingInfo":{"type":"dingtalk"}
```
to the request body when creating a schedule, the response will include
```
onlineMeetingInfo.url
```
and other related information.
Meeting Room: First query by
```
roomIds
```
+ time window through the meeting room availability interface; then add meeting room to the existing schedule (requires the enterprise internal meeting room
```
roomId
```
, which can be found in the management backend or open platform). For integration testing, you can use the environment variable
```
TEST_MEETING_ROOM_IDS
```
(comma-separated).
Check-in/Check-out: After the schedule is created, you can GET check-in/check-out links to distribute to participants; organizers/participants POST to complete check-in; for details, use the GET signin / signOut list interface (see api.md). Whether it is linked with offline meetings and approval flows is subject to DingTalk's capabilities.

Scenario Routing (classify first then call API)

User Intent	Priority API Direction
Book a meeting room, check meeting room availability	`POST .../meetingRooms/schedules/query`
Add meeting room to existing schedule	`POST .../events/{eventId}/meetingRooms`
Request check-in code, check-out link	`GET .../signInLinks` , `GET .../signOutLinks`
Weekly recurrence, daily recurrence	Add `recurrence` when creating a schedule (see api.md)
Only query user availability (not for meeting rooms)	`POST .../querySchedule`

Workflow (before each execution)

Identify the task → Classify according to the table above, then select the specific API (see
```
references/api.md
```
).

Verify configuration → Run

bash scripts/dt_helper.sh --get

to read

DINGTALK_APP_KEY

,

DINGTALK_APP_SECRET

,

DINGTALK_MY_USER_ID

,

DINGTALK_MY_OPERATOR_ID

(use

--to-unionid

if unionId is missing).

Collect missing items → Ask for all missing information at once and write to
```
~/.dingtalk-skills/config
```
with
```
--set
```
.

Get the latest Token →

NEW_TOKEN=$(bash scripts/dt_helper.sh --token)

, add to request header

x-acs-dingtalk-access-token

.

Execute API → Write multi-line logic to
```
/tmp/<task>.sh
```
before execution; heredoc is prohibited.

Verify Configuration by Task

General requirements:

DINGTALK_APP_KEY

,

DINGTALK_APP_SECRET

,

DINGTALK_MY_USER_ID

; unionId is required before calling (either

DINGTALK_MY_OPERATOR_ID

or generated via

--to-unionid

).

API calls are not allowed before passing verification. Only the first 4 digits of credentials are displayed +
****
.

Required Configuration

Configuration Key	Required	Description
`DINGTALK_APP_KEY`	✅	Client ID (AppKey)
`DINGTALK_APP_SECRET`	✅	Client Secret
`DINGTALK_MY_USER_ID`	✅	Current user userId (from management backend address book)
`DINGTALK_MY_OPERATOR_ID`	✅	Current user unionId (can be written via `--to-unionid` )

Identity Description

Identifier	Description
`userId`	Enterprise employee ID, visible in management backend
`unionId`	All user identifiers in schedule path parameters and body use unionId

userId → unionId: Use old version

access_token

to call

POST https://oapi.dingtalk.com/topapi/v2/user/get

(see

references/api.md

), get

result.unionid

(no underscore).

Execution Script Template

bash

#!/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 Reference Index