Dingtalk Workspace

Interact with DingTalk enterprise workspace to search contacts, send messages, manage calendars, todos, approvals, attendance, reports, and AITable data via...

DingTalk Workspace Skill

Use the dws CLI to interact with DingTalk enterprise workspace. This skill covers all 12 products: contact, chat, bot, calendar, todo, oa (approval), attendance, ding, report, aitable, workbench, and devdoc.

⚠️ Security & Safety Notes

Read before installing:

1. Credentials Required: This skill requires OAuth credentials (DWS_CLIENT_ID, DWS_CLIENT_SECRET) from a DingTalk Open Platform app. Enterprise admin approval may be needed.

2. Install Safely: The dws CLI installer fetches from GitHub. Review the installer script before running:

   • Installer: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/scripts/install.sh
   • Releases: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

3. Autonomous Execution Risk: This skill can perform destructive actions (approve workflows, send messages, delete records). Always use --dry-run first and restrict autonomous invocation unless you trust the agent.

4. Least Privilege: Use scoped OAuth credentials with minimum permissions. Test in a sandbox enterprise first.

Prerequisites

Installation

Option 1: Install from release (recommended)

Download pre-built binary from https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases

Option 2: Build from source (safer)

bash

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
go build -o dws ./cmd
cp dws ~/.local/bin/

Option 3: Install script (review first!)

bash

# macOS / Linux - REVIEW SCRIPT BEFORE RUNNING
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

# Windows (PowerShell) - REVIEW SCRIPT BEFORE RUNNING
irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

Authentication

bash

# First-time login (credentials saved to system Keychain)
dws auth login --client-id <your-app-key> --client-secret <your-app-secret>

# Or via environment variables
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login

Safe Execution Guidelines

For Agents

• --dry-run: ALWAYS use first for mutations to preview API calls
• --yes: Skip confirmation prompts (use only after verifying with --dry-run)
• --jq: Extract specific fields to reduce token consumption
• --fields: Return only needed fields

Recommended Workflow

bash

# 1. Preview the operation
dws todo task create --title "Test" --executors "user123" --dry-run

# 2. Verify the output looks correct

# 3. Execute (only if preview was correct)
dws todo task create --title "Test" --executors "user123" --yes

Auto-Correction

dws automatically corrects common AI mistakes:

• --baseId → --base-id (camelCase to kebab-case)
• --timeout30 → --timeout 30 (sticky argument splitting)
• --tabel-id → --table-id (fuzzy matching)
• "yes" → true, "2024/03/29" → "2024-03-29" (value normalization)

Discovery & Introspection

Before making calls, discover available capabilities:

bash

# List all products and tool counts
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'

# Inspect a specific tool's parameter schema
dws schema aitable.query_records --jq '.tool.parameters'

# View required fields
dws schema aitable.query_records --jq '.tool.required'

# List all product IDs
dws schema --jq '.products[].id'

Quick Reference by Product

Contact

bash

# Search users by keyword
dws contact user search --keyword "engineering"

# Get current user profile
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName}'

# Search department by name
dws contact dept search --keyword "Engineering"

# List department members
dws contact dept members --dept-id <dept-id>

Chat

bash

# Send message as bot
dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID> --title "Weekly Report" --text @report.md

# List groups
dws chat group list

# Get group info
dws chat group get --group-id <GROUP_ID>

Calendar

bash

# List calendar events
dws calendar event list

# Create event
dws calendar event create --title "Team Meeting" --start "2024-03-29T14:00:00Z" --end "2024-03-29T15:00:00Z"

# Find free slots
dws calendar participant busy --user-ids <user-id-1>,<user-id-2> --start "2024-03-29" --end "2024-03-30"

# Search meeting rooms
dws calendar room search --keyword "Meeting Room"

Todo

bash

# Create todo
dws todo task create --title "Review PR" --executors "<your-userId>" --yes

# List todos
dws todo task list

# Mark as done
dws todo task done --task-id <task-id>

Approval (OA)

bash

# List pending approvals
dws oa approval list --status pending

# Approve instance
dws oa approval approve --instance-id <instance-id> --comment "Approved"

# Reject instance
dws oa approval reject --instance-id <instance-id> --comment "Needs revision"

Attendance

bash

# View my attendance records
dws attendance record list --user-id <your-userId>

# View team shift schedule
dws attendance shift list --dept-id <dept-id>

Report

bash

# View today's received reports
dws report list --type received --start-date "2024-03-29" --end-date "2024-03-29"

# Create report
dws report create --template-id <template-id> --content @report.md

AITable

bash

# Query records
dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --limit 10

# Create record
dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> --fields '{"name": "Task 1", "status": "open"}'

# List bases
dws aitable base list

# List tables in a base
dws aitable table list --base-id <BASE_ID>

Output Control

jq Filtering

bash

# Extract specific fields
dws contact user search --keyword "engineering" --jq '.result[] | {name: .orgUserName, userId: .userId}'

# Count results
dws todo task list --jq '.result | length'

Field Selection

bash

# Return only specific fields
dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --fields invocation,response

File Input

bash

# Read from file
dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID> --text @message.md

# Pipe from stdin
cat message.md | dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID>

Common Workflows

See bundled scripts in scripts/ for batch operations:

Script	Description
calendar_schedule_meeting.py	Create event + add participants + book meeting room
calendar_free_slot_finder.py	Find common free slots across multiple people
todo_batch_create.py	Batch create todos from JSON
contact_dept_members.py	Search department and list all members
report_inbox_today.py	View today's received reports

Error Handling

Common Error Codes

• INVALID_TOKEN: Re-authenticate with dws auth login
• PERMISSION_DENIED: Check app permissions in DingTalk Open Platform
• RESOURCE_NOT_FOUND: Verify IDs with dws schema introspection

Recovery

When encountering RECOVERY_EVENT_ID, use:

bash

dws --recovery <RECOVERY_EVENT_ID>

Security Notes

• Credentials are stored encrypted in system Keychain (never in config files)
• All requests use HTTPS to *.dingtalk.com only
• Use --dry-run before any mutation to preview the API call
• Token refresh is automatic; no manual intervention needed

Reference Files

• Product commands: See references/products/*.md for detailed command reference per product
• Intent guide: See references/intent-guide.md for disambiguation (e.g., report vs todo)
• Error codes: See references/error-codes.md for debugging workflows
• Global reference: See references/global-reference.md for auth, output formats, global flags