Home > Tools

DingTalk

1. Overview

Dingtalk is an intelligent mobile office platform designed by Alibaba Group specifically for Chinese enterprises, integrating instant messaging, online documents, smart human resources, OA approval, and other functions, aimed at improving enterprise communication and collaboration efficiency.

Through GoInsight's Dingtalk node, you can seamlessly integrate Dingtalk's powerful capabilities into your automated workflows, achieving comprehensive automated control of organizational structure, communication and collaboration, and knowledge management. Including:

  • Organizational Structure Management: Automate the creation, query, and search of users and departments within the enterprise.
  • Communication and Collaboration: Automatically create group chats, send work notifications, and manage message status.
  • Knowledge Base and Documents: Create and manage spaces, documents, worksheets, etc. in the Dingtalk knowledge base.
  • Online Spreadsheet Operations: Perform granular operations on Dingtalk smart spreadsheets, such as reading and writing cell data, adding and 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 rights to the enterprise organization, or be authorized by an administrator, in order to create applications and obtain API credentials on the Dingtalk Open Platform.

3. Credentials

For detailed guidance on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This DingTalk node covers group chats, messages, organization contacts, knowledge base spaces and nodes, document blocks, smart worksheets, and AI Notable tables. The table below summarizes all currently published operations:

Resource Operation Description
Group Chat Create Chat Create a new DingTalk group chat with owner, members, and group management settings.
Group Chat Get Chat Info Retrieve detailed information about a DingTalk group chat by chat ID.
Message Get Message Status Check delivery status for a work notice sent by Send Work Notice.
Message Recall Message Recall a previously sent DingTalk work notice.
Message Send Robot Group Message Send a text or Markdown message to a DingTalk group through a custom robot webhook.
Message Send Work Notice Send a DingTalk work notice to selected users through an internal app.
User Create User Create a user in the DingTalk organization directory.
User Get Dept Users List users in a department with pagination support.
User Get User Get user details by DingTalk user ID or mobile number.
User Get User Count Return the total user count for the organization.
User Get UserID By UnionID Resolve a DingTalk user ID from a UnionID.
User Search Users Search enterprise users by keyword, such as name or mobile number.
Department Get Dept Detail Get detailed department information by department ID.
Department Get Dept List List sub-departments under a parent department.
Department Search Departments Search departments by keyword.
Knowledge Base Space Batch Get Workspaces Retrieve multiple knowledge base workspaces in one request.
Knowledge Base Space Create Workspace Create a DingTalk knowledge base workspace.
Knowledge Base Space Get Workspace Get a knowledge base workspace by workspace ID.
Knowledge Base Space Get Workspaces List knowledge base workspaces available to the operator.
Knowledge Base Node Batch Get Nodes Retrieve details for multiple knowledge base nodes.
Knowledge Base Node Create Doc Create a document, workbook, mind map, or folder in a DingTalk knowledge base.
Knowledge Base Node Get Node By Link Resolve a DingTalk document link into node metadata.
Knowledge Base Node Get Node List List nodes in a knowledge base workspace.
Knowledge Base Node Get Workspace Node Get detailed information for one knowledge base node.
Document Block Append Paragraph Inline Element Append an inline element, such as an image or link, to a paragraph block.
Document Block Append Text to Paragraph Append plain text to the end of a paragraph block.
Document Block Delete Block Delete one block element from a DingTalk document.
Document Block Insert Block Insert a block element into a DingTalk document.
Document Block Insert Content Insert Markdown content into a DingTalk document.
Document Block Overwrite Doc Replace the full body of a DingTalk document with new Markdown content.
Document Block Query Block Elements Query top-level block elements in a DingTalk document.
Document Block Update Block Element Update a block element in a DingTalk document.
Worksheet Create Worksheet Create a worksheet in a DingTalk smart workbook.
Worksheet Delete Worksheet Delete a worksheet from a DingTalk smart workbook.
Worksheet Get Worksheet Get worksheet metadata by workbook ID and sheet ID.
Worksheet Get Worksheets List all worksheets in a DingTalk smart workbook.
Column Delete Columns Delete columns from a DingTalk smart worksheet.
Column Insert Columns Before Insert columns before a specified column index.
Column Set Columns Visibility Show or hide worksheet columns.
Row Append Rows Append rows after existing data in a DingTalk smart worksheet.
Row Delete Rows Delete rows from a DingTalk smart worksheet.
Row Insert Rows Before Insert empty rows before a specified row index.
Row Insert Rows Before with Data Insert rows and write cell data in one operation.
Row Set Rows Visibility Show or hide worksheet rows.
Cell Range Data Clear Range Content Clear cell values and formatting from a worksheet range.
Cell Range Data Clear Range Data Clear cell values from a worksheet range while preserving formatting.
Cell Range Data Get Range Data Read values and metadata from a worksheet cell range.
Cell Range Data Update Range Data Write values to a worksheet cell range.
AI Notable Sheet Create Notable Sheet Create a data sheet in a DingTalk AI Notable base.
AI Notable Sheet Delete Notable Sheet Delete a data sheet from a DingTalk AI Notable base.
AI Notable Sheet Get Notable Sheet Get metadata for one DingTalk AI Notable data sheet.
AI Notable Sheet Get Notable Sheets List data sheets in a DingTalk AI Notable base.
AI Notable Sheet Update Notable Sheet Rename or update metadata for a DingTalk AI Notable data sheet.
AI Notable Field Create Notable Field Create a field in a DingTalk AI Notable data sheet.
AI Notable Field Delete Notable Field Delete a field from a DingTalk AI Notable data sheet.
AI Notable Field Get Notable Fields List fields in a DingTalk AI Notable data sheet.
AI Notable Field Update Notable Field Update a field in a DingTalk AI Notable data sheet.
AI Notable Record Delete Notable Records Delete records from a DingTalk AI Notable data sheet.
AI Notable Record Get Notable Record Get one record from a DingTalk AI Notable data sheet.
AI Notable Record Insert Notable Records Insert records into a DingTalk AI Notable data sheet.
AI Notable Record List Notable Records List records from a DingTalk AI Notable data sheet with pagination and filters.
AI Notable Record Update Notable Records Update existing records in a DingTalk AI Notable data sheet.

Operation Details

Create Chat

Create a new DingTalk group chat with owner, members, and group management settings.

Create a new DingTalk group chat. Requires group name (1-20 chars), owner user ID, and member user IDs (max 40). The owner is automatically added to the member list. NOTE: This action does NOT have idempotency protection - duplicate chats may be created on retry. Use AdditionalFields for advanced settings like @all permission, management type, and group mute.

Input Parameters:

  • Name (string): Group chat name. Must be 1-20 characters. Example: "Engineering Team".
  • Owner (string): User ID of the group owner. The owner is automatically added to the member list. Retrieve via Get_User or Search_Users action. Example: "manager001".
  • UserIds (string-array): User ID list for group members (max 40). The owner is automatically included even if not listed. Retrieve user IDs via Get_User or Search_Users action. Example: ["user001", "user002"].

Options:

  • ShowHistoryType (number): Whether new members can view chat history. 0: cannot view history, 1: can view history. Default: 1. Default: 1.
  • Searchable (number): Whether the group is searchable in DingTalk. 0: not searchable, 1: searchable. Default: 1. Default: 1.
  • ValidationType (number): Join validation type. 0: anyone can join directly, 1: requires owner approval to join. Default: 0. Default: 0.
  • AdditionalFields (object): Optional advanced settings (key-value object). Use for less common group configuration options. Available fields: - MentionAllAuthority (number): @all permission. 0: only owner and admins can @all, 1: everyone can @all. Default: 0. - ManagementType (number): Group management type. 0: everyone can manage, 1: only owner and admins can manage. Default: 0. - ChatBannedType (number): Group mute setting. 0: not muted, 1: all members muted (only owner can speak). Default: 0. Example: {"MentionAllAuthority": 1, "ManagementType": 1, "ChatBannedType": 0}

Output:

  • ChatData (object): Group chat creation result. On success contains: - errcode (number): Error code, 0 means success. - errmsg (string): Error message, "ok" on success. - chatid (string): The created group chat ID, used for subsequent chat operations (e.g., Send_Chat_Message, Update_Chat). - openConversationId (string): Open conversation ID for the group. - conversationTag (number): Conversation tag number.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
  • ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Chat Info

Retrieve detailed information about a DingTalk group chat by chat ID.

Retrieve detailed information about a DingTalk group chat by its chat ID, including group name, member count, owner, and group settings.

Input Parameters:

  • ChatId (string): The unique chat ID of the DingTalk group conversation. This is the chatId returned when creating a group chat via the DingTalk API, not the openConversationId. You can obtain it from the Create Chat API response or from DingTalk admin console. Example: "chatb0e6xxxxxxxxxx"

Output:

  • ChatInfo (object): Group chat detail object containing: - openConversationId (string): The open conversation ID of the group chat. - title (string): Group chat name/title. - memberCount (number): Total number of members in the group. - owner (string): UserId of the group owner. - createTime (string): Group creation timestamp in milliseconds. - icon (string): Group avatar URL, empty if not set. - showHistoryType (number): Whether new members can view chat history. 0=not visible, 1=visible. - searchable (number): Whether the group is searchable. 0=not searchable, 1=searchable. - chatBannedType (number): Group mute mode. 0=not muted, 1=all muted. - managementType (number): Group management type. 0=all members can manage, 1=only owner can manage. - mentionAllAuthority (number): Who can @All. 0=all members, 1=only owner.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
  • ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Message Status

Check delivery status for a work notice sent by Send Work Notice.

Get the delivery status of a DingTalk work notification previously sent via the Send Work Notice action. Use the TaskId returned by Send Work Notice to check delivery progress. Uses DingTalk China Open API (oapi.dingtalk.com), not an overseas region endpoint.

Input Parameters:

  • AgentId (string): The agentId of the DingTalk internal application (numeric). Usually configured by an administrator from the open platform app details; end users rarely need the developer console. Pass as a numeric string. Example: "3558010000"
  • TaskId (string): The async task ID from Send Work Notice (numeric). DingTalk supports querying only recent tasks (about the last 24 hours). Pass as a numeric string. Example: "2956140000"

Output:

  • MessageStatus (object): Object from the API field progress: progress_in_percent (number, 0-100), status (number) per DingTalk: 0=not started, 1=in progress, 2=finished. When status is 2, use progress_in_percent as the completion percentage.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Recall Message

Recall a previously sent DingTalk work notice.

Recall a DingTalk work notification. WARNING: Permanent for recipients; recalled content cannot be restored. Set Confirm=true only when intended.

Input Parameters:

  • AgentId (string): Numeric agentId of your DingTalk internal app (from open.dingtalk.com app basic info). Same app that sent the notice. Example: "3558010000"
  • MsgTaskId (string): task_id from Send Work Notice response (MessageData / async send result). Used to target which sent notice to recall. Example: "abc-task-id"
  • Confirm (bool): Must be true to recall. Recalled notices cannot be restored for users. Example: true

Output:

  • RecallResult (bool): Whether the message was successfully recalled
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Send Robot Group Message

Send a text or Markdown message to a DingTalk group through a custom robot webhook.

Send a text or markdown message to a DingTalk group via custom robot webhook. Prerequisites: RobotAccessToken from group robot webhook URL; RobotSecret if signing is enabled. Side effects: posts immediately to the group and may notify members.

Input Parameters:

  • RobotAccessToken (string): The access_token from the custom group robot webhook URL. In DingTalk: open the target group -> Settings -> Smart Group Assistant -> Robot -> copy the access_token value from the Webhook URL (query parameter). Example: "a1b2c3d4e5f6g7h8i9j0".
  • Content (string): Message body. For text: plain string. For markdown: Markdown text. Example (text): "[Monitor] Service is healthy." Example (markdown): "## Deploy Report
  • Status: Success
  • Version: 1.2.3"

Options:

  • RobotSecret (string): Optional signing secret for the custom robot. Required only when the robot security mode is "Sign". Omit or leave empty if the robot uses custom keywords or IP whitelist only. Example: "SECxxxxxxxx".
  • MsgType (string): Message type. Default: "text". Must be one of: - "text": Plain text message. - "markdown": Markdown-formatted message (Title is required). Default: text.
  • Title (string): Markdown message title. Required when MsgType is "markdown"; ignored for "text". Example: "Deploy Report".
  • IsAtAll (bool): Whether to @all members in the group. true=@all, false=do not @all. Default: false. Default: false.
  • AtMobiles (string-array): Mobile phone numbers to @mention in the message. Pass a string-array of mainland China mobile numbers. Example: ["13800138000","13900139000"]. Default: empty array. Default: [].

Output:

  • MessageData (object): DingTalk robot webhook API response. On success contains: - errcode (number): 0 means success. - errmsg (string): "ok" on success.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Upstream HTTP status code. 0 if the request did not reach DingTalk.
  • StatusCode (number): Operation status code: 200=completed, -1=parameter error, 500=network/system error.
  • ErrorMessage (string): Detailed error message if any error occurred. Empty string on full success.

Send Work Notice

Send a DingTalk work notice to selected users through an internal app.

Send a Dingtalk Work Notice (corp conversation message) to specific users with text or markdown content.

Input Parameters:

  • AgentId (number): The agentId of the DingTalk internal application. You can find it in the DingTalk Developer Console (open.dingtalk.com) under your app's basic information page. It is a numeric ID. Example: 3558010000
  • UserIds (string-array): Recipient DingTalk userIds within the org (userid, not unionId). Pass a string-array, or a single comma-separated string (both accepted by code). Obtain via Get_Dept_Users or Get_User. Example: ["user001","user002"] or "user001,user002"
  • MsgType (string): Message type to send. Must be one of: - "text": Plain text message, suitable for simple notifications. - "markdown": Markdown-formatted message, suitable for rich-text reports or structured content. When using markdown, the Title parameter is required.
  • Content (string): Message body content. For text type: plain text string. For markdown type: markdown-formatted string supporting headings, bold, lists, and links. Example (text): "Deployment completed successfully." Example (markdown): "## Weekly Report
  • Revenue: $12,000
  • New Users: 150

View Details"

Options:

  • Title (string): Title for the markdown message. Required when MsgType is "markdown", ignored when MsgType is "text". This title is shown in the notification preview on mobile devices. Example: "Weekly Report Notification"

Output:

  • MessageData (object): DingTalk API response object. On success it contains: - errcode (number): Error code, 0 means success. - errmsg (string): Error message, "ok" on success. - task_id (number): Async message task ID for tracking delivery status. - request_id (string): Request ID for troubleshooting.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): The original HTTP status code returned by the upstream DingTalk API. Default value is 0. Use this for debugging and troubleshooting. - 0: The request did not reach the upstream API (e.g., network timeout, connection refused). - 200: Upstream API returned success. - 4xx: Client error from upstream (e.g., 400 Bad Request, 401 Unauthorized). - 5xx: Server error from upstream.
  • StatusCode (number): Operation status code: - 200: Success. The upstream API request completed successfully. Check ErrorMessage for business-level errors. - -1: Parameter validation error. One or more input parameters are invalid or missing. - 500: System error. Network timeout, connection failure, or response parsing error. The operation may be retried.
  • ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. - When StatusCode is 200 and ErrorMessage is empty: Operation fully succeeded. - When StatusCode is 200 and ErrorMessage is not empty: Upstream API returned a business error (e.g., invalid userId, permission denied). - When StatusCode is -1: Describes which parameter is invalid and how to fix it. - When StatusCode is 500: Describes the system-level error (timeout, connection failure, etc.).

Create User

Create a user in the DingTalk organization directory.

Create a new user in the DingTalk organization directory. DingTalk enforces mobile uniqueness per organization, so duplicate mobile numbers will be rejected (natural idempotency).

Input Parameters:

  • Name (string): Employee full name (1-64 characters). This is the display name shown in the DingTalk organization directory. Example: "John Smith"
  • Mobile (string): Employee mobile phone number. Must be unique within the organization (DingTalk uses mobile as the unique identifier, so duplicate mobile numbers will be rejected). Supports digits with optional '+' country code prefix. Example: "13800138000" or "+8613800138000"
  • DeptIdList (string): Comma-separated department IDs that the user belongs to. A user must belong to at least one department. Retrieve valid department IDs using the Get_Dept_List action. Example: "12345" (single) or "12345,67890" (multiple departments).

Options:

  • JobNumber (string): Employee job number / employee ID used for internal HR identification. Example: "EMP001"
  • Email (string): Employee email address for internal communication. Example: "john.smith@company.com"
  • Title (string): Job title or position within the organization. Example: "Senior Engineer"
  • WorkPlace (string): Office location or work site. Example: "Building A, Floor 5"
  • AdditionalFields (object): Optional key-value pairs for extra fields not covered by the explicit parameters above. Common fields: - remark (string): Notes or comments about the employee - extension (object): Custom extension attributes defined in DingTalk admin console - hide_mobile (boolean): Whether to hide the mobile number in the directory - senior_mode (boolean): Whether to enable senior mode - org_email (string): Organization email address Example: {"remark": "New hire from campus recruitment", "hide_mobile": false}

Output:

  • UserData (object): The created user data returned by DingTalk API. On success (errcode=0), contains: - errcode (number): Error code, 0 means success - errmsg (string): Error message, "ok" on success - result (object): Created user info with userid (string) - the unique user ID in DingTalk - request_id (string): DingTalk API request tracking ID
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): The original HTTP status code returned by the upstream DingTalk API. Default 0 means the request did not reach upstream (e.g., network timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
  • ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Dept Users

List users in a department with pagination support.

Get all user lists within DingTalk enterprise, supporting pagination query and specific department query, providing basic data for user discovery and batch operations.

Options:

  • Cursor (number): List offset / starting index. Use 0 for the first page; when HasMore is true, advance by Size for the next page. Example: 0 Default: 0.
  • Size (number): Page size, default 50, maximum 100 Default: 50.
  • DeptId (number): DingTalk department id to list users from. Use 1 for root. For other departments, use DeptId values from Get_Dept_List -> Departments[].DeptId. Example: 123456789 Default: 1.

Output:

  • Users (object-array): User rows: userid (string), name (string), dept_id_list (array of numbers) when present, unionid, mobile, email, and other DingTalk user fields returned by the API.
  • HasMore (bool): Whether there is more data
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Get User

Get user details by DingTalk user ID or mobile number.

Get DingTalk user detail by userId or mobile phone number. Provide one of UserId or Mobile (not both). If using Mobile, the system auto-resolves to userId first, then fetches full user details.

Options:

  • UserId (string): DingTalk userId of the target user. Provide either UserId or Mobile (one is required, not both). If you already have the userId, use this parameter for faster lookup. You can obtain userIds via the Get Dept Users or Search Users action. Example: "user123456"
  • Mobile (string): User mobile phone number. Provide either Mobile or UserId (one is required, not both). If you only know the user's phone number, use this parameter and the system will auto-resolve the userId first. Must include country code for international numbers (e.g. "+8613800138000"). Example: "+8613800138000"

Output:

  • UserData (object): User detail object containing: userid (string, unique ID), name (string, display name), mobile (string, phone number), email (string), dept_id_list (array of numbers, department IDs the user belongs to), job_number (string, employee ID), title (string, job title), work_place (string, office location), active (boolean, whether account is active).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
  • ErrorMessage (string): Error message if any.

Get User Count

Return the total user count for the organization.

Read-only: returns total user count for the org. No side effects.

Options:

  • OnlyActive (bool): Whether to count only active users. Default is true. Default: true.

Output:

  • UserCount (number): Total number of users in the organization
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Get UserID By UnionID

Resolve a DingTalk user ID from a UnionID.

Get DingTalk user ID by union ID.

Input Parameters:

  • UnionId (string): The union ID of the user. Retrieved from third-party platforms integrated with DingTalk.

Output:

  • UserId (string): The user ID corresponding to the union ID
  • ContactType (number): User type: 0-internal employee, 1-external contact
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Search Users

Search enterprise users by keyword, such as name or mobile number.

Search users within DingTalk enterprise by keywords such as name and mobile number, supporting fuzzy search and pagination.

Input Parameters:

  • QueryWord (string): Search keyword to find DingTalk users. Supports fuzzy matching by user name. Enter a partial or full user name to search. Example: "John"

Options:

  • Offset (number): Pagination offset for pagination. Default 0. Use with Size to fetch subsequent pages. Default: 0.
  • Size (number): Number of users per page. Default 10, maximum 20. Default: 10.

Output:

  • SearchResult (object): Search result object containing: list (array of user objects, each with userid, name, mobile, email, dept_id_list, unionid), totalCount (number, total number of matching users), hasMore (boolean, whether more results exist beyond the current page).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Dept Detail

Get detailed department information by department ID.

Get detailed information of a specific department by department ID in DingTalk organization structure, providing comprehensive department data including permissions and settings.

Input Parameters:

  • DeptId (number): Department id to load. Use DeptId from each object in Get_Dept_List -> Departments (same value as API dept_id). Use 1 for root. Example: 123456789

Options:

  • Language (string): Locale for department name/display fields: zh_CN (Simplified Chinese, default), en_US (English). Default: zh_CN.

Output:

  • DeptDetail (object): Full dept payload: DeptId, Name, ParentId, CreateDeptGroup (auto-create dept groupchat flag), AutoAddUser, FromUnionOrg, Tags, Order, DeptManagerUseridList (manager userids), MemberCount, DeptGroupChatId, OuterDept, OuterPermitDepts, OuterPermitUsers, OrgDeptOwner, DeptPerimits, etc.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP status code
  • ErrorMessage (string): Error message if any

Get Dept List

List sub-departments under a parent department.

Get list of sub-departments under a specified parent department in DingTalk organization structure, providing comprehensive department information including hierarchy and settings.

Options:

  • DeptId (number): Parent department whose direct children you list. Use 1 for top-level departments. For deeper levels: call with DeptId=1, pick a child DeptId from Departments[], then call again with that id. Example: 1 Default: 1.
  • Language (string): Locale for names: zh_CN (Simplified Chinese, default), en_US (English). Default: zh_CN.

Output:

  • Departments (object-array): Each item: DeptId, Name, ParentId, CreateDeptGroup, AutoAddUser, FromUnionOrg, Tags, Order, DeptManagerUseridList, MemberCount, DeptGroupChatId, SourceIdentifier, Ext (same shape as Get_Dept_Detail).
  • TotalCount (number): Number of departments returned
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP status code
  • ErrorMessage (string): Error message if any

Search Departments

Search departments by keyword.

Search departments within DingTalk enterprise by keywords such as department name, supporting fuzzy search and pagination.

Input Parameters:

  • QueryWord (string): Search keywords (supports department name)

Options:

  • Offset (number): Pagination offset, default 0 Default: 0.
  • Size (number): Page size, default 10, maximum 20 Default: 10.

Output:

  • SearchResult (object): Detailed search result including list of departments (dept_id, name, parent_id, etc.) and pagination info (totalCount, hasMore).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP status code
  • ErrorMessage (string): Error message if any

Batch Get Workspaces

Retrieve multiple knowledge base workspaces in one request.

Batch retrieve multiple DingTalk knowledge base (workspace) details in one API call. More efficient than calling Get Workspace multiple times. Maximum 50 workspaces per request.

Input Parameters:

  • WorkspaceIds (string): Comma-separated list of DingTalk knowledge base (workspace) IDs to retrieve. Maximum 50 IDs per request. You can obtain workspace IDs by calling the Get Workspaces action. Supports both English comma (,) and Chinese comma (,). Example: "wspxxx123,wspxxx456,wspxxx789"
  • OperatorId (string): DingTalk user ID of the operator performing this query. Used for permission verification. The operator must have read access to the requested workspaces. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • WorkspaceList (object-array): Array of workspace objects retrieved from DingTalk. Each workspace object contains: id (string, workspace unique identifier), name (string, workspace display name), description (string, workspace description), createTime (number, creation timestamp in milliseconds), type (string, workspace type e.g. TEAM or PERSONAL).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error (e.g., empty workspace IDs, exceeded 50 IDs limit), 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any.

Create Workspace

Create a DingTalk knowledge base workspace.

Create a DingTalk wiki workspace. NOT idempotent; duplicate calls create multiple workspaces. Set Confirm=true only when intended.

Input Parameters:

  • Name (string): Name of the knowledge base to be created.
  • OperatorId (string): UnionId of the user creating the workspace (the actor whose credential/scope is used). Obtain via Get_User or Search_Users. Example: "user123456"
  • Confirm (bool): Must be true to create a workspace. NOT idempotent; duplicate calls create multiple workspaces. Example: true

Options:

  • Description (string): Description of the knowledge base (optional).

Output:

  • WorkspaceData (object): Created workspace info (e.g. workspace_id, name, description, url).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Get Workspace

Get a knowledge base workspace by workspace ID.

Get DingTalk workspace information by workspace ID.

Input Parameters:

  • WorkspaceId (string): Retrieve using Get_Workspaces action.
  • OperatorId (string): The user ID of the operator. Retrieve using Get_User or Search_Users action.

Output:

  • WorkspaceData (object): Workspace object. Contains id, name, createTime, etc.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Get Workspaces

List knowledge base workspaces available to the operator.

Get list of DingTalk knowledge bases.

Input Parameters:

  • OperatorId (string): The user ID of the operator. Retrieve using Get_User or Search_Users action.

Options:

  • MaxResults (number): Maximum number of results per page (1-100). Default: 20.
  • NextToken (string): Next page token for pagination.

Output:

  • WorkspaceList (object-array): Array of workspace objects. Each has id, name, createTime, etc. Use workspace id for Get_Node_List and other actions.
  • NextToken (string): Next page token
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Batch Get Nodes

Retrieve details for multiple knowledge base nodes.

Batch retrieve multiple node details by providing a list of node ID pairs using DingTalk Enterprise API.

Input Parameters:

  • NodeIds (string): Comma-separated list of DingTalk knowledge base node IDs to retrieve. Maximum 30 IDs per request. You can obtain node IDs by calling the Get Node List action. Supports both English comma (,) and Chinese comma (,). Example: "node123,node456,node789"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • NodeList (object-array): Array of node objects retrieved from DingTalk. Each node object contains: nodeId (string, unique identifier), name (string, display name), workspaceId (string, workspace the node belongs to), type (string, node type: DOC/SHEET/MIND/FOLDER), url (string, access URL), parentNodeId (string, parent folder ID).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Create Doc

Create a document, workbook, mind map, or folder in a DingTalk knowledge base.

Create a new document in a DingTalk knowledge base. Supports documents, spreadsheets, mind maps, and folders. NOTE: This action is not idempotent - calling it multiple times will create duplicate documents.

Input Parameters:

  • WorkspaceId (string): The DingTalk knowledge base (workspace) ID where the new document will be created. Prefer Get Workspaces in automation; the raw ID may not be obvious in the mobile/desktop UI. Example: "wspxxx123"
  • Name (string): Display name of the new document. DingTalk typically allows up to about 255 characters; avoid path-like characters (e.g. / \ : * ? " < > \|). Duplicate names are allowed-each call still creates a new document. Example: "2024 Q1 Project Plan".
  • DocType (string): The type of document to create. Must be one of: - "DOC": Standard DingTalk document (rich text). Use for notes, plans, articles; supports rich text, images, tables, mentions. - "WORKBOOK": Smart spreadsheet (Excel-like). Use for grids, budgets, tracking; supports formulas and charts. - "MIND": Mind map. Use for brainstorming or outlining. - "FOLDER": Container only. Use to group docs; create children by passing this folder's nodeId as ParentNodeId. Tip: Prefer DOC for general prose.
  • OperatorId (string): Operator DingTalk unionId (unique across orgs)-NOT org-scoped userid. Used for permission checks; the user must have write access (e.g. editor/admin) on the workspace. Obtain: Get User or Search Users (API), or admin/member UIs where unionId may appear in details. Example: "union6d447xxxxxxxxxxxxx4f4a"

Options:

  • ParentNodeId (string): Parent folder node ID; use string "0" for workspace root. Prefer Get Node List for the workspace-client tree IDs are not always the same as API node IDs. Example: "0" or a nodeId from Get Node List.
  • TemplateId (string): Optional template ID when creating from a DingTalk doc template; set together with TemplateType. Source: org template gallery or template picker. Example: "tpl_abc123".
  • TemplateType (string): Required when TemplateId is set. Must be one of: - "public_template": Official catalog templates - "team_template": Org-shared templates - "user_template": Personal templates for the current user Omit both TemplateId and TemplateType for a blank document.

Output:

  • DocData (object): Created document payload: workspaceId (string), nodeId (string, use as ParentNodeId for children or in follow-up API calls), docKey (string, document key for doc APIs / linking), url (string, open in browser).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Node By Link

Resolve a DingTalk document link into node metadata.

Get DingTalk knowledge base node details by its URL. Resolves a DingTalk document link into node metadata including nodeId, name, type, and workspaceId.

Input Parameters:

  • NodeUrl (string): The DingTalk document URL (link) to resolve into node information. Copy the URL from DingTalk's document page or knowledge base. Example: "https://alidocs.dingtalk.com/i/nodes/xxx123"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • NodeData (object): Node detail object containing: nodeId (string, unique node identifier), name (string, node display name), workspaceId (string, workspace the node belongs to), type (string, node type: DOC=document, SHEET=spreadsheet, MIND=mind map, FOLDER=folder), url (string, access URL), createTime (string, creation timestamp), creatorId (string, creator user ID).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Node List

List nodes in a knowledge base workspace.

Get list of nodes in a DingTalk knowledge base workspace using v2.0 API.

Input Parameters:

  • WorkspaceId (string): DingTalk wiki workspace id. From Get_Workspaces / Batch_Get_Workspaces: use workspace_id (or equivalent id) on each workspace row. Example: "wsxxx123"
  • OperatorId (string): UnionId of the user listing nodes (permission/audit). Get_User or Search_Users. Example: "user123456"
  • ParentNodeId (string): Parent folder/node id. Use "0" or empty string "" to list top-level nodes of the workspace; use a child nodeId from a previous response to drill down (both mean root when empty). Example: "" or "nd_parent_123"

Options:

  • MaxResults (number): Maximum number of results per page (1-100). Default: 20.
  • NextToken (string): Next page token for pagination.

Output:

  • NodeList (object-array): Array of node objects. Each has nodeId, name, nodeType, parentNodeId, hasChildren, createTime, etc. Use nodeId for Get_Node_By_Link and Batch_Get_Nodes.
  • NextToken (string): Next page token
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Get Workspace Node

Get detailed information for one knowledge base node.

Get detailed information about a specific node within a DingTalk workspace.

Input Parameters:

  • NodeId (string): Wiki/node id string for a document or folder inside the workspace. From Get_Node_List -> NodeList[].nodeId (or equivalent id field). Example: "ndxxx456"
  • OperatorId (string): UnionId of the user performing the read (for permission). Get_User or Search_Users. Example: "user123456"

Output:

  • NodeData (object): Raw node object: nodeId (string id), title (display name), type (e.g. wiki/doc/folder per API), wikiId (owning workspace id when present), plus other API fields.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Append Paragraph Inline Element

Append an inline element, such as an image or link, to a paragraph block.

Append an inline element (sticker, image, link, etc.) to the end of a paragraph block in a DingTalk DOC. Requires DocumentId (docKey/dentryUuid), paragraph blockId, operatorId (unionId), elementType, and properties. NOT idempotent - each call appends another inline element. Side effects: modifies document content.

Input Parameters:

  • DocumentId (string): Document ID (docKey or dentryUuid per DingTalk API path docKey). From Create Doc DocData.docKey, or dentryUuid in https://alidocs.dingtalk.com/i/nodes/{id} URLs.
  • BlockId (string): Target paragraph blockId (required path param). Obtain from Query Block Elements; must be a paragraph block.
  • OperatorId (string): Operator DingTalk unionId (NOT org userid). Must have write permission. Example: "union6d447xxxxxxxxxxxxx4f4a".
  • ElementType (string): Inline element type: sticker, image, link, etc. See DingTalk inline element data structure documentation.
  • Properties (object): Properties map for the inline element, e.g. {"code": "smile"} for sticker. JSON object per DingTalk docs.

Output:

  • InlineElementData (object): Appended inline element: elementId, elementType, index, parentId, and type-specific fields (e.g. sticker).
  • ApiSuccess (bool): Upstream API success flag (true when DingTalk returns success=true).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
  • ErrorMessage (string): Error message if any. Empty string on success.

Append Text to Paragraph

Append plain text to the end of a paragraph block.

Append plain text to the end of a paragraph block in a DingTalk document (append text to paragraph). NOT idempotent; requires Confirm=true.

Input Parameters:

  • DocumentId (string): Maps to API path parameter docKey. Use Create Doc DocData.docKey or dentryUuid from document URL (e.g. Zxxxxa-id in alidocs links). Example: "QoJGq7xxx"
  • BlockId (string): Paragraph block id from Query Block Elements (blockType paragraph). Example: "lc4si5p3n84zwqxxx"
  • OperatorId (string): Operator UnionId (NOT org userid). Get User / Search Users. Example: "union6d447xxxxxxxxxxxxx4f4a"
  • Text (string): Plain text appended after the paragraph's existing content. Example: " - status update"
  • Confirm (bool): GI write gate only (not sent to DingTalk API). Must be true to append. NOT idempotent. Example: true

Output:

  • ApiSuccess (bool): Upstream success flag when returned by DingTalk.
  • Result (object): Upstream API result object (official return field).
  • BlockData (object): Paragraph element after append (result.data when present).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Delete Block

Delete one block element from a DingTalk document.

Delete one block element (DELETE /v1.0/doc/suites/documents/{docKey}/blocks/{blockId}?operatorId=...). DocumentId maps to path docKey; BlockId maps to path blockId; OperatorId maps to query operatorId (unionId). WARNING: Permanent. Requires Confirm=true and non-empty Reason (GI safety, not in API). Obtain BlockId from Query Block Elements; DocumentId from Create Doc DocData.docKey or document URL dentryUuid.

Input Parameters:

  • DocumentId (string): Maps to API path docKey. Document ID (docKey or dentryUuid). From Create Doc DocData.docKey, or dentryUuid from URL https://alidocs.dingtalk.com/i/nodes/Zxxxxa-id. Example: "docxxx" or "Zxxxxa-id"
  • BlockId (string): Block id to delete. From Query Blocks result item id. Example: "lc4si5p3n84zwqxxx"
  • OperatorId (string): Operator unionId (NOT org userid). Get User or Search Users. Example: "union6d447xxxxxxxxxxxxx4f4a"
  • Confirm (bool): Must be true to delete. WARNING: Permanent; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Deleted (bool): Whether the block was deleted. true = success; false = failed (see ErrorMessage).
  • BlockId (string): The blockId that was requested for deletion (echo for audit).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Insert Block

Insert a block element into a DingTalk document.

Insert a block element (POST .../documents/{documentId}/blocks). Path: DocumentId (docKey/dentryUuid). Query: OperatorId (unionId). Body: Element (required), optional BlockId, Index, Where. NOT idempotent. Side effects: modifies document content.

Input Parameters:

  • DocumentId (string): Document ID (DocData.docKey or dentryUuid). From Create Doc DocData.docKey, or from URL https://alidocs.dingtalk.com/i/nodes/{dentryUuid}. Example: "QoJGq7xxx".
  • OperatorId (string): Query: operatorId. User unionId (NOT org userid); obtain via Get User / Search Users or Get User. Required. Must have document write permission. Example: "union6d447xxxxxxxxxxxxx4f4a".
  • Element (object): Body: element (required). BlockElement map: blockType plus the matching property object, e.g. {"blockType": "paragraph", "paragraph": {"text": "Hello"}}. See DingTalk for other types.

Options:

  • BlockId (string): Body: blockId (optional). Target block id from Query Block Elements. If omitted, Index is used as anchor; if both omitted, inserts at document end.
  • Index (number): Body: index (optional, integer). When blockId is absent, use the index-th top-level block (0-based). If blockId and index are both omitted, defaults to document end.
  • Where (string): Body: where (optional). Insert after or before the anchor block: "after" (API default) or "before".

Output:

  • BlockData (object): Inserted block payload: id (string, use in follow-up block APIs), blockType, type-specific fields, index.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
  • ErrorMessage (string): Error message if any. Empty string on success.

Insert Content

Insert Markdown content into a DingTalk document.

Insert Markdown into a DingTalk DOC. NOT idempotent - set Confirm=true only when intended. Requires Storage.File.Write and DocumentId (docKey / dentryUuid). IMPORTANT: ONLY markdown content type is supported; HTML, plain text, and other formats are rejected. Failure example: when DingTalk returns 401, ErrorMessage is like API Error (401): {"errcode":"Unauthorized.SubUser","errmsg":"app or user does not have permission"}, Hint is Verify DingTalk credential (Client ID / Secret) and app permissions., Retryable is false, and OriginalStatusCode is 401.

Input Parameters:

  • DocumentId (string): Document ID: docKey from Create Doc (DocData.docKey), or dentryUuid from URL https://alidocs.dingtalk.com/i/nodes/{id}. Same value as nodeId for wiki DOC nodes in many cases. Example: "QoJGq7xxx"
  • OperatorId (string): Operator DingTalk unionId (NOT org userid). The operator must have edit permission on the document. Obtain it from Get User or Search Users, using the returned unionId field. unionId is DingTalk's global user identifier; org userid is enterprise-scoped and is not accepted by this document API. Example: "union6d447xxxxxxxxxxxxx4f4a"
  • MarkdownContent (string): Markdown text to insert (headings, lists, paragraphs). Example: "## Status
  • item one
  • item two"
  • Confirm (bool): Must be true to insert content. NOT idempotent; retries duplicate inserted blocks. Example: true

Options:

  • ContentType (string): DingTalk content.type; ONLY markdown IS SUPPORTED (default). Other values such as html or text cause validation error. Example: "markdown" Default: markdown.
  • Path (number-array): Optional JSON-style number array for nested insert position (document root or BlockElement children). Omit it or use [] for root placement; use [0, 2] to target child index 2 under block 0. The runtime also accepts a JSON array string for compatibility, for example "[0, 2]". Example: [0, 2]
  • Index (number): Optional insert index used with Path (0-based child index). Example: 1

Output:

  • InsertResult (object): DingTalk insert-content API body. Core fields: success (bool) indicates whether DingTalk accepted the insert; result (object, optional) contains upstream insert details when returned. Empty object {} means the action failed before a successful upstream body was available. See ResponseExample for shape.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code from DingTalk API. 0 if request did not reach upstream.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Overwrite Doc

Replace the full body of a DingTalk document with new Markdown content.

Overwrite the entire body of a DingTalk document with new Markdown content. DESTRUCTIVE: replaces all existing content; it cannot be undone via this API.

Input Parameters:

  • DocumentId (string): Document identifier: DocData.docKey from Create Doc, or nodeId/dentryUuid from Get Node List / Get Node By Link / document URL (e.g. https://alidocs.dingtalk.com/i/nodes/Zxxxxa-id -> Zxxxxa-id). Example: "QoJGq7xxx".
  • OperatorId (string): Query parameter operatorId: operator DingTalk unionId (NOT org-scoped userid). User must have edit permission. Obtain via Get User or Search Users. Example: "union6d447xxxxxxxxxxxxx4f4a".
  • Content (string): Body parameter content: full Markdown body to write (max 50,000 characters). Replaces the entire document. Example: "# Title

Paragraph text."

  • Confirm (bool): Must be true to overwrite document content. WARNING: Permanently replaces the entire body; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Options:

  • DataType (string): Body parameter dataType: content format. Only "markdown" is supported (default). Leave empty to use markdown. Default: markdown.

Output:

  • OverwriteResult (object): Upstream overwrite API response (may be empty on success).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code from upstream. 0 if request did not reach upstream.
  • StatusCode (number): 200=Success, -1=Parameter validation error, 500=System error.
  • ErrorMessage (string): Error message if any. Empty string on success.

Query Block Elements

Query top-level block elements in a DingTalk document.

Query first-level block elements of a DingTalk document. Read-only; requires Storage.File.Read. Official DingTalk docs expose StartIndex/EndIndex filters but no HasMore, NextToken, or TotalCount; continue by calling the next explicit index window. Related: Create Doc / Get Node By Link for DocumentId.

Input Parameters:

  • DocumentId (string): Maps to API path parameter docKey (docKey or dentryUuid per DingTalk docs). Sources: DocData.docKey from Create Doc; dentryUuid from URL https://alidocs.dingtalk.com/i/nodes/{id}; doc_key/nodeId from Get Node By Link NodeData. Example: "QoJGq7xxx"
  • OperatorId (string): Maps to API query operatorId (required). User unionId - obtain via Get User / Search Users (unionid field). NOT org-scoped userid. Example: "union6d447xxxxxxxxxxxxx4f4a"

Options:

  • StartIndex (number): Maps to API query startIndex (optional, integer >= 0). Start from the Nth top-level block in the document. Use -1 or default to omit. Example: 0 Default: -1.
  • EndIndex (number): Maps to API query endIndex (optional, integer >= 0). Query through the Nth top-level block (inclusive per DingTalk). Use -1 or default to omit. Must be >= StartIndex when both set. Example: 20 Default: -1.
  • BlockType (string): Maps to API query blockType (optional). Filter by block element type; see DingTalk block element data structure. Examples: paragraph, heading, unorderedList, orderedList, table, blockquote, unknown. Leave empty for all types.

Output:

  • BlockList (object-array): Array of top-level block elements for the requested index range. Each item typically includes blockType, type-specific fields (e.g. paragraph.text), id (block id for insert/update APIs), and index. Official API does not return HasMore, NextToken, or TotalCount.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout).
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Update Block Element

Update a block element in a DingTalk document.

Update a block element in a DingTalk document (PATCH semantics, paragraph blocks only per DingTalk API).

Input Parameters:

  • DocumentId (string): Path: documentId (required). Document ID: DocData.docKey from Create Doc, or dentryUuid from URL https://alidocs.dingtalk.com/i/nodes/{dentryUuid}. Example: "QoJGq7xxx".
  • BlockId (string): Path: blockId (required). Target block id from Query Block Elements (Query Block Elements; response field id). Example: "lc4si5p3n84zwqxxx".
  • OperatorId (string): Query: operatorId (required). User unionId (NOT org userid); obtain via Get User / Search Users or Get User. Example: "union6d447xxxxxxxxxxxxx4f4a".
  • Element (object): Body: element (required). BlockElement map: blockType plus matching property object. PATCH - only sent fields change. Paragraph updates only per DingTalk API. Example: {"blockType":"paragraph","paragraph":{"text":"Hello"}}.

Output:

  • ApiSuccess (bool): Upstream success flag when returned by DingTalk.
  • BlockResult (object): Upstream result object (may include result array per API).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Create Worksheet

Create a worksheet in a DingTalk smart workbook.

Create a new worksheet in DingTalk workbook.

Input Parameters:

  • WorkbookId (string): Smart workbook id (wb...). From Get_Node_List / Get_Workspace_Node or URL - not the wiki workspace_id. Example: "wb123456789012345678"
  • SheetName (string): The name of the new worksheet to be created.
  • OperatorId (string): UnionId of the operator. Get_User or Search_Users. Example: "user123456"
  • Confirm (bool): Must be true to create a worksheet (write). Example: true

Output:

  • SheetId (string): The ID of the created worksheet
  • SheetName (string): The name of the created worksheet
  • Created (bool): Whether the worksheet was created successfully
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Delete Worksheet

Delete a worksheet from a DingTalk smart workbook.

Delete a worksheet from a DingTalk smart workbook. WARNING: This operation is permanent and cannot be undone. All data in the worksheet will be lost.

Input Parameters:

  • WorkbookId (string): Smart workbook id (wb...). From Get_Node_List / Get_Workspace_Node node payload or workbook URL. Example: "wb123456789012345678"
  • SheetId (string): Worksheet id to delete (not tab title). Get_Worksheets -> each item's id. WARNING: Permanent. Example: "sh123456789012345678"
  • OperatorId (string): UnionId of the operator. Get User or Search Users. Example: "user123456"
  • Confirm (bool): Must be true to delete the sheet. WARNING: Permanent; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Deleted (bool): Whether the worksheet was successfully deleted. true = deletion succeeded, false = deletion failed (check ErrorMessage for details).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Worksheet

Get worksheet metadata by workbook ID and sheet ID.

Get DingTalk worksheet details by workbook ID and sheet ID.

Input Parameters:

  • WorkbookId (string): The ID of the workbook containing the worksheet. Retrieve using Get_Workspaces action.
  • SheetId (string): The ID of the worksheet to retrieve. Retrieve using Get_Worksheets action.
  • OperatorId (string): The user ID of the operator performing this action. Retrieve using Get_User or Search_Users action.

Output:

  • SheetData (object): Worksheet details including id (string), name (string), visibility (string), rowCount (int), columnCount (int).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Get Worksheets

List all worksheets in a DingTalk smart workbook.

Get all worksheets from DingTalk workbook.

Input Parameters:

  • WorkbookId (string): Smart workbook id (wb...). From Get_Node_List / workbook URL / Get_Workspace_Node. Example: "wb123456789012345678"
  • OperatorId (string): UnionId for smart-doc API access. Not org userid. Get_User / Search_Users. Example: "user123456"

Output:

  • SheetList (object-array): List of worksheets, each with id (worksheet ID) and name (worksheet name).
  • SheetCount (number): Total number of worksheets
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Delete Columns

Delete columns from a DingTalk smart worksheet.

Delete specified columns from a DingTalk spreadsheet. Warning: This operation permanently removes the columns and their data; it cannot be undone.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. 'Sheet1'). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • Column (number): The 1-based column index where deletion starts. Column 1 = the first column (A), Column 2 = the second column (B), etc. Example: 3
  • ColumnCount (number): Number of columns to delete starting from the Column position. Must be a positive integer. Example: 3
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • Success (bool): Indicates whether the column deletion operation was successful.
  • DeletedColumnCount (number): The actual number of columns that were deleted.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Insert Columns Before

Insert columns before a specified column index.

Insert columns before the specified column index in a DingTalk spreadsheet.

Input Parameters:

  • WorkbookId (string): The unique identifier of the workbook.
  • SheetId (string): The unique identifier of the sheet within the workbook.
  • Column (number): The column index where new columns will be inserted before (1-based).
  • ColumnCount (number): The number of columns to insert (default is 1).
  • OperatorId (string): The user ID (unionId) of the operator. Retrieve using Get_User or Search_Users action.

Output:

  • Success (bool): Indicates whether the column insertion operation was successful.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Set Columns Visibility

Show or hide worksheet columns.

Show/hide columns for collaborators; Confirm=true required. Does not trigger DingTalk workflow notifications.

Input Parameters:

  • WorkbookId (string): Smart workbook id (wb...). From Get_Node_List / URL - same as other sheet APIs. Example: "wb123456789012345678"
  • SheetId (string): Worksheet id from Get_Worksheets (each item's id), not the tab title. Example: "sh123456789012345678"
  • Column (number): Starting column index (1-based): 1 = A, 2 = B, 26 = Z. Example: 1
  • ColumnCount (number): How many consecutive columns to show/hide starting at Column; required, must be 1. Example: 3 affects columns A-C when Column=1
  • Visibility (string): Exactly "visible" or "hidden" (lowercase). Use visible to show, hidden to hide.
  • OperatorId (string): UnionId for smart-doc API. Get_User or Search_Users (unionId). Example: "user123456"
  • Confirm (bool): Must be true to change column visibility (write). Example: true

Output:

  • Success (bool): True when StatusCode is 200 and ErrorMessage is empty (HTTP success path).
  • AffectedColumnCount (number): Number of columns in the request (columnCount) when the API returned success; may differ if columns are protected.
  • Visibility (string): The visibility state that was set ('visible' or 'hidden').
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Append Rows

Append rows after existing data in a DingTalk smart worksheet.

Append rows after existing data in a DingTalk smart worksheet (auto rowCount). Warning: WARNING: NOT idempotent - Risk Level: High; retries duplicate rows; duplicates cannot be auto-removed. Don't use without required IDs from read/search actions. Side effects: irreversible writes. Request timeout fixed at 30 seconds.

Input Parameters:

  • WorkbookId (string): Smart workbook ID (wb...). From Get Node List / Get Workspace Node node entries, or from the workbook URL: the path segment starting with wb after /nodes/.../, e.g. https://alidocs.dingtalk.com/i/nodes/xxx/wbxxx123456 -> WorkbookId is wbxxx123456. Example: "wbxxx123456"
  • SheetId (string): Worksheet ID within the workbook - NOT the visible tab name (e.g. "Sheet1"). Call Get Worksheets; use each sheet's id from the SheetList array (field name id, not name). Example: "shxxx789"
  • Values (string): JSON string of a 2D array: each inner array is one row of string cell values. Column width is derived from the widest row. Formatted structure (pass as a single JSON string): [ ["Alice", "30", "alice@example.com"], ["Bob", "25", "bob@example.com"] ] Compact JSON-string example: "[[\"Alice\",\"30\",\"alice@example.com\"],[\"Bob\",\"25\",\"bob@example.com\"]]"
  • OperatorId (string): Operator unionId for smart-doc APIs - NOT org-scoped userid. Best source: Search Users -> SearchResult.list[].unionid (lowercase field). unionId is typically a long alphanumeric string (e.g. abc123def456). The operator must have edit access to the worksheet. Example: "abc123def456"

Options:

  • StartColumn (string): The starting column letter for writing data. Defaults to "A". Supports multi-letter columns like "AA". End column is computed from the widest row in Values. Example: "A" Default: A.

Output:

  • AppendResult (object): Append operation result object containing: a1Notation (string, the actual range address updated), appendedRange (string, calculated range where data was written, e.g. "A6:C7"), appendedRows (integer, number of rows appended).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Delete Rows

Delete rows from a DingTalk smart worksheet.

Delete rows from a DingTalk spreadsheet. WARNING: Permanent; cannot be undone. Set Confirm=true only after verifying Row/RowCount. Requires Confirm=true and non-empty Reason (GI safety, not in API).

Input Parameters:

  • WorkbookId (string): Retrieve using Get_Workspaces action.
  • SheetId (string): Retrieve using Get_Worksheets action.
  • Row (number): First row to delete, counting from 1 (top row of the sheet is 1). Example: 5
  • RowCount (number): The number of rows to delete (default is 1).
  • OperatorId (string): The user ID (userId) of the person performing the delete. Use the same operator the app will act as. Retrieve via Get_User or Search_Users. Example: "user123456"
  • Confirm (bool): Must be true to delete rows. WARNING: permanent; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Success (bool): Indicates whether the row deletion operation was successful.
  • DeletedRowCount (number): The actual number of rows that were deleted.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200 (success), 500 (server error), -1 (parameter error).
  • ErrorMessage (string): Error message if the operation fails, empty otherwise.

Insert Rows Before

Insert empty rows before a specified row index.

Insert rows before the specified row index in a DingTalk spreadsheet. New empty rows are inserted at the specified position; existing rows at and below that position are shifted down.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. 'Sheet1'). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • Row (number): The 1-based row index before which new rows will be inserted. Row 1 = the first row, Row 2 = the second row, etc. Existing rows at and below this position will be shifted down. Example: 3
  • RowCount (number): Number of empty rows to insert before the specified Row position. Must be a positive integer. Example: 5
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • Success (bool): Indicates whether the row insertion operation was successful.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Insert Rows Before with Data

Insert rows and write cell data in one operation.

Insert rows and write cell data. NOT idempotent - retries duplicate rows. Set Confirm=true only when intended.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. "Sheet1"). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • Row (number): The 1-based row index before which new rows will be inserted. For example, Row=3 inserts above the 3rd row; existing rows at and below this position shift down. The number of inserted rows equals the number of rows encoded in Values (JSON 2D array). Example: 3
  • Values (string): JSON string encoding a 2D array: each element is one row (array of string cell values). Row count sets how many rows to insert. Example: "[[\"Alice\",\"30\",\"alice@example.com\"],[\"Bob\",\"25\",\"bob@example.com\"]]"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification and audit logging. The operator must have edit access to the target worksheet. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"
  • Confirm (bool): Must be true to insert rows and write data. NOT idempotent; repeated calls add duplicate rows. Example: true

Options:

  • StartColumn (string): The starting column letter for writing data. Defaults to "A". Supports multi-letter columns like "AA". For example, StartColumn="B" writes data starting from column B. Example: "A" Default: A.

Output:

  • InsertedRows (number): The number of rows that were inserted (equal to the row count encoded in Values). 0 if insertion failed.
  • UpdateResult (object): Data write result object containing: a1Notation (string, the actual range address where data was written, e.g. "A3:C4"). Empty object if write step failed.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API (from the last API call). Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Set Rows Visibility

Show or hide worksheet rows.

Show/hide rows for collaborators; Confirm=true required. Does not trigger DingTalk workflow notifications.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. 'Sheet1'). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • Row (number): The 1-based row index where the visibility change starts. Row 1 = the first row, Row 2 = the second row, etc. Example: 3
  • RowCount (number): Number of consecutive rows to show or hide starting from the Row position. Must be a positive integer. Example: 5
  • Visibility (string): The target visibility state for the specified rows. Must be one of: "visible" (show rows - make hidden rows visible again) or "hidden" (hide rows - rows still exist but are not displayed). Example: "hidden"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"
  • Confirm (bool): Must be true to change row visibility (write). Example: true

Output:

  • Success (bool): True when StatusCode is 200 and ErrorMessage is empty (HTTP success path).
  • AffectedRowCount (number): Number of rows in the request (rowCount) when the API returned success; may differ from server-side enforcement if rows are protected.
  • Visibility (string): The visibility state that was set ('visible' or 'hidden').
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Clear Range Content

Clear cell values and formatting from a worksheet range.

Clear content from a DingTalk Smart Worksheet range. WARNING: Permanent; cannot be undone. Set Confirm=true only after verifying RangeAddress.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. 'Sheet1'). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • RangeAddress (string): The cell range address using Excel-style A1 notation. Supported formats: rectangular range (e.g. "A1:C3"), single cell (e.g. "A1"). Example: "A1:C3"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"
  • Confirm (bool): Must be true to clear the range. WARNING: permanent; cannot be undone via this API. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Options:

  • ClearType (string): DingTalk clear API clearType sent in the request body. Use all to clear cell values and formatting in the range (default). Example: "all" Default: all.

Output:

  • ClearResult (object): Clear operation result object containing: range (string, the actual cleared range address), clearedCells (number, total cells cleared).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Clear Range Data

Clear cell values from a worksheet range while preserving formatting.

Clear range data from DingTalk Smart Worksheet while preserving formatting. WARNING: Cleared cell values may not be recoverable through this API-confirm RangeAddress before calling.

Input Parameters:

  • WorkbookId (string): The ID of the target workbook.
  • SheetId (string): The ID of the target worksheet.
  • RangeAddress (string): The cell range address to clear data from (e.g., 'A1:C3').
  • OperatorId (string): The user ID (unionId) of the operator. Retrieve using Get_User or Search_Users action.

Output:

  • ClearResult (object): Clear operation result. Contains: range (actual cleared range address), clearedCells (number of cells cleared), operation (e.g., clearContents).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code
  • ErrorMessage (string): Error message if any

Get Range Data

Read values and metadata from a worksheet cell range.

Retrieves data from a specified cell range in a DingTalk Smart Worksheet. Returns the values and metadata of the specified range.

Input Parameters:

  • WorkbookId (string): Smart workbook id (typically wb + numeric id). From Get_Node_List / Get_Workspace_Node node payload or alidocs URL path segment. Example: "wb123456789012345678"
  • SheetId (string): Worksheet id (internal id, not the visible tab title). Call Get_Worksheets with WorkbookId; each sheet item includes id - use that as SheetId. Example: "sh123456789012345678"
  • RangeAddress (string): A1-style range on the sheet identified by SheetId (e.g. "A1:C10"). Use same rules as Excel row/column addresses; cross-sheet references like Sheet2!A1 are not used here-pick SheetId for the tab first. Example: "A1:C10"
  • OperatorId (string): Operator unionId for this doc API (global user id). Different from org-scoped userid used in some older OAPIs. Obtain via Get_User or Search_Users. Example: "user123456"

Output:

  • RangeData (object): Object with: values (string[][], rows of cells), range (string), rowCount (number), columnCount (number) when returned by API. All cell values as strings.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Update Range Data

Write values to a worksheet cell range.

Update cell values in a specified range of a DingTalk smart worksheet. Values is a JSON string of a 2D array (rows of string cells), matching RangeAddress.

Input Parameters:

  • WorkbookId (string): The unique ID of the target DingTalk smart workbook. You can obtain it by calling the Get Node List or Get Workspace Node action, or from the workbook URL in DingTalk. Example: "wbxxx123456"
  • SheetId (string): The unique ID of the target worksheet (sheet tab) within the workbook. This is NOT the sheet name (e.g. 'Sheet1'). You can obtain it by calling the Get Worksheets action. Example: "shxxx789"
  • RangeAddress (string): The cell range address to update, using Excel-style A1 notation. The dimensions must match the Values array. Supported formats: rectangular range (e.g. "A1:C3"), single cell (e.g. "A1"). Example: "A1:C3" for a 3-row by 3-column area.
  • Values (string): JSON string encoding a 2D array: each element is one row (array of string cell values). Dimensions must match RangeAddress. Example: "[[\"Name\",\"Age\",\"Email\"],[\"Alice\",\"30\",\"alice@example.com\"],[\"Bob\",\"25\",\"bob@example.com\"]]"
  • OperatorId (string): The DingTalk user ID (unionId) of the operator. Used for permission verification and audit logging. The operator must have edit access to the target worksheet. You can obtain user IDs via the Get User or Search Users action. Example: "user123456"

Output:

  • UpdateResult (object): Update operation result object containing: range (string, actual updated range address e.g. "A1:C3"), updatedCells (number, total cells updated), updatedRows (number, rows updated), updatedColumns (number, columns updated).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error (e.g., invalid shape or empty fields), 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Create Notable Sheet

Create a data sheet in a DingTalk AI Notable base.

Create a data sheet in DingTalk AI Notable (POST /v1.0/notable/bases/{baseId}/sheets). Prerequisites: enterprise internal app with AI Notable write scope; operator UnionId. Execution: optional SheetName and optional Fields JSON array.

Input Parameters:

  • BaseId (string): Notable AI table base ID. From DingTalk Notable / open platform or prior API. Example: "qnYxxxxxxxx"
  • OperatorId (string): UnionId of the operator. Get_User or Search_Users. Example: "abcUnionId123"
  • Confirm (bool): Must be true to create the data sheet (write). Example: true

Options:

  • SheetName (string): Optional display name for the new data sheet. Leave empty to use platform default naming. Example: "Leads"
  • Fields (object-array): Optional array of column definitions. Each item should include name and type, and may include property. Example: [{"name":"Title","type":"text"},{"name":"Status","type":"singleSelect","property":{"choices":[{"name":"Open"}]}}]

Output:

  • SheetId (string): The ID of the created notable data sheet
  • SheetName (string): The name of the created data sheet
  • Created (bool): Whether the data sheet was created successfully
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Delete Notable Sheet

Delete a data sheet from a DingTalk AI Notable base.

Delete one data sheet inside a DingTalk AI Notable base (DELETE /v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName}). WARNING: Permanent. Enterprise internal app + Notable write scope required per DingTalk.

Input Parameters:

  • BaseId (string): Notable AI base id (baseId in path). From node metadata / product docs for AI tables. Example: "base_abc123"
  • SheetIdOrName (string): Target sheet id OR sheet name (per DingTalk delete API). Prefer stable id from listing APIs when available. WARNING: identifies the sheet to delete permanently. Example: "sheet_xyz789" or "Inventory"
  • OperatorId (string): UnionId of the operator (query operatorId). Get User / Search Users. Example: "user123456"
  • Confirm (bool): Must be true to delete. WARNING: Permanent; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Deleted (bool): Whether the Notable data sheet was deleted. true = success; false = failed (see ErrorMessage).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Notable Sheet

Get metadata for one DingTalk AI Notable data sheet.

Get DingTalk AI-table (Notable) sheet metadata by base ID and sheet ID or name. Requires operator UnionId. Don't use for classic Doc workbooks (use Get_Worksheet).

Input Parameters:

  • BaseId (string): AI-table (Notable) base ID. Obtain from your AI-table link or DingTalk admin context.
  • SheetIdOrName (string): Target sheet ID or sheet display name. IDs are stable; names may change. Obtain from list-all-sheets API or product UI.
  • OperatorId (string): Operator UnionId (required as operatorId in Notable APIs). Obtain via Get_User, Search_Users, or SSO flows.

Output:

  • SheetData (object): Upstream Notable sheet object (e.g. id, name; additional fields if returned by API).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Get Notable Sheets

List data sheets in a DingTalk AI Notable base.

Get all data tables from a DingTalk AI Notable base (DingTalk AI Notable). Official DingTalk docs expose no pagination or cursor for this API; SheetList is the upstream value array. Requires AI-table read permission; not the same as smart workbook Get_Worksheets.

Input Parameters:

  • BaseId (string): AI Notable base id. From wiki/node metadata or open-platform data-structure for AI tables; not wb... workbook id. Example: "qnYxxx"
  • OperatorId (string): UnionId for Notable API (operatorId query). Get_User / Search_Users. Example: "user123456"

Output:

  • SheetList (object-array): Data tables: each item has id (sheet id for Notable APIs) and name.
  • SheetCount (number): Count of items returned in SheetList; official API does not return cursor/page metadata.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Update Notable Sheet

Rename or update metadata for a DingTalk AI Notable data sheet.

Prerequisites: DingTalk internal app with AI-table write permission; valid BaseId, SheetIdOrName, Name, operator unionId. Execution: PUT /v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName} with JSON body {name}.

Input Parameters:

  • BaseId (string): The DingTalk AI table (Notable) base identifier (baseId). Obtain from AI table product context or open-platform resources-not the same as smart workbook WorkbookId. Example: "qnYxxx"
  • SheetIdOrName (string): Target data sheet id or current sheet name (path segment; non-ASCII names are URL-encoded automatically). Example: "tblxxx" or a display name like "data table"
  • Name (string): New name for the data sheet after update (required by upstream API). Max 255 characters. Example: "data table2"
  • OperatorId (string): Operator unionId for permission and audit. Obtain via Get User / Search Users. Example: "abc123UnionId"

Output:

  • SheetInfo (object): Upstream sheet object after update: typically id (string, sheet id) and name (string, new name). May be empty if upstream returns no body.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Create Notable Field

Create a field in a DingTalk AI Notable data sheet.

Create a column (field) in a DingTalk AI Notable data sheet (POST /v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName}/fields). Requires Confirm=true. Enterprise internal app + Notable write scope. Related: Get Notable Fields, Update/Delete Notable Field.

Input Parameters:

  • BaseId (string): Notable AI base id (baseId in path). Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target sheet id OR sheet name. Example: "edKxxxx" or "data table"
  • FieldName (string): New column display name (body name). Example: "Status"
  • FieldType (string): Notable field type: text, number, date, singleSelect, etc. See DingTalk field-property docs. Example: "text"
  • OperatorId (string): UnionId of the operator (query operatorId). Get User / Search Users. Example: "user123456"
  • Confirm (bool): Must be true to create the field (write). Example: true

Options:

  • Property (object): Optional field property object for DingTalk Notable field options, such as singleSelect choices. Example: {"choices":[{"name":"A"}]}

Output:

  • FieldId (string): ID of the created Notable field.
  • FieldInfo (object): Field object after create (id, name, type, optional property).
  • Created (bool): Whether the field was created successfully.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Delete Notable Field

Delete a field from a DingTalk AI Notable data sheet.

Delete one column (field) in a DingTalk AI Notable data sheet (DELETE /v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName}/fields/{fieldIdOrName}). WARNING: Permanent. Enterprise internal app + Notable write scope required.

Input Parameters:

  • BaseId (string): Notable AI base id (baseId in path). Example: "base_abc123"
  • SheetIdOrName (string): Target sheet id OR sheet name. Example: "sheet_xyz789" or "Inventory"
  • FieldIdOrName (string): Field id OR field name to delete (from list-fields APIs). WARNING: identifies the column to delete permanently. Example: "fld_abc" or "Title"
  • OperatorId (string): UnionId of the operator (query operatorId). Get User / Search Users. Example: "user123456"
  • Confirm (bool): Must be true to delete. WARNING: Permanent; cannot be undone. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Deleted (bool): Whether the Notable field was deleted. true = success; false = failed (see ErrorMessage).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Get Notable Fields

List fields in a DingTalk AI Notable data sheet.

List all column fields in a DingTalk AI Notable data table (DingTalk AI Notable list fields). Official DingTalk docs expose no pagination or cursor for this API; FieldList is the upstream value array. Requires BaseId, SheetIdOrName, and operator UnionId. Not smart workbook columns.

Input Parameters:

  • BaseId (string): AI Notable base id. From wiki/node metadata or open-platform data-structure for AI tables; not wb... workbook id. Example: "qnYxxx"
  • SheetIdOrName (string): Target sheet ID or sheet display name. Obtain from Get Notable Sheets (SheetList[].id or name). Example: "edKxxxx" or "data table"
  • OperatorId (string): UnionId for Notable API (operatorId query). Get_User / Search_Users. Example: "user123456"

Output:

  • FieldList (object-array): Column definitions: each item has id, name, type, and optional property per DingTalk Notable field docs.
  • FieldCount (number): Count of items returned in FieldList; official API does not return cursor/page metadata.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Update Notable Field

Update a field in a DingTalk AI Notable data sheet.

Prerequisites: DingTalk internal app with AI-table write permission; valid BaseId, SheetIdOrName, FieldIdOrName, Name, operator unionId. Execution: PUT /v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName}/fields/{fieldIdOrName} with JSON body {name, property?}.

Input Parameters:

  • BaseId (string): The DingTalk AI table (Notable) base identifier (baseId). Example: "qnYxxx"
  • SheetIdOrName (string): Data table id or display name (path segment; URL-encoded). Example: "tblxxx" or "data table"
  • FieldIdOrName (string): Field id or current field name (path segment). Example: "fldxxx" or "Title"
  • Name (string): New field name after update (required by upstream API). Example: "Status"
  • OperatorId (string): Operator unionId for permission and audit. Obtain via Get User / Search Users. Example: "abc123UnionId"

Options:

  • Property (object): Optional field property map per DingTalk field-properties doc; omit or empty object to skip property in request body.

Output:

  • FieldInfo (object): Field object after update: typically id (string) and name (string). May include upstream response fields.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error (network timeout, may retry).
  • ErrorMessage (string): Error message if any. Empty string on success.

Delete Notable Records

Delete records from a DingTalk AI Notable data sheet.

Delete multiple rows from a DingTalk AI Notable data table by record id list. Requires Confirm=true and non-empty Reason. Enterprise internal app + Notable write scope. Not smart workbook Delete Rows.

Input Parameters:

  • BaseId (string): Notable AI table base ID (same as Get Notable Sheets). Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target data table id from SheetList[].id, or the sheet display name. Example: "edKxxxx"
  • OperatorId (string): UnionId of the operator (query operatorId). Get_User / Search_Users.
  • RecordIds (string-array): Array of Notable record id strings to delete. Example: ["recxxxx","recyyyy"]
  • Confirm (bool): Must be true to delete records (write). WARNING: Permanent. Example: true
  • Reason (string): Non-empty audit string explaining why this destructive operation was approved. Recorded for compliance; not sent to the DingTalk API. Example: "User approved deletion in workflow step 3."

Output:

  • Deleted (bool): Whether the delete request succeeded (upstream success=true or empty 2xx).
  • DeletedCount (number): Number of record ids submitted in RecordIds.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Get Notable Record

Get one record from a DingTalk AI Notable data sheet.

Get one row from a DingTalk AI Notable data table by record id. Read-only. Not for smart workbook cell ranges (use Get Range Data).

Input Parameters:

  • BaseId (string): Notable AI table base ID (same as Get Notable Sheets). Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target data table id from SheetList[].id, or the sheet display name. URL-encoded in path. Example: "edKxxxx"
  • RecordId (string): Notable row record id returned by insert/list APIs (path segment). Example: "recxxxxxxxx"
  • OperatorId (string): UnionId of the operator (query operatorId). Get_User / Search_Users.

Output:

  • Record (object): Single Notable record object (typically id, fields, etc. per upstream).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Insert Notable Records

Insert records into a DingTalk AI Notable data sheet.

Insert rows into a DingTalk AI Notable data table (DingTalk AI Notable insert records). Requires Confirm=true and Notable write permission. Not smart workbook Append Rows.

Input Parameters:

  • BaseId (string): Notable AI table base ID (same as Get Notable Sheets). Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target data table id from SheetList[].id, or the sheet display name (e.g. Chinese name). Path-segment is URL-encoded. Example: "edKxxxx" or "data table"
  • OperatorId (string): UnionId of the operator (query operatorId). Get_User / Search_Users.
  • Records (object-array): Array of rows to insert. Each row is either {"fields":{"ColumnName":value,...}} or shorthand {"ColumnName":value,...}. Multiple rows allowed. Example: [{"fields":{"Title":"hello"}}] or [{"Title":"hello"}]
  • Confirm (bool): Must be true to insert records (write). Example: true

Options:

  • ClientToken (string): Optional clientToken query (UUID string) for idempotent retries per DingTalk docs; leave empty if unused.

Output:

  • RecordList (object-array): Inserted rows: each item has id (new record id from API value[]).
  • RecordCount (number): Number of returned record ids (equals inserted row count on full success).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

List Notable Records

List records from a DingTalk AI Notable data sheet with pagination and filters.

List Notable rows with pagination and optional filter (POST .../records/list). Read-only. Use Get Notable Record for one row by id.

Input Parameters:

  • BaseId (string): Notable AI table base ID (same as Get Notable Sheets). Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target data table id from SheetList[].id, or display name. URL-encoded in path. Example: "edKxxxx"
  • OperatorId (string): UnionId of the operator (query operatorId). Get_User / Search_Users.

Options:

  • MaxResults (number): Page size per request, 1-100. Default 100. Example: 100 Default: 100.
  • NextToken (string): Cursor from prior response NextToken; leave empty on first page.
  • Filter (object): Optional filter object: combination (and\|or) and conditions per DingTalk list-records API. Example: {"combination":"and","conditions":[{"fieldIdOrName":"Status","operator":"eq","value":["Open"]}]}
  • FieldIdOrNames (string-array): Optional array of field ids or names to return (max 100). Example: ["Title","Status"]

Output:

  • RecordList (object-array): Notable rows for this page (id, fields, etc.).
  • RecordCount (number): Number of items in RecordList.
  • HasMore (bool): True when upstream hasMore indicates another page.
  • NextToken (string): Cursor for the next page; pass as NextToken input.
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

Update Notable Records

Update existing records in a DingTalk AI Notable data sheet.

Update existing rows in a DingTalk AI Notable data table (DingTalk AI Notable update records). Requires Confirm=true, record id per row, and Notable write permission.

Input Parameters:

  • BaseId (string): Notable AI table BaseId. Obtain it from the DingTalk Notable URL/context or workspace node metadata, then use Get Notable Sheets to confirm the available sheets. This is not a smart workbook id. Example: "qnYxxxxxxxx"
  • SheetIdOrName (string): Target data table id or exact display name. Prefer the stable id from Get Notable Sheets -> SheetList[].id; display names must match exactly. The path segment is URL-encoded. Example: "edKxxxx" or "Sales Pipeline"
  • OperatorId (string): UnionId of the operator (query operatorId). Get_User / Search_Users.
  • Records (object-array): Array of rows to update. Each row must include id (Notable record id) and fields to patch. Accepted shapes: - Full: {"id":"recxxx","fields":{"ColumnName":value,...}} - Shorthand: {"id":"recxxx","ColumnName":value,...} Field value examples: - Text: "Launch plan" - Number: 3 or 50000.0 - Date/time: ISO 8601 string, e.g. "2024-06-30T23:59:59+08:00" - Single select: option label string, e.g. "Open" - Multi select: string array, e.g. ["Marketing","Q2"] - Person: UnionId string, e.g. "union_abc123" Use field names/API names exactly as shown in the Notable sheet/field metadata. For large updates, split into smaller batches (100 rows or fewer when unsure). Example: [{"id":"rec_001","fields":{"Title":"Launch plan","Status":"Open","Priority":3,"DueDate":"2024-06-30T23:59:59+08:00"}}]
  • Confirm (bool): Must be true to update records (write). Example: true

Options:

  • ClientToken (string): Optional clientToken query (UUID string) for idempotent retries per DingTalk docs; leave empty if unused.

Output:

  • RecordList (object-array): Updated rows returned from upstream API value[]. Each item includes id and may include fields with updated values, unchanged values, calculated fields, and system metadata such as created/modified time or creator/modifier when DingTalk returns them. Treat the shape as the upstream Notable record object, not only an id list.
  • RecordCount (number): Number of returned record ids (equals updated row count on full success).
  • Summary (string): One-sentence outcome for the agent (success path); empty when failed.
  • Hint (string): Actionable next step when failed; empty on success.
  • Retryable (bool): Whether retrying the same request may succeed.
  • OriginalStatusCode (number): Original HTTP status code returned by the upstream API. Default 0 = request did not reach upstream (e.g., timeout). Use for debugging.
  • StatusCode (number): HTTP/status code.
  • ErrorMessage (string): Error message if any.

5. Example Usage

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

Workflow Overview

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

Step-by-Step Guide

  1. Add Tool Node:
    • In the workflow canvas, click the "+" button to add a new node.
    • Select the "Tools" tab in the pop-up panel.
    • Find and select Dingtalk in the tools list.
    • In the Dingtalk supported operations list, click to select Send Work Notice, which will add a corresponding node to the canvas.
  2. Configure Node:
    • Click the newly added Send Work Notice node, and the configuration panel for this node will expand on the right side.
    • Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select your configured Dingtalk credentials.
    • Parameter Filling: 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 users who will receive the message. Can be one or more, separated by commas. For example: manager001,user002.
    • MsgType: Enter the message type. For plain text messages, enter text.
    • Content: Enter the message content you want to send. For example: This is a test message from the GoInsight automated workflow.
  3. Run and Verify:
    • When all required parameters are filled in correctly, the error message in the upper right corner of the workflow canvas will disappear.
    • Click the "Test Run" button in the upper right corner of the canvas to execute the workflow.
    • After successful execution, you can click the log icon in the upper right corner to view the detailed input and output of the node and verify whether the operation was successful. Meanwhile, the specified users should receive your sent message in Dingtalk.

Final Workflow Display

After completing the above steps, your entire workflow is configured. Click "Test Run", and a work notification will be successfully sent to the Dingtalk client of the specified users.

6. FAQs

Q: Why did my message fail to send?

A: Please check the following:

  • Credentials and AgentId: Ensure that the AgentId you entered in the node matches the selected credentials (AppKey/AppSecret).
  • Is UserID correct: 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 whether your application has the "send work notification" interface 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: Check the ErrorMessage field in the node output, which usually provides the specific reason for failure.

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

A: You can obtain it in the following ways:

  • Use GoInsight Node: In your workflow, you can use the Get User or Search Users operation to query user details, which includes the UserID.
  • Dingtalk Management Backend: Log in to your enterprise's Dingtalk management backend, find the corresponding employee in the "Directory", and view their personal profile to find the UserID.

Q: I received a permission error (such as 401/403), what should I do?

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

  • Credentials Validity: Confirm that the AppKey and AppSecret configured in GoInsight are correct and not expired.
  • Interface Permission Scope: On the Dingtalk Open Platform, check whether your application has applied for and been approved for the API interface permissions you want to call. For example, to create users, you need permissions related to "directory management".
  • IP Whitelist: This is one of the most common reasons. Please ensure that the IP address of the GoInsight platform server is correctly configured in your Dingtalk application's IP whitelist.

7. Official Documentation

For a deeper understanding of the details and advanced features of the Dingtalk API, please refer to the official documentation:

Dingtalk Official API Documentation

Updated on: Jul 3, 2026
Was This Page Helpful?
Prev ConvertKit
Next Discord
Discussion

Leave a Reply.

Your email address will not be published. Required fields are marked*

Product-related questions?Contact Our Support Team to Get a Quick Solution>
On this page
loading...
No Results