DingTalk

1. Overview

Dingtalk is an intelligent mobile office platform created by Alibaba Group specifically for Chinese enterprises. It integrates instant messaging, online documents, intelligent human resources, OA approvals, and other functions, aiming to enhance enterprise communication and collaboration efficiency.

With GoInsight's Dingtalk node, you can seamlessly integrate the powerful features of Dingtalk into your automated workflows, achieving comprehensive automated control over organizational structure, communication, and knowledge management. This includes:

• Organizational Structure Management: Automate the creation, querying, and searching of user and department information within the enterprise.
• Communication and Collaboration: Automatically create group chats, send work notifications, and manage message statuses.
• Knowledge Base and Documents: Create and manage spaces, documents, worksheets, and more in the Dingtalk knowledge base.
• Online Sheet Operations: Perform detailed operations on Dingtalk smart sheets, such as reading and writing cell data, adding/deleting rows and columns, and setting visibility.

2. Prerequisites

Before using this node, you need to meet the following conditions:

• Have a valid Dingtalk account and be a member of an enterprise organization.
• You need to have administrator privileges for the enterprise organization, or be authorized by an administrator, to create an application on the Dingtalk Open Platform and obtain API credentials.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This Dingtalk node primarily operates on core resources within an enterprise, such as chats, users, departments, knowledge bases, online sheets, and messages. The following table summarizes all supported operations:

Operation Details

Create Chat

Creates a new Dingtalk group chat with comprehensive settings, including group name (1-20 characters), owner, members (up to 40), permission to view historical messages, group management rights, and various feature toggles.

Input Parameters:

• Name: The name of the group chat (1-20 characters).
• Owner: The UserID of the group owner.
• UserIds: An array of member UserIDs (up to 40 members), also accepts a comma-separated string.

Options:

• ShowHistoryType: Whether new members can view chat history: 0-No, 1-Yes.
• Searchable: Whether the group is searchable.
• ValidationType: Group entry validation type: 0-No validation, 1-Validation required.
• MentionAllAuthority: @all permission: 0-Owner and admins only, 1-Everyone.
• ManagementType: Group management type: 0-Everyone can manage, 1-Owner and admins only.
• ChatBannedType: Group mute setting: 0-Not muted, 1-All members muted.

Output:

• ChatData (object): Group chat creation result data.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Create Doc

Creates a new document in a Dingtalk knowledge base.

Input Parameters:

• WorkspaceId: The ID of the knowledge base.
• Name: The name of the document to create.
• DocType: Document type: DOC (text), WORKBOOK (sheet), MIND (mind map), FOLDER (folder).
• OperatorId: The user UnionID of the operator.

Options:

• ParentNodeId: The parent node ID. If not provided, the document is created in the root directory.
• TemplateId: The document template ID.
• TemplateType: Document template type: public_template, team_template, user_template.

Output:

• DocData (object): Information about the created document.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Create User

Directly creates a new user in the Dingtalk organization's contact list.

Input Parameters:

• Name: The employee's name, must be 1-64 characters long.
• Mobile: The employee's mobile number, must be unique within the organization.
• DeptIdList: A comma-separated list of department IDs the user belongs to.

Options:

• JobNumber: The employee's job number.
• Email: The employee's email address.
• Title: The job title.
• WorkPlace: The work location.
• Remark: Additional remarks.
• Extension: Extra extension information.

Output:

• UserData (object): User creation result data.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Create Worksheet

Creates a new worksheet in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the target workbook where the worksheet will be created.
• SheetName: The name of the new worksheet to create.
• OperatorId: The UserID of the operator performing this action.

Output:

• SheetId (string): The ID of the created worksheet.
• SheetName (string): The name of the created worksheet.
• Created (bool): Whether the worksheet was successfully created.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Create Workspace

Creates a new knowledge base (space) in Dingtalk.

Input Parameters:

• Name: The name of the knowledge base to create.
• OperatorId: The UserID of the operator.

Options:

• Description: A description of the knowledge base.

Output:

• WorkspaceData (object): Information about the created knowledge base space.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Delete Columns

Deletes specified columns from a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Column: The starting column index to delete (1-based).
• ColumnCount: The number of columns to delete (defaults to 1).
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the column deletion was successful.
• DeletedColumnCount (number): The actual number of columns deleted.
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Delete Rows

Deletes specified rows from a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Row: The starting row index to delete (1-based).
• RowCount: The number of rows to delete (defaults to 1).
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the row deletion was successful.
• DeletedRowCount (number): The actual number of rows deleted.
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Delete Worksheet

Deletes a worksheet from a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the workbook containing the worksheet to delete.
• SheetId: The ID of the worksheet to delete.
• OperatorId: The UserID of the operator performing this action.

Output:

• Deleted (bool): Whether the worksheet was successfully deleted.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Batch Get Nodes

Batch retrieves detailed information for multiple nodes by providing a list of node IDs.

Input Parameters:

• NodeIds: A comma-separated list of node IDs.
• OperatorId: The ID of the operating user.

Output:

• NodeList (object-array): A list of nodes.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Batch Get Workspaces

Batch retrieves detailed information for multiple Dingtalk knowledge bases.

Input Parameters:

• WorkspaceIds: A comma-separated list of knowledge base space IDs.
• OperatorId: The ID of the operating user.

Output:

• WorkspaceList (object-array): A list of successfully retrieved knowledge bases.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Chat Info

Retrieves Dingtalk group chat information by its openConversationId.

Options:

• ChatId: The openConversationId of the chat to retrieve information for.

Output:

• ChatInfo (object): Detailed information of the group chat.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Dept Detail

Retrieves detailed information for a specific department in the Dingtalk organizational structure by department ID.

Input Parameters:

• DeptId: The ID of the department to query.

Options:

• Language: Language setting, defaults to zh_CN. Options: zh_CN, en_US.

Output:

• DeptDetail (object): Detailed department information.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Dept List

Retrieves a list of sub-departments under a specified parent department in the Dingtalk organizational structure.

Options:

• DeptId: The parent department ID, defaults to 1 (the root department).
• Language: Language setting, defaults to zh_CN. Options: zh_CN, en_US.

Output:

• Departments (object-array): A list of department information.
• TotalCount (number): The number of departments returned.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Dept Users

Retrieves a list of all users within a Dingtalk enterprise, supporting pagination and queries for specific departments.

Options:

• Cursor: Pagination cursor, defaults to 0.
• Size: Page size, defaults to 50, max is 100.
• DeptId: The ID of the department to get users from. If not specified, defaults to the root department (1).

Output:

• Users (object-array): A list of user information.
• HasMore (bool): Whether there is more data.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Message Status

Queries the sending status of a Dingtalk work notification message.

Input Parameters:

• AgentId: The agent ID of the application.
• TaskId: The task ID returned when the message was sent.

Output:

• MessageStatus (object): Detailed message status.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Node By Link

Retrieves Dingtalk node information via a URL link.

Input Parameters:

• NodeUrl: The URL link of the node to retrieve.
• OperatorId: The ID of the operating user.

Output:

• NodeData (object): Node information retrieved via the URL.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Node List

Retrieves the list of nodes in a Dingtalk knowledge base space.

Input Parameters:

• WorkspaceId: The knowledge base space ID.
• OperatorId: The ID of the operating user.
• ParentNodeId: The parent node ID; leave empty for the root level.

Options:

• MaxResults: Maximum number of results per page (1-100).
• NextToken: The token for the next page for pagination.

Output:

• NodeList (object-array): A list of nodes.
• NextToken (string): The next page token.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Range Data

Retrieves data from a specified a range of cells in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the target workbook.
• SheetId: The ID of the target worksheet.
• RangeAddress: The cell range address to retrieve data from (e.g., 'A1:C3').
• OperatorId: The ID of the operator performing the action.

Output:

• RangeData (object): Range data including values and metadata.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get User

Retrieves Dingtalk user details by userId or mobile number.

Options:

• UserId: The user's userId (mutually exclusive with Mobile).
• Mobile: The user's mobile number (mutually exclusive with UserId).

Output:

• UserData (object): User details.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get User Count

Gets the total number of users in a Dingtalk organization.

Options:

• OnlyActive: Whether to count only active users. Defaults to true.

Output:

• UserCount (number): The total number of users in the organization.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get UserID By UnionID

Retrieves a Dingtalk user ID by their union ID.

Input Parameters:

• UnionId: The union ID of the user to be converted.

Output:

• UserId (string): The user ID corresponding to the union ID.
• ContactType (number): User type: 0-internal employee, 1-external contact.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Worksheet

Retrieves Dingtalk worksheet details by workbook ID and worksheet ID.

Input Parameters:

• WorkbookId: The ID of the workbook containing the worksheet.
• SheetId: The ID of the worksheet to retrieve.
• OperatorId: The UserID of the operator performing this action.

Output:

• SheetData (object): Detailed worksheet information.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Worksheets

Retrieves all worksheets from a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the workbook to get all worksheets from.
• OperatorId: The UserID of the operator performing this action.

Output:

• SheetList (object-array): A list of all worksheets.
• SheetCount (number): The total number of worksheets.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Workspace

Retrieves Dingtalk knowledge base space information by its space ID.

Input Parameters:

• WorkspaceId: The ID of the knowledge base space to retrieve information for.
• OperatorId: The UserID of the operator.

Output:

• WorkspaceData (object): Detailed knowledge base space information.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Workspace Node

Gets detailed information for a specific node in a Dingtalk knowledge base space.

Input Parameters:

• NodeId: The ID of the node to retrieve information for.
• OperatorId: The UserID of the operator.

Output:

• NodeData (object): Detailed node information.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Get Workspaces

Retrieves a list of Dingtalk knowledge bases.

Input Parameters:

• OperatorId: The ID of the operating user.

Options:

• MaxResults: Maximum number of results per page (1-100).
• NextToken: The token for the next page for pagination.

Output:

• WorkspaceList (object-array): A list of knowledge bases.
• NextToken (string): The next page token.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Search Departments

Searches for departments within a Dingtalk enterprise by keywords such as department name, supporting fuzzy search and pagination.

Input Parameters:

• QueryWord: The search keyword (supports department name).

Options:

• Offset: Pagination offset, defaults to 0.
• Size: Page size, defaults to 10, max is 20.

Output:

• SearchResult (object): The search result from the API. Contains a list of departments and pagination info.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Search Users

Searches for users within a Dingtalk enterprise by keywords such as name and mobile number, supporting fuzzy search and pagination.

Input Parameters:

• QueryWord: The search keyword (supports name, mobile number, email).

Options:

• Offset: Pagination offset, defaults to 0.
• Size: Page size, defaults to 10, max is 20.

Output:

• SearchResult (object): The search result from the API. Contains a list of users and pagination info.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Send Work Notice

Sends a text or Markdown formatted Dingtalk work notification (corporate conversation message) to specified users.

Input Parameters:

• AgentId: The agentId of the Dingtalk application.
• UserIds: A comma-separated list of recipient userIds.
• MsgType: Message type: text/markdown.
• Content: The message content.

Options:

• Title: Markdown title (required for markdown type).

Output:

• MessageData (object): Message sending result data.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Set Columns Visibility

Sets the visibility (show/hide) of specified columns in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Column: The starting column index to set visibility for (1-based).
• ColumnCount: The number of columns to set visibility for (defaults to 1).
• Visibility: The visibility state: 'visible' for show, 'hidden' for hide.
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the column visibility operation was successful.
• AffectedColumnCount (number): The actual number of columns affected.
• Visibility (string): The visibility state that was set ('visible' or 'hidden').
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Set Rows Visibility

Sets the visibility (show/hide) of specified rows in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Row: The starting row index to set visibility for (1-based).
• RowCount: The number of rows to set visibility for (defaults to 1).
• Visibility: The visibility state: 'visible' for show, 'hidden' for hide.
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the row visibility operation was successful.
• AffectedRowCount (number): The actual number of rows affected.
• Visibility (string): The visibility state that was set ('visible' or 'hidden').
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Clear Range Content

Clears all content, including data and formatting, from a specified range in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the target workbook.
• SheetId: The ID of the target worksheet.
• RangeAddress**: The cell range address to clear all content from (e.g., 'A1:C3').
• OperatorId: The ID of the operator performing the action.

Output:

• ClearResult (object): The result of the clear operation.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Clear Range Data

Clears data from a specified range in a Dingtalk workbook but retains the formatting.

Input Parameters:

• WorkbookId: The ID of the target workbook.
• SheetId: The ID of the target worksheet.
• RangeAddress**: The cell range address to clear data from (e.g., 'A1:C3').
• OperatorId: The ID of the operator performing the action.

Output:

• ClearResult (object): The result of the clear operation.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Insert Columns Before

Inserts columns before a specified column index in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Column: The column index before which new columns will be inserted (1-based).
• ColumnCount: The number of columns to insert (defaults to 1).
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the column insertion was successful.
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Insert Rows Before

Inserts rows before a specified row index in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The unique identifier of the workbook.
• SheetId: The unique identifier of the worksheet within the workbook.
• Row: The row index before which new rows will be inserted (1-based).
• RowCount: The number of rows to insert (defaults to 1).
• OperatorId: The ID of the operator performing the action.

Output:

• Success (bool): Indicates if the row insertion was successful.
• StatusCode (number): Operation status code: 200 (Success), 500 (Server Error), -1 (Parameter Error).
• ErrorMessage (string): An error message if the operation failed, otherwise empty.

Recall Message

Recalls a Dingtalk work notification message.

Input Parameters:

• AgentId: The agent ID of the application.
• MsgTaskId: The message task ID returned when the message was sent.

Output:

• RecallResult (bool): Whether the message was successfully recalled.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

Update Range Data

Updates range data in a Dingtalk workbook.

Input Parameters:

• WorkbookId: The ID of the target workbook.
• SheetId: The ID of the target worksheet.
• RangeAddress: The cell range address to be updated (e.g., 'A1:C3').
• Values: A JSON string of a two-dimensional array of values to be updated.
• OperatorId: The ID of the operator performing the action.

Output:

• UpdateResult (object): The result of the update operation.
• StatusCode (number): HTTP status code.
• ErrorMessage (string): An error message if an error occurred.

5. Example Usage

This section will guide you through creating a simple workflow to send a text message to a specified user in Dingtalk.

Workflow Overview

A basic workflow consists of three nodes: Start -> Dingtalk: Send Work Notice -> Answer.

Step-by-Step Guide

1. Add a Tool Node:
   • On the workflow canvas, click the "+" sign to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select Dingtalk from the tool list.
   • In the list of supported operations for Dingtalk, click to select Send Work Notice, which will add the corresponding node to the canvas.
2. Configure the Node:
   • Click on the newly added Send Work Notice node, and its configuration panel will expand on the right.
   • Credential Configuration: At the top of the panel, find the credential field. Click the dropdown menu and select your pre-configured Dingtalk credential.
   • Parameter Entry: Fill in the following parameters according to your needs:
   • AgentId: Enter the AgentId of the application you created on the Dingtalk Open Platform. For example: 123456789.
   • UserIds: Enter the UserID of the user(s) who will receive the message. You can enter one or more, separated by commas. For example: manager001,user002.
   • MsgType: Enter the message type. For a plain text message, enter text.
   • Content: Enter the content of the message you want to send. For example: This is a test message from a GoInsight automated workflow.
3. Run and Validate:
   • Once all required parameters are correctly filled in, the error prompt in the top right corner of the workflow canvas will disappear.
   • Click the "Run" button in the top right corner of the canvas to execute the workflow.
   • After successful execution, you can click the log icon in the top right corner to view the detailed input and output of the node to verify if the operation was successful. The specified user(s) should also receive the message in Dingtalk.

Final Workflow Display

After completing the steps above, your entire workflow is configured. After clicking "Run," a work notification will be successfully sent to the specified user's Dingtalk client.

6. FAQs

Q: Why did my message fail to send?

A: Please check the following:

• Credentials and AgentId: Ensure the AgentId you entered in the node matches the selected credential (AppKey/AppSecret).
• Correct UserID: Confirm that the user IDs in the UserIds field are valid and exist in your enterprise organization.
• Application Permissions: Log in to the Dingtalk Open Platform and check if your application has the "Send Work Notification" API permission.
• IP Whitelist: Ensure that the outbound IP address of the GoInsight server has been added to your Dingtalk application's IP whitelist.
• Check Error Output: Review the ErrorMessage field in the node's output, which usually provides the specific reason for failure.

Q: How do I get a user's UserID?

A: You can obtain it in several ways:

• Using GoInsight Nodes: In your workflow, you can use the Get User or Search Users operations to query for user details, which include the UserID.
• Dingtalk Admin Console: Log in to your enterprise's Dingtalk admin console, find the employee in the "Contacts," and view their profile to find the UserID.

Q: I received a permission error (e.g., 401/403). What should I do?

A: Permission errors are usually related to credentials or application settings. Please check:

• Credential Validity: Confirm that the AppKey and AppSecret configured in GoInsight are correct and have not expired.
• API Permission Scope: On the Dingtalk Open Platform, check if your application has applied for and been granted the API permissions you want to call. For example, to create a user, you need "Contacts Management" related permissions.
• IP Whitelist: This is one of the most common reasons. Please ensure that the GoInsight platform's server IP address is correctly configured in your Dingtalk application's IP whitelist.

7. Official Documentation

For more in-depth information and advanced features of the Dingtalk API, please refer to the official documentation:

Dingtalk Official API Documentation