Overview
This node integrates with DingTalk robot APIs to send messages via two types of robots: a custom robot and a company internal development robot. It supports sending various message formats such as text, markdown, links, action cards with buttons, feed cards, images, and files.
Typical use cases include:
- Automating notifications or alerts in DingTalk groups or to individual users.
- Sending rich interactive messages with buttons for user actions.
- Distributing files or documents directly through DingTalk.
- Using either a custom webhook-based robot (with rate limits) or an enterprise internal robot with broader capabilities.
For example, you can configure the node to send a markdown-formatted alert to a DingTalk group using a custom robot, or send a file attachment to specific users via the company internal robot.
Properties
| Name | Meaning |
|---|---|
| Type | Select between "自定义机器人" (Custom Robot, limited to 20 calls per minute) and "企业内部开发机器人" (Company Internal Development Robot). |
| 是否使用JSON格式数据模式 (enableJsonMode) | Boolean flag to enable JSON mode where you provide the full message payload structure manually. |
| 数据内容 (json) | Raw JSON data content for the message when JSON mode is enabled. |
| 用户集合 (userIds) | Collection of user phone numbers (mobile) to send messages to; used only for company internal robot without JSON mode. |
| 消息类型 (msgKey/msgtype) | Message type options vary by robot type: - For custom robot: actionCard, feedCard, link, markdown, text. - For company internal robot: sampleActionCard2/3/4/5/6, sampleActionCard, sampleImageMsg, sampleLink, sampleMarkdown, sampleText, sampleFile. |
| 是否@所有人 (isAtAll) | Whether to @ all users in the message (only for custom robot text or markdown messages). |
| 被@人的手机号 (atMobiles) | Comma-separated mobile numbers of users to @ mention (custom robot, text/markdown, when not @all). |
| 被@人的用户Userid (atUserIds) | Comma-separated user IDs to @ mention (custom robot, text/markdown, when not @all). |
| 消息内容 (content/text/markdownText) | The main message content varies by message type: - Text content for text messages. - Markdown formatted text for markdown/actionCard. - Title and text for link messages. - File info for file messages. |
| 消息标题 (title) | Title shown on the first screen or message header, required for markdown, actionCard, and link messages. |
| 是否单个按钮 (isSingleButton) | For actionCard messages, whether there is a single button or multiple buttons. |
| 单个按钮的标题 (singleTitle) | Title of the single button (actionCard). |
| 点击消息跳转的URL (singleURL/messageUrl/url) | URL to open when clicking the message or button. Behavior differs on mobile (opens inside DingTalk client) and PC (sidebar or external browser). |
| 按钮集合 (btns) | Collection of buttons with titles and URLs for multi-button actionCard messages (custom robot). |
| 排列方式 (btnOrientation) | Button layout orientation for actionCard: vertical (0) or horizontal (1). |
| 链接集合 (lks) | Collection of links with title, URL, and image URL for feedCard messages (custom robot). |
| 文件名称 (fileName) | File name to display in DingTalk message (company internal robot, file message). Defaults to previous node's file name if empty. |
| 文件类型 (fileType) | File type (xlsx, pdf, zip, rar, doc, docx) for file messages (company internal robot). Defaults to previous node's file type if empty. |
| Input Binary Field (binaryPropertyName) | Name of the input binary field containing the file to upload (company internal robot, file message). |
Output
The node outputs an array of JSON objects corresponding to each input item processed:
- For custom robot, the output JSON contains the response from the DingTalk webhook API after sending the message.
- For company internal robot, the output JSON contains the response from the DingTalk batch send API, including any failed user information if applicable.
- In case of errors, if "Continue On Fail" is enabled, the output includes the original input JSON plus error details.
No binary output is produced by this node.
Dependencies
- Requires credentials for either:
- A DingTalk custom robot webhook URL and secret key.
- A DingTalk company internal API with appKey, appSecret, access token, and robot code.
- Uses external libraries:
axiosfor HTTP requests.- Alibaba Cloud DingTalk SDK clients for internal robot API calls.
- Node.js crypto module for signing webhook requests.
- Environment must allow outbound HTTPS requests to DingTalk API endpoints.
Troubleshooting
- Rate limiting on custom robot: Custom robots have a limit of 20 calls per minute. Exceeding this will cause errors. Use company internal robot for higher throughput.
- Invalid credentials: Errors retrieving access tokens or sending messages usually indicate incorrect or expired credentials. Verify API keys and secrets.
- User ID resolution failure: When sending to company internal robot users by mobile number, if some mobiles cannot be resolved to user IDs, those users are reported as failures in output.
- Malformed JSON in JSON mode: If JSON mode is enabled, ensure the JSON message content is valid and matches DingTalk API schema.
- Missing required parameters: Required fields like message title, content, or URLs must be provided according to message type, otherwise the API call will fail.
- File upload issues: For file messages, ensure the binary input field exists and contains valid file data. Also, supported file types are limited.