holon-run/uxc/dingtalk-openapi-skill

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

1. 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

1. 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

1. 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/