dingtalk-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DingTalk Messaging Skill

钉钉消息Skill

Use this skill to run DingTalk messaging operations through

uxc

+ OpenAPI.

Reuse the

uxc

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

使用该Skill通过

uxc

+ OpenAPI执行钉钉消息操作。

复用

uxc

Skill以实现共享执行、认证和错误处理指引。

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.

已安装
```
uxc
```
并可在
```
PATH
```
中访问。
可访问
```
https://api.dingtalk.com/v1.0
```
的网络权限。

可访问精选OpenAPI Schema的URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/dingtalk-openapi-skill/references/dingtalk-messaging.openapi.json

已启用机器人消息权限的钉钉内部应用或应用套件。
钉钉应用
```
appKey
```
+
```
appSecret
```
，若使用手动备用方式则需当前
```
accessToken
```
。
目标发送流程对应的机器人代码、会话标识和用户标识。

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

该Skill仅覆盖聚焦即时通讯的窄请求/响应场景：

机器人一对一发送消息
机器人群组发送消息
服务群组发送消息
通过
```
unionId
```
进行极简用户查询

该Skill 不覆盖以下场景：

审批、考勤、管理或更广泛的企业应用工作流
旧版
```
oapi.dingtalk.com
```
端点
自定义机器人Webhook令牌/签名流程
入站回调或Webhook接收器运行时

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.

钉钉提供流模式等事件交付流程，但这些流程不在当前Skill的覆盖范围内。

当前

uxc subscribe

状态：

该Skill仅针对请求/响应式消息操作验证通过
目前未通过
```
uxc subscribe
```
验证钉钉入站事件/消息接收功能

可将钉钉视为未来通过流模式支持的订阅目标，而非当前已支持的即时通讯订阅提供商。

API Surface Choice

API接口选择

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.

该Skill特意绑定新版钉钉开放平台主机：

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

为保持认证和Schema格式一致，v1版本特意排除了旧版

oapi.dingtalk.com

接口。

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:

bash

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:

bash

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:

bash

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:

bash

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

钉钉v1 API使用应用

accessToken

凭证。

推荐的配置方式是将

appKey

appSecret

存储为凭证字段，让

uxc auth bootstrap

自动获取并刷新短期访问令牌。

引导式管理配置：

bash

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

若已拥有应用访问令牌，可使用手动备用方式：

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

当认证出现问题时，验证当前映射：

bash

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

Core Workflow

核心工作流

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
```

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

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

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\"}"}'

默认使用固定链接命令：

```
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
```

先查看操作Schema：

dingtalk-openapi-cli get:/contact/users/{unionId} -h

dingtalk-openapi-cli post:/robot/oToMessages/batchSend -h

dingtalk-openapi-cli post:/robot/groupMessages/send -h

在执行写入操作前优先进行读取/配置验证：

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

使用键值对或位置JSON参数执行操作：

键值对方式：

dingtalk-openapi-cli get:/contact/users/{unionId} unionId=$DINGTALK_UNION_ID language=zh_CN

位置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}
```

```
get:/contact/users/{unionId}
```

Messaging

消息发送

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

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

保持自动化基于JSON输出包；请勿使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
优先使用
```
uxc auth bootstrap
```
而非手动令牌管理。仍支持手动
```
accessToken
```
配置作为备用方案。
所有三种发送操作均为高风险写入操作。执行前需用户明确确认。
钉钉
```
msgParam
```
是JSON编码的字符串负载，而非嵌套JSON对象。发送前需仔细构建并验证该字符串。
```
robotCode
```
、
```
openConversationId
```
、
```
coolAppCode
```
及目标标识均为服务商特定的路由字段。即使认证有效，缺少其中任何一个通常都会导致发送失败。
本v1包装器不包含自定义机器人Webhook令牌/签名流程；仅使用基于应用的API。

dingtalk-openapi-cli <operation> ...

等同于

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/

使用模式：
```
references/usage-patterns.md
```

精选OpenAPI Schema：

references/dingtalk-messaging.openapi.json

钉钉开发者文档：https://open.dingtalk.com/document/