DingTalk OpenAPI Skill

Operate DingTalk messaging APIs through UXC with a curated OpenAPI schema, app-token bearer auth, and robot/service-group guardrails.

Security Scan

The skill's code and instructions match its stated purpose (sending DingTalk messages via uxc), but the package metadata does not declare the credentials and environment access the runtime docs clearly require — an incoherence that deserves attention before installing.

Purpose & Capability

Name, description, OpenAPI schema, and operations (user lookup and three send endpoints) align with a DingTalk messaging skill. The required operations and auth (appKey/appSecret or accessToken) are coherent with the described capability.

Instruction Scope

SKILL.md gives concrete, narrow runtime instructions that stay within messaging scope (linking the schema, inspecting schema, read-then-write pattern, and explicit write-confirmation guardrails). It requires the external 'uxc' CLI and network access to api.dingtalk.com and a schema URL on raw.githubusercontent.com. It does not instruct reading unrelated system files or exfiltrating data, but it does instruct the agent to consume secrets (env vars) at runtime.

Install Mechanism

No install spec is present (instruction-only), so nothing arbitrary will be downloaded or written at install time. The included validate.sh is a harmless local validation script (requires ripgrep and jq) and does not perform network installs or execute remote code.

Credentials

The SKILL.md expects app credentials and environment variables (DINGTALK_APP_KEY, DINGTALK_APP_SECRET, DINGTALK_ACCESS_TOKEN, DINGTALK_UNION_ID) and recommends storing tokens in env vars and binding them into uxc. However, the registry metadata lists no required environment variables or primary credential. That mismatch means the manifest under-reports the secrets the skill needs and obscures the credential blast radius.

Persistence & Privilege

always is false and the skill is not requesting system-wide persistence or modifying other skills. Autonomous invocation is allowed by default (disable-model-invocation: false) — normal for skills — but this combined with the unreported credential requirements increases potential impact if misused.

What to consider before installing

This skill appears to do what it says (a narrow DingTalk messaging wrapper for uxc), but the package metadata does not declare the credentials the runtime docs require. Before installing: - Verify you trust the 'uxc' tool referenced; the skill delegates auth and calls through uxc. If you don't already trust uxc, review its code and auth behavior. - Expect to provide app credentials (appKey/appSecret) or an access token and at least one identifier (unionId). Treat those as sensitive: store them in a secure secret store, not in plaintext shell history. - Confirm the skill will always ask for explicit confirmation before performing message sends (SKILL.md requests this); if you need to prevent automated sends, disable autonomous invocation or require manual approval in your agent policy. - The skill pulls an OpenAPI schema from raw.githubusercontent.com but also includes a local schema copy; verify the schema you will use and prefer the included local copy to avoid silent remote changes. - The absence of declared required env vars in the registry metadata is an information gap — ask the publisher to update the manifest to list required secrets and the primary credential so you can review requested privileges more easily. If you cannot confirm these items, treat this skill as higher risk and avoid installing it until the manifest and trust of uxc are clarified.

DingTalk Messaging Skill

Use this skill to run DingTalk messaging operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, auth, and error-handling guidance.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://api.dingtalk.com/v1.0.
• Access to the curated OpenAPI schema URL:
  • https://raw.githubusercontent.com/holon-run/uxc/main/skills/dingtalk-openapi-skill/references/dingtalk-messaging.openapi.json
• A DingTalk internal app or app suite with bot messaging permissions enabled.
• A DingTalk app appKey + appSecret, or a current accessToken if you are using the manual fallback path.
• Robot code, conversation identifiers, and user identifiers for the target send flows.

Scope

This skill covers a narrow IM-focused request/response surface:

• one-to-one bot sends
• group bot sends
• service group sends
• minimal user lookup by unionId

This skill does not cover:

• approval, attendance, admin, or broader enterprise app workflows
• old oapi.dingtalk.com endpoints
• custom robot webhook token/signature flows
• inbound callback or webhook receiver runtime

Subscribe / Stream Mode Status

DingTalk has event-delivery flows such as Stream Mode, but those flows are outside the current scope of this skill.

Current uxc subscribe status:

• this skill is validated only for request/response messaging operations
• DingTalk inbound event/message intake is not currently validated through uxc subscribe

Treat DingTalk as a possible future subscribe target via Stream Mode rather than a currently supported IM subscribe provider.

API Surface Choice

This skill is intentionally pinned to the newer DingTalk Open Platform host:

• https://api.dingtalk.com/v1.0

The older oapi.dingtalk.com surface is intentionally excluded from v1 to keep auth and schema shape consistent.

Authentication

DingTalk v1 APIs use app accessToken credentials.

Preferred setup is to store appKey + appSecret as credential fields and let uxc auth bootstrap fetch and refresh the short-lived access token automatically.

Bootstrap-managed setup:

uxc auth credential set dingtalk-app \
  --auth-type bearer \
  --field app_key=env:DINGTALK_APP_KEY \
  --field app_secret=env:DINGTALK_APP_SECRET

uxc auth bootstrap set dingtalk-app \
  --token-endpoint https://api.dingtalk.com/v1.0/oauth2/accessToken \
  --header 'Content-Type=application/json' \
  --request-json '{"appKey":"{{field:app_key}}","appSecret":"{{field:app_secret}}"}' \
  --access-token-pointer /accessToken \
  --expires-in-pointer /expireIn

uxc auth binding add \
  --id dingtalk-app \
  --host api.dingtalk.com \
  --path-prefix /v1.0 \
  --scheme https \
  --credential dingtalk-app \
  --priority 100

Manual fallback if you already have an app access token:

curl -sS https://api.dingtalk.com/v1.0/oauth2/accessToken \
  -H 'Content-Type: application/json' \
  -d '{"appKey":"dingxxxx","appSecret":"xxxx"}'

Configure one bearer credential and bind it to the DingTalk API host:

uxc auth credential set dingtalk-app \
  --auth-type bearer \
  --secret-env DINGTALK_ACCESS_TOKEN

uxc auth binding add \
  --id dingtalk-app \
  --host api.dingtalk.com \
  --path-prefix /v1.0 \
  --scheme https \
  --credential dingtalk-app \
  --priority 100

Validate the active mapping when auth looks wrong:

uxc auth binding match https://api.dingtalk.com/v1.0

Core Workflow

1. Use the fixed link command by default:

   • command -v dingtalk-openapi-cli
   • If missing, create it: uxc link dingtalk-openapi-cli https://api.dingtalk.com/v1.0 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/dingtalk-openapi-skill/references/dingtalk-messaging.openapi.json
   • dingtalk-openapi-cli -h

2. Inspect operation schema first:

   • dingtalk-openapi-cli get:/contact/users/{unionId} -h
   • dingtalk-openapi-cli post:/robot/oToMessages/batchSend -h
   • dingtalk-openapi-cli post:/robot/groupMessages/send -h

3. Prefer read/setup validation before writes:

   • dingtalk-openapi-cli get:/contact/users/{unionId} unionId=$DINGTALK_UNION_ID
   • dingtalk-openapi-cli post:/robot/oToMessages/batchSend -h
   • dingtalk-openapi-cli post:/serviceGroup/messages/send -h

4. Execute with key/value or positional JSON:

   • key/value: dingtalk-openapi-cli get:/contact/users/{unionId} unionId=$DINGTALK_UNION_ID language=zh_CN
   • positional JSON: dingtalk-openapi-cli post:/robot/groupMessages/send '{"openConversationId":"cidxxxx","robotCode":"dingxxxx","msgKey":"sampleText","msgParam":"{\"content\":\"Hello from UXC\"}"}'

Operation Groups

User Lookup

• get:/contact/users/{unionId}

Messaging

• post:/robot/oToMessages/batchSend
• post:/robot/groupMessages/send
• post:/serviceGroup/messages/send

Guardrails

• Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Prefer uxc auth bootstrap over manual token management. Manual accessToken setup is still supported as a fallback.
• All three send operations are high-risk writes. Require explicit user confirmation before execution.
• DingTalk msgParam is a JSON-encoded string payload, not a nested JSON object. Build and validate that string carefully before sending.
• robotCode, openConversationId, coolAppCode, and target identifiers are all provider-specific routing fields. Missing any of them generally means the send will fail even if auth is valid.
• This v1 wrapper does not include custom robot webhook token/sign flows; use app-based APIs only.
• dingtalk-openapi-cli <operation> ... is equivalent to uxc https://api.dingtalk.com/v1.0 --schema-url <dingtalk_openapi_schema> <operation> ....

References

• Usage patterns: references/usage-patterns.md
• Curated OpenAPI schema: references/dingtalk-messaging.openapi.json
• DingTalk developer docs: https://open.dingtalk.com/document/