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.