> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # DingTalk > Configure the DingTalk knowledge connector and limit indexing to explicitly approved wiki, document, and drive scopes. 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](https://open-dingtalk.github.io/developerpedia/docs/explore/tutorials/stream/event/go/create-app/). | | Access token and credential validation | DingTalk exchanges app credentials for an Access Token. See [DingTalk developer guide: get an app Access Token](https://open-dingtalk.github.io/developerpedia/docs/develop/permission/single_to_multi/new_get_app_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](https://open.dingtalk.com/document/) 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. | ## 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 1. Create a connector with one test Wiki node, document, or DingDrive folder. 2. Run indexing and confirm token acquisition and scope validation pass. 3. Search known titles, body text, and file names. 4. Search resources outside the configured scopes and confirm they are absent. 5. Test both an assigned AIvis group member and an outside user. 6. 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. ## Official references * [DingTalk developer tutorial: create an app and view Client ID / Client Secret](https://open-dingtalk.github.io/developerpedia/docs/explore/tutorials/stream/event/go/create-app/) * [DingTalk developer guide: get an app Access Token](https://open-dingtalk.github.io/developerpedia/docs/develop/permission/single_to_multi/new_get_app_token/) ## Related pages * [Connectors & Indexing](/aivis/knowledge/connectors) * [Index Settings](/aivis/knowledge/index-settings) * [Users, Groups & Roles](/aivis/governance/users-and-groups)