Skip to content

dingtalk.md

Latest commit

 

History

History
116 lines (75 loc) · 5.57 KB

dingtalk.md

File metadata and controls

116 lines (75 loc) · 5.57 KB
Raw
title DingTalk Integration
nav_title DingTalk
description Authorize a DingTalk bot by QR code and run over DingTalk Stream, with no public callback URL required.
order 4

DingTalk Integration

For organizations already running on DingTalk: one QR scan authorizes a bot, and the adapter connects over DingTalk Stream, so no public callback URL or tunnel is needed. Replies stream through an AI Card by default. Only private chats are supported, and tappable approval cards need one extra template ID — otherwise approval is text replies.

Bind the bot by QR code

  1. Open Settings → IM Adapters and select the DingTalk tab.
  2. Under Bind DingTalk bot with QR, select Scan to bind.
  3. Scan with the DingTalk mobile app and confirm bot creation and authorization.
  4. Wait for Desktop to report the bound state.

Client ID and Client Secret are filled in and written to local configuration automatically, and the adapter reconnects with them.

Manual credentials

If QR binding is unavailable, fill in the fields below the QR area yourself:

  • Client ID — the DingTalk application appKey
  • Client Secret — the application appSecret
  • Stream Endpoint — optional; defaults to https://api.dingtalk.com
  • Permission Card Template ID — optional; when set, permission requests prefer an interactive card
  • Allowed Users — optional; explicit DingTalk user IDs

Select Save, and the adapter opens a DingTalk Stream connection with the new credentials.

Authorize a user

Binding the bot does not authorize every DingTalk account.

  1. Back at the top of the page, under Pairing, select Generate Code.
  2. Send the six-character code to the bot in a private chat.
  3. Once pairing is confirmed, you can start chatting.

Codes are valid for 60 minutes and work once. Paired accounts appear under Paired Users and can be revoked at any time; a revoked user needs a fresh code.

Projects and sessions

With Default Project set, the first accepted message opens a session in that directory. Without it, the bot lists recent projects; reply with a number, project name, or absolute path.

Later messages in the same chat reuse that session. /new picks another project; /clear empties the context while keeping the project binding.

Commands

DingTalk has no bot menu like Feishu, so the chat box is the only entry point. After pairing, the bot suggests /help.

  • /help or 帮助 — show available commands
  • /status or 状态 — project, branch, model, run state, and task summary
  • /projects or 项目列表 — list recent projects again
  • /new or 新会话 — clear the current binding and choose a project
  • /new <number, project name, or absolute path> — start directly in that project
  • /clear or 清空 — clear context, keep the project binding
  • /stop or 停止 — stop the current generation

Approval and reply behavior

By default a permission request arrives as text. Reply with one of:

  • /allow <requestId> — allow once
  • /always <requestId> — persist the matching approval
  • /deny <requestId> — deny

With a published template entered in Permission Card Template ID, the adapter prefers an interactive card and receives the button callback over DingTalk Stream. Text commands stay available whenever a card fails to send or cannot be seen.

Normal replies prefer AI Card streaming. Image attachments are downloaded and passed as inline image input; oversized attachments are reported back in the chat.

Unbind

Two levels:

  • Unbind bot account clears the DingTalk credentials, the permission card template ID, and this platform's authorization lists. Binding again means scanning or entering credentials again.
  • Unbind next to a name under Paired Users revokes only that person.

Development

Packaged Desktop starts the sidecar automatically. Run it by hand only when working from source:

cd adapters
bun install
bun run dingtalk

Optional overrides:

export DINGTALK_CLIENT_ID="..."
export DINGTALK_CLIENT_SECRET="..."
export DINGTALK_STREAM_ENDPOINT="https://api.dingtalk.com"
export DINGTALK_PERMISSION_CARD_TEMPLATE_ID="..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"

Normal Desktop use needs none of these; QR binding or manual entry writes the local configuration.

Troubleshooting

Still unauthorized after a successful scan. That is the expected flow. Scanning only stores bot credentials; the individual user still has to send a pairing code or appear in Allowed Users.

Scanning fails or waits forever. Select Scan to bind again for a fresh QR code. If it still fails, enter Client ID and Client Secret manually.

The adapter reports missing credentials. Neither the environment variables nor dingtalk.clientId / dingtalk.clientSecret in ~/.claude/adapters.json took effect. Complete QR binding or manual entry in Settings first.

No permission card appears. Confirm the template ID belongs to a published template, that the template supports the callback route the adapter uses, and that the bot has published a new version. Text approval works regardless.

No replies. Confirm Desktop is running, the tab shows the bound state, the sender is paired or allowlisted, and ~/.claude/adapters.json is writable. When running from source, also confirm ADAPTER_SERVER_URL points at the running Desktop server.

Source

index.ts, helpers.ts, ai-card.ts, permission-card.ts, and media.ts under adapters/dingtalk/, plus pairing.ts, session-store.ts, ws-bridge.ts, and http-client.ts under adapters/common/.