dingtalk-event

DingTalk personal IM, OA approval, VoIP, todo, interactive card, and friend events

**Prerequisite: before executing dws you must fully read dingtalk-shared.** Shared references are loaded only on demand.

This Skill is only responsible for real-time personal events; sending/historical messages, approval handling, and todo operations go through dingtalk-chat、dingtalk-misc、dingtalk-todo。

Only group lifecycle, Filter DSL, raw envelope, or low-level subscription control use event consume。

Golden Route

User intent	Only recommended entry point
Listen to messages @me	dws event +listen-im --kind at-me
Listen to messages sent by someone	dws event +listen-im --kind sender --user-query <姓名>
Listen to a specified group's messages	dws event +listen-im --kind group --chat-query <群名>
Messages, emojis, reads, or recalls from the same person/group	`dws event +listen-im --kind <sender
Listen to all one-on-one chats or all group messages	`dws event +listen-im --kind <all-direct
Group rename, member join/leave, group dissolution	EventKey is user_im_group_updated、user_im_group_member_added、user_im_group_member_exited、user_im_group_disbanded, read EventKey index
OA approval task or instance events	Read OA event reference, use exact event consume EventKey
View OA event catalog	dws event list --category oa
VoIP call invitation	Read VoIP event reference, use exact event consume EventKey
Todo creation, update, or deletion events	Read Todo event reference, use exact event consume EventKey and --role-types
View Todo event catalog	dws event list --category todo
Friend request/friend added successfully events	Read Friend event reference, use exact event consume EventKey
View friend event catalog	dws event list --category contact
Interactive card callback	Read Interactive card event reference; for commands and fields see the card contract below
View interactive card event catalog	dws event list --category card
Known EventKey or need low-level subscription control	dws event consume; parameters and constraints are subject to the leaf Schema
View status / stop	dws event status / dws event stop <subscribe_id> --dry-run, after confirmation then --yes

Default --events message. Optional events are message、reaction、read、recall：

• at-me、all-direct、all-group only supports message, and does not accept a target.
• sender must and can only pass --user、--open-dingtalk-id or --user-query one of.
• group must and can only pass --chat-id or --chat-query one of.
• --query is only used for pure message listening; must not be used when reaction/read/recall are mixed in.

The seven OA EventKeys use ruleType=all、filterRule={}, do not accept a target or message filtering; the three Todo EventKeys only accept --role-types creator,executor,participant, when omitted take the union; the two friend EventKeys have the same constraints as OA. Each item is subscribed independently and shares the bus.

Names/group names must be resolved uniquely; zero hits or multiple candidates stop before creating a subscription. Resolution, listening, status, and stop use the same --profile, IDs must not be carried across organizations.

EventKey index

See 16 EventKeys and target constraints in Index; group output may include operator_open_dingtalk_id、members[].open_dingtalk_id。

Runtime and Result Contract

• Normal consumption uses the current user OAuth,--flatten and NDJSON; stdout contains only events, stderr carries lifecycle status.
• Single-event ready:[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>。
• For multiple events, first output subscription one by one, and after all are ready output [event] ready event_count=<n> bus_pid=<pid>. Wait for ready, do not use sleep to guess.
• For bounded tasks use --max-events N/--duration 10m; a clean exit cancels subscriptions newly created in this run. For unbounded tasks the host continuously reads stdout; use SIGTERM or bounded exit, do not use kill -9。
• Self-sent messages are filtered by self-loop. When replying, pass the real conversation_id/sender_open_dingtalk_id to dws chat +messages-send, do not guess the ID from the display name.
• Flat message/action fields are read by event type: read is reader_open_dingtalk_id, recall is recaller_open_dingtalk_id, reaction is reaction_name、operation_type. For media, prefer chat read commands plus --download-resources, and for known message IDs use dws chat message download-media。
• OA flat events provide approval instance, task, and status fields; for field differences, raw fallback conditions, and stable ID handoff with OA commands, refer to OA Event Reference .
• Todo flat events provide task_id, title, role, status stage, and time fields; pass the real task_id to dws todo, for field differences see Todo Event Reference。
• Interactive card outputs type/event_id/timestamp/subscribe_id/payload; the three timestamps such as operator operatorDTO.uid，triggerTimestamp are preserved as-is; for fallback see Interactive Card Reference。

Security and Failure Handling

Open-source normal obtains the missing AppKey, no AppSecret required; except for custom/customized versions.Troubleshooting。

• event stop Cancel subscription and affect the local consumer: first --dry-run, after confirmation --yes。
• Multiple events belong to one original operation; when any subscription fails to start, Runtime rolls back items created in this run, and does not split into new commands to bypass the retry budget.
• All 30 public personal EventKeys (16 IM + 7 OA + 1 VoIP + 3 Todo + 1 card + 2 friend) follow Agent/host 0/2/1：retryable=false→max_additional_attempts=0；retryable=true→max_additional_attempts=2；retryable=unknown→max_additional_attempts=1. It is not a CLI persistent hard total attempt limit; there is no automatic retry within the process, and it does not persist or calculate Agent/host attempt counts across calls.
• When complying with retry_after_seconds/next_retry_at；in_flight、cooldown、terminal_hold , do not concurrently or switch subscribe_id/trace_id to bypass.
• For authentication, profile, subscription protection state, and bus troubleshooting, read by failure type Subscription Operations。

Local Subscription Protection

Status in ~/.dws/events/open/personal_stream/<identity_hash>/personal_subscription_attempts.json（DWS_CONFIG_DIR change root); directory 0700，personal_subscription_attempts.json and personal_subscription_attempts.lock are 0600. After consecutive 24h with no failures, reset,terminal_hold is 1h. Emergency recovery only deletes personal_subscription_attempts.json, do not delete the lock file; doing so clears all protection records for that identity.

When to Query Schema

• When the Golden Route is known, execute directly, do not first run event list。
• When parsing business fields use dws event schema <event_key> --flatten。
• Use when parameters or security are uncertain dws schema --cli-path "event +listen-im" --compact or the corresponding compact leaf.
• event schema describes the event payload; top-level dws schema describes CLI commands, do not mix the two.

Reference

Topic	Reference	When to read
Task Index	event-im.md	Unsure which reference to load
EventKey, target rules, and the underlying consume	event-im-keys.md	Group lifecycle, explicit EventKey, or multi-event combination
ready, bounded consume, and exit cleanup	event-im-lifecycle.md	Start/host/close a consumer
Flat fields and event-to-Chat handoff	event-im-output.md	Parse an event or auto-reply
Filter, status/stop, retry, and troubleshooting	event-im-operations.md	Subscription control or failure recovery
OA approval events	event-oa.md	Seven OA EventKeys and approval field parsing
VoIP call invitation events	event-voip.md	VoIP EventKey and invitation fields, sensitive output boundaries
Todo events	event-todo.md	Todo EventKey, role scope, and todo fields
Friend events	event-contact.md	Friend EventKey, request and addition field parsing
Interactive card callback events	event-card.md	Callback subscription and payload parsing