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 INLINECODE9
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 INLINECODE12
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:
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:
CODEBLOCK0
Manual fallback if you already have an app access token:
CODEBLOCK1
Configure one bearer credential and bind it to the DingTalk API host:
CODEBLOCK2
Validate the active mapping when auth looks wrong:
CODEBLOCK3
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
- INLINECODE21
- 2. Inspect operation schema first:
-
dingtalk-openapi-cli get:/contact/users/{unionId} -h
-
dingtalk-openapi-cli post:/robot/oToMessages/batchSend -h
- INLINECODE24
- 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
- INLINECODE27
- 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:
INLINECODE29
Operation Groups
User Lookup
Messaging
- - INLINECODE31
- INLINECODE32
- INLINECODE33
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. - INLINECODE43 ,
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.
- INLINECODE46 is equivalent to
uxc https://api.dingtalk.com/v1.0 --schema-url <dingtalk_openapi_schema> <operation> ....
References
- - Usage patterns: INLINECODE48
- Curated OpenAPI schema: INLINECODE49
- DingTalk developer docs: https://open.dingtalk.com/document/
钉钉消息技能
使用此技能通过 uxc + OpenAPI 执行钉钉消息操作。
复用 uxc 技能以实现共享执行、认证和错误处理指导。
前提条件
- - uxc 已安装并可在 PATH 中使用。
- 可访问 https://api.dingtalk.com/v1.0 网络。
- 可访问精选的 OpenAPI 模式 URL：
- https://raw.githubusercontent.com/holon-run/uxc/main/skills/dingtalk-openapi-skill/references/dingtalk-messaging.openapi.json
- - 一个已启用机器人消息权限的钉钉内部应用或应用套件。
- 钉钉应用的 appKey + appSecret，或当前 accessToken（如果使用手动回退路径）。
- 目标发送流程所需的机器人编码、会话标识符和用户标识符。
范围
此技能涵盖一个狭窄的、专注于即时通讯的请求/响应接口：
- - 一对一机器人发送
- 群机器人发送
- 服务群发送
- 通过 unionId 进行最小化的用户查询
此技能不涵盖：
- - 审批、考勤、管理或更广泛的企业应用工作流
- 旧的 oapi.dingtalk.com 端点
- 自定义机器人 webhook 令牌/签名流程
- 入站回调或 webhook 接收器运行时
订阅/流模式状态
钉钉具有事件传递流程（如流模式），但这些流程不在当前技能范围内。
当前 uxc subscribe 状态：
- - 此技能仅针对请求/响应消息操作进行了验证
- 钉钉入站事件/消息接收目前未通过 uxc subscribe 验证
将钉钉视为未来可能通过流模式支持的订阅目标，而非当前支持的即时通讯订阅提供者。
API 接口选择
此技能特意固定使用较新的钉钉开放平台主机：
- - https://api.dingtalk.com/v1.0
较旧的 oapi.dingtalk.com 接口被有意排除在 v1 之外，以保持认证和模式结构的一致性。
认证
钉钉 v1 API 使用应用 accessToken 凭证。
首选设置是将 appKey + appSecret 存储为凭证字段，并让 uxc auth bootstrap 自动获取和刷新短期访问令牌。
Bootstrap 管理设置：
bash
uxc auth credential set dingtalk-app \
--auth-type bearer \
--field appkey=env:DINGTALKAPP_KEY \
--field appsecret=env:DINGTALKAPP_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:appkey}},appSecret:{{field:appsecret}}} \
--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
如果已有应用访问令牌，手动回退方式：
bash
curl -sS https://api.dingtalk.com/v1.0/oauth2/accessToken \
-H Content-Type: application/json \
-d {appKey:dingxxxx,appSecret:xxxx}
配置一个 bearer 凭证并将其绑定到钉钉 API 主机：
bash
uxc auth credential set dingtalk-app \
--auth-type bearer \
--secret-env DINGTALKACCESSTOKEN
uxc auth binding add \
--id dingtalk-app \
--host api.dingtalk.com \
--path-prefix /v1.0 \
--scheme https \
--credential dingtalk-app \
--priority 100
当认证看起来有问题时，验证活动映射：
bash
uxc auth binding match https://api.dingtalk.com/v1.0
核心工作流
- 1. 默认使用固定链接命令：
- command -v dingtalk-openapi-cli
- 如果缺失，创建它：
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. 首先检查操作模式：
- 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. 在写入操作前优先进行读取/设置验证：
- dingtalk-openapi-cli get:/contact/users/{unionId} unionId=$DINGTALK
UNIONID
- dingtalk-openapi-cli post:/robot/oToMessages/batchSend -h
- dingtalk-openapi-cli post:/serviceGroup/messages/send -h
- 4. 使用键/值或位置 JSON 执行：
- 键/值：
dingtalk-openapi-cli get:/contact/users/{unionId} unionId=$DINGTALK
UNIONID language=zh_CN
- 位置 JSON：
dingtalk-openapi-cli post:/robot/groupMessages/send {openConversationId:cidxxxx,robotCode:dingxxxx,msgKey:sampleText,msgParam:{\content\:\Hello from UXC\}}
操作组
用户查询
- - get:/contact/users/{unionId}
消息发送
- - post:/robot/oToMessages/batchSend
- post:/robot/groupMessages/send
- post:/serviceGroup/messages/send
安全护栏
- - 保持自动化在 JSON 输出信封上；不要使用 --text。
- 首先解析稳定字段：ok、kind、protocol、data、error。
- 优先使用 uxc auth bootstrap 而非手动令牌管理。手动 accessToken 设置仍作为回退方式支持。
- 所有三个发送操作都是高风险写入操作。执行前需要明确的用户确认。
- 钉钉 msgParam 是一个 JSON 编码的字符串负载，而非嵌套的 JSON 对象。在发送前仔细构建和验证该字符串。
- robotCode、openConversationId、coolAppCode 和目标标识符都是特定于提供者的路由字段。即使认证有效，缺少其中任何一个通常也会导致发送失败。
- 此 v1 封装不包括自定义机器人 webhook 令牌/签名流程；仅使用基于应用的 API。
- dingtalk-openapi-cli ... 等同于 uxc https://api.dingtalk.com/v1.0 --schema-url openapischema> ...。
参考
- - 使用模式：references/usage-patterns.md
- 精选的 OpenAPI 模式：references/dingtalk-messaging.openapi.json
- 钉钉开发者文档：https://open.dingtalk.com/document/
