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

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

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

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