dingtalk-event

Listen to DingTalk IM, OA approval, VoIP, and todo events over long-lived connections.

2.8k|221|Updated Mar 21, 2026
One-click install
npx skills add https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli --skill dingtalk-event
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dingtalk-event
Source: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/tree/main/skills/multi/dingtalk-event
Command: npx skills add https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli --skill dingtalk-event

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It eliminates polling scripts by giving agents real-time, long-connection subscriptions to personal DingTalk events such as messages, approvals, calls, and todo changes.

Core Features & Use Cases

  • IM Event Listening: Monitor @mentions, messages from specific users or groups, reactions, read receipts, recalls, and group lifecycle changes via dws event +listen-im or dws event consume.
  • OA, VoIP, and Todo Events: Subscribe to seven OA approval events, VoIP call invitations, and todo create/update/delete events with role-based scoping.
  • Safe Subscription Lifecycle: Ready markers, bounded consumption, dry-run stop confirmation, retry budgets, and local subscription protection prevent runaway or duplicate subscriptions.
  • Use Case: An agent listens for messages mentioning the user in a specific group, then replies using the event's real conversation_id handed off to dws chat +messages-send.

Quick Start

Ask the agent to listen for messages that @mention you by running the dingtalk-event skill's default entry dws event +listen-im --kind at-me.

Frequently Asked Questions about dingtalk-event

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I listen for DingTalk messages that mention me?▼

Run `dws event +listen-im --kind at-me` to subscribe to messages that @mention the current OAuth user. Wait for the `[event] ready` marker on stderr before reading NDJSON events from stdout.

How to monitor DingTalk OA approval events in real time?▼

Use `dws event consume` with one or more of the seven OA EventKeys such as `user_oa_approval_task_created` or `user_oa_approval_instance_finished`. These subscriptions use `ruleType=all` and accept no user, group, or filter parameters.

Can I filter DingTalk event subscriptions by sender or group?▼

Yes, `+listen-im --kind sender` accepts `--user`, `--open-dingtalk-id`, or `--user-query`, and `--kind group` accepts `--chat-id` or `--chat-query`. Names are resolved uniquely inside the CLI and fail before creating any subscription on zero or multiple matches.

Why does my DingTalk event consumer show no output?▼

First confirm the correct `[event] ready` marker appeared on stderr, then check `dws event status` for the subscribe_id and received/dropped counters. Messages sent by the current user are filtered by self-loop protection, so test with another user or bot.

What are the limitations of DingTalk event subscriptions?▼

Subscriptions follow a 0/2/1 retry budget based on the retryable flag and honor `retry_after_seconds`, `in_flight`, `cooldown`, and `terminal_hold` states. Local protection records reset after 24 hours without failures, and `terminal_hold` lasts one hour.

How do I safely stop a DingTalk event subscription?▼

Run `dws event stop <subscribe_id> --dry-run` first to preview the impact, then confirm with `--yes`. Never use `kill -9` on the consumer process because it skips automatic unsubscription cleanup.