DingTalk | Alephant Documentation

The DingTalk connector brings approved DingTalk Wiki nodes, individual DingTalk documents, and DingDrive folders into AIvis retrieval. It reads only the scopes explicitly entered by an administrator and does not scan every DingTalk object visible to the app or operator account.

Use cases

Scenario	Recommendation
Team Wiki Q&A	Use `workspace_id/parent_node_id` for the smallest approved Wiki subtree.
Single policy or project document	Use the document `dentry_uuid` instead of granting a whole Wiki tree.
DingDrive material	Use `space_id/parent_id` for one approved folder, then validate file type and size.
Multi-department knowledge	Split connectors by department or business audience.
Sensitive content	Use a dedicated DingTalk app and operator UnionId instead of a broad shared app.

What it indexes

DingTalk data	Scope format	Indexing behavior
Wiki subtree	`workspace_id/parent_node_id`	Reads the selected Wiki node hierarchy and native document content.
Single document	`dentry_uuid`	Parses the document body as an independent page.
DingDrive folder	`space_id/parent_id`	Reads supported files under the selected folder and keeps folder hierarchy.

The connector supports at most 100 total scopes and rejects duplicate or overlapping scopes. It does not index DingTalk chats, tasks, approvals, calendars, contacts, or resources that were not explicitly listed.

Prerequisites

Create an internal DingTalk app and prepare its AppKey and AppSecret.
Identify an operator UnionId that can read the approved resources. Do not enter a userId, phone number, email, or display name.
Grant the app the required read-only API permissions and resource authorization.
Collect the exact Wiki, document, or DingDrive scope IDs to index.
Decide the AIvis access group before indexing private content.
Allow the AIvis backend to reach api.dingtalk.com and authorized DingDrive downloads.

DingTalk API permissions, resource authorization, and app availability are separate checks. A valid credential does not prove that every target Wiki, document, or folder has been authorized to the app.

Where to get configuration values

Configuration value	Where to get it
`AppKey` / `AppSecret`	Open the internal app in the DingTalk developer console and check the app’s basic information or credential page. See DingTalk developer tutorial: create an app and view Client ID / Client Secret.
Access token and credential validation	DingTalk exchanges app credentials for an Access Token. See DingTalk developer guide: get an app Access Token.
Operator `UnionId`	Get it from an authorized operator identity API, enterprise address-book tooling, or your internal identity mapping. Confirm it is not a `userId`, phone number, or email.
Wiki, document, and DingDrive scope IDs	Confirm them from the resource URL, resource admin page, or related Open API response. If the field source is unclear, search the DingTalk Open Platform docs for `workspace_id`, `dentry_uuid`, `space_id`, or `parent_id`.
API permission and resource authorization	Enable the required read-only API permissions in the DingTalk Open Platform, then authorize the target Wiki, document, or DingDrive folder to the app.

Prepare the DingTalk app

In the DingTalk developer console, open App Development > DingTalk Apps, then select Create App to create an internal enterprise app.

DingTalk developer console app list with the Create App entry highlighted

Open the app and copy Client ID (formerly AppKey) and Client Secret (formerly AppSecret) from Credentials and Basic Info. In AIvis, these values are still entered as DingTalk AppKey and DingTalk AppSecret.

DingTalk app credentials page showing Client ID and Client Secret

In Permission Management, enable the read permissions required by the resources this connector will index. Grant DingDrive, document, or Wiki permissions only for the actual indexing scope.

DingTalk permission management page showing enabled DingDrive permissions

If you need to identify the operator, use DingTalk API Explorer to debug requestAuthCode and get an authorization code for the current signed-in user.

DingTalk JSAPI Explorer requestAuthCode page showing the authCode debugging entry

Follow the DingTalk Open Platform “Get user token” guide to exchange the authorization code for a user access token.

DingTalk Open Platform Get User Token documentation page

Confirm unionId in the user information response. Enter this value as Operator UnionId in AIvis, not a userId, phone number, email, or display name.

DingTalk user information response parameters with unionId highlighted

Return to AIvis and create the DingTalk credential with a name, DingTalk AppKey, DingTalk AppSecret, and Operator UnionId.

AIvis Create DingTalk Credential dialog with name, AppKey, AppSecret, and Operator UnionId fields

Configure in AIvis

In the Admin panel, open Connectors, select DingTalk, create or choose a DingTalk credential, and then enter the explicit scopes to index.

Field	How to fill it	Notes
AppKey	Internal app AppKey	Used to request DingTalk access tokens.
AppSecret	AppSecret from the same app	Stored as a protected secret.
Operator UnionId	For example `unionid_xxx`	Represents the user used for resource reads.
DingTalk Wiki root scopes	One `workspace_id/parent_node_id` per line	Indexes explicit Wiki subtrees.
DingTalk document IDs	One `dentry_uuid` per line	Indexes explicit documents.
DingDrive folder scopes	One `space_id/parent_id` per line	Indexes explicit folders.

Enter at least one scope type. Start with a minimal test scope, validate search results, then expand.

Sync behavior

The standard Admin-created DingTalk connector runs as a polling connector with checkpoint resume. It processes scopes in order, builds a stable inventory for each scope, and emits hierarchy nodes and documents from that inventory.

Stage	Behavior
Wiki	Reads the selected root’s node tree and exports native document content.
Single document	Parses the target `dentry_uuid` directly.
DingDrive files	Emits supported files from the selected folder; unsupported files are recorded as item failures.
Incremental window	Items outside the sync time window are skipped. Configuration changes invalidate the previous checkpoint fingerprint.

Permissions

The DingTalk app and operator UnionId determine what AIvis can ingest, but this connector does not synchronize DingTalk departments, groups, document members, or DingDrive ACLs into AIvis.

AIvis access setting	Meaning
Private groups	Only selected AIvis groups can search documents produced by this connector. Recommended for internal Wiki and project material.
Public	Every eligible AIvis user can search indexed content. Use only for content that can be shared with that audience.
Auto permission sync	DingTalk is not supported for this mode.

Use AIvis Private groups for internal or project content. Use Public only when every eligible AIvis user may search every indexed result. DingTalk is not available as an auto permission-sync source.

Verify

Create a connector with one test Wiki node, document, or DingDrive folder.
Run indexing and confirm token acquisition and scope validation pass.
Search known titles, body text, and file names.
Search resources outside the configured scopes and confirm they are absent.
Test both an assigned AIvis group member and an outside user.
Modify a test document and confirm the next sync updates the result.

Troubleshooting

Symptom	What to check
Credential validation fails	AppKey and AppSecret must belong to the same enabled DingTalk app.
Scope validation fails	Check ID format, resource authorization, and whether the operator UnionId can read the resource.
API permission exists but resource is unreadable	Verify resource-level authorization and operator access.
Only part of the content is synced	Check omitted, duplicate, overlapping, or over-limit scopes.
DingDrive files are missing	Check supported file type, size, and backend download reachability.
Users can search content they should not see	Restrict AIvis access groups or split the connector by audience.

Security and maintenance

Use separate DingTalk apps and secrets for production, test, and demo environments.
Store real secrets only in protected AIvis credential fields.
Review scopes, operator UnionId, app permissions, resource authorization, and AIvis access groups regularly.
Rotate credentials or replace the operator if ownership changes or a secret may have leaked.
Disable the connector before removing DingTalk permissions for retired scopes.