references/api.md

dt_helper.sh

is located in

scripts/dt_helper.sh

at the same level as this

SKILL.md

.

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

1. Identify the task → Classify according to the table above, then select the specific API (see

   references/api.md

   ).
2. 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).
3. Collect missing items → Ask for all missing information at once and write to

   ~/.dingtalk-skills/config

   with

   --set

   .
4. Get the latest Token →

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

   , add to request header

   x-acs-dingtalk-access-token

   .
5. Execute API → Write multi-line logic to

   /tmp/<task>.sh

   before execution; heredoc is prohibited.

• 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 +

****

.

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