> 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 Bot

> Configure a DingTalk bot with Stream mode while controlling app credentials, bot capability, event subscription, release, and test boundaries.

The DingTalk bot lets users call AIvis from DingTalk conversations. Prefer `Stream` mode: save the DingTalk `Client ID` and `Client Secret` in the AIvis bot configuration page, add the bot capability and event subscription in DingTalk, and receive messages through the long-lived stream connection.

Treat it as a governed entry point before rollout. It should only respond to approved sources, only use knowledge and tools available to the current user, group, or bound Agent, and keep each response traceable.

## Use Cases

| Scenario                 | Guidance                                                                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Team knowledge Q\&A      | Publish the bot only to approved DingTalk organizations or members, and bind it to the Agent or document set that team can access. |
| Internal support         | Use a dedicated DingTalk internal app so credential rotation, logs, and permission reviews are easier.                             |
| Project-group assistant  | Limit knowledge and tool scope to the project group, then remove access or take the bot offline after the project ends.            |
| Sensitive knowledge Q\&A | Validate user, group, and document-set permissions first. Do not use the bot as a shared permission bypass.                        |

## Management Boundary

| Area        | Guidance                                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| Entry       | Use an approved DingTalk internal app, bot capability, and event subscription.                                  |
| Identity    | Bind the bot to a clear AIvis workspace and owner. Do not treat it as an admin proxy.                           |
| Responses   | Return only knowledge and tool results available to the current user, group, or bound Agent.                    |
| Permissions | Enable only the message permissions required by the bot. Add broader conversation permissions only when needed. |
| Operations  | Track Client ID, release time, connection mode, availability scope, secret rotation, and owner.                 |

## Before Configuration

Before configuration, confirm:

1. You can access the [DingTalk Developer Platform](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app) and create internal apps or publish app versions.
2. The AIvis DingTalk bot configuration page is open and ready for `Client ID`, `Client Secret`, and connection mode.
3. The groups, departments, members, workspace, default Agent, and knowledge scope the bot may serve are defined.
4. You plan to use `Stream` mode. DingTalk HTTP callbacks are sensitive to response latency and usually need a response in about 1.5 seconds, so `Stream` is the safer default.

> `Client Secret` is sensitive. Store it only in protected configuration. Do not put real secrets in public docs, Agent instructions, screenshots, tickets, or chat messages.

## Create the DingTalk App

Open the DingTalk Developer Platform, go to the internal app list, click create app, and fill in the app name, description, icon, and other basic information. Keep the app name aligned with the AIvis bot display name so administrators and members can identify it.

![DingTalk Developer Platform creating an internal app](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/99ce2f16ae9d4fd41013ac64b20ff5be49cd95f2184356a5eb1aa2a3bc27264e/assets/aivis/dingtalk-bot/dingtalk-create-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=e8ee1cecdb3e57617ca18a20307d04eb65b75a553cb2ffaa704bf796a0a73812&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

After creation, open the app detail page and confirm it belongs to the expected organization before continuing with credentials, bot capability, and release.

## Configure App Credentials

Copy `Client ID` and `Client Secret` from the DingTalk app detail page. Return to the AIvis bot configuration page, fill them into client ID and client secret, and confirm the connection mode is `Stream`.

![DingTalk app detail page showing Client ID and Client Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/d3e62adf9ed0d5243f2ff7c1af4d3dd9205954241e4e6c11714ea3fd19369307/assets/aivis/dingtalk-bot/dingtalk-client-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=88e31d943d8dd378f57555b5a9a7b04096f222963052fb405d097fba0946ea19&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![AIvis bot configuration page selecting Stream mode and saving DingTalk credentials](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2a7df6b77cfe05ed494bedcd1a3ab513d9b95dcc92862f652f6dcdbfc651d10a/assets/aivis/dingtalk-bot/aivis-dingtalk-stream-config.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=f8c82079a9f0d5c9417881e238367cee6adf82e0d46a850e9c67173ff99ea374&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| DingTalk Developer Platform   | AIvis configuration field | Notes                                                  |
| ----------------------------- | ------------------------- | ------------------------------------------------------ |
| `Client ID`                   | Client ID                 | Identifies the DingTalk internal app.                  |
| `Client Secret`               | Client Secret             | Used for app authentication and the Stream connection. |
| Message receive mode `Stream` | Connection mode `Stream`  | The DingTalk and AIvis settings must match.            |

Configuration notes:

* `Client ID` and `Client Secret` must come from the same DingTalk app.
* Do not put an enterprise ID, bot name, user ID, or phone number into the Client ID field.
* If `Client Secret` is regenerated, update the AIvis configuration as well.
* If the AIvis page says the value is already saved and you are not changing the secret, the secret field can remain empty.

## Add the Bot Capability

In the DingTalk Developer Platform, click add app capability and add the bot capability.

![DingTalk Developer Platform adding the bot capability to the app](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/064b9fb62fd56eb32ab12cbe4fd7d42a7f55ab588d402f32364759ba9ffaaf65/assets/aivis/dingtalk-bot/dingtalk-add-bot-capability.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=214d4c76d10faf062b34a27e340620c52208f1fee2642aea9e64e1da690e4582&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Open the bot configuration page, set the message receive mode to `Stream`, then save and publish the bot configuration.

![DingTalk bot configuration page setting message receive mode to Stream](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/fc83725e6f2032606e540f8e723b15f333fa0573093f9a8065b734b51dc4136a/assets/aivis/dingtalk-bot/dingtalk-bot-stream-mode.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=aa2241c8c48c6f9baf7d4ee0af2207f1762a204c05e0c32bd148be49240038f7&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

If DingTalk indicates the bot configuration has not been published, DingTalk may not deliver messages even when the AIvis credentials are saved.

## Configure Event Subscription

When adding an event subscription, use `Stream` mode and keep it consistent with the AIvis connection mode. After completing the setup, click the connection-complete action, validate the connection channel, and save after validation passes.

![DingTalk Developer Platform configuring event subscription and validating the Stream channel](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b9477407e6e5e8860420911bfa389807069f31e7d1b997d24c0ddd3e616cdd9e/assets/aivis/dingtalk-bot/dingtalk-event-subscription-stream.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=52085743c150acb3339b38537fd7e032fffece8d3ae8733254779c96847e063b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Event subscription and app release are separate checks. If the event subscription is saved but the version is not released, or the version is released but Stream validation fails, the bot may not receive messages.

## Create and Release a Version

Open version management, submit the latest version, and publish it. After release, confirm:

* The version status is normal or published.
* The bot capability is included in the released version.
* The availability scope is expected, such as selected members, departments, or the target organization.
* There are no unpublished changes left.

![DingTalk Developer Platform publishing the app version](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/cb62d15bde5f0ea715a6dd8abe7569a275347696eaea0eb0df46edd7ede4120e/assets/aivis/dingtalk-bot/dingtalk-release-version.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=f308d947a19cdcc4f94265fc37fa486fea07d10d2bcd9b2eb27542ed78009acb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Test the DingTalk Bot

Before testing, confirm in AIvis:

1. The bot is enabled.
2. The connection mode is `Stream`.
3. `Client ID` and `Client Secret` are saved.
4. The bound Agent, knowledge scope, and tool scope match the test scenario.
5. DingTalk bot capability, event subscription, and app version are saved and released.

Then search for the bot in DingTalk, open the conversation, and send a test message. When configuration is correct, the bot should receive the message and reply. Actual latency depends on network, model calls, and backend processing.

![DingTalk client searching for the newly created bot](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2213516ba8ea0e74a820788a942c3d942863ee7d50a7309ed71baa808bb142eb/assets/aivis/dingtalk-bot/dingtalk-search-bot.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=ad3331d40730bc247102d697edba1ba4b01330c44ac27fc3a76481c9b209bcd3&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![DingTalk bot message test succeeds](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/e3c36ce52722a32f77941de8f7d6f20fced9fa3550b5bc4eb704c6e90827c045/assets/aivis/dingtalk-bot/dingtalk-bot-test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T120120Z&X-Amz-Expires=604800&X-Amz-Signature=e30b3eb9f02bf45e7bcfc9542a740aedfc20c9cbc7dee7c4c23cd00158c75114&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Validate Access Boundaries

After the basic reply test, validate governance boundaries:

1. Send an allowed question as an authorized member and confirm the bot returns the expected answer.
2. Test an unauthorized member, unauthorized group, or a question requiring an inaccessible document set, and confirm sensitive data is not returned.
3. Confirm tracing or request logs include source platform, user context, bound Agent, response result, and errors.
4. After changing `Client Secret`, connection mode, event subscription, bot capability, or availability scope, release a new DingTalk version and test again.

## Troubleshooting

| Symptom                                          | Priority checks                                                                                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AIvis cannot establish the DingTalk connection   | Confirm `Client ID` and `Client Secret` come from the same app, connection mode is `Stream`, and the secret has not been regenerated without updating AIvis. |
| DingTalk can send messages but AIvis has no logs | Confirm the bot capability is added, event subscription is saved, Stream channel validation passed, and the latest version is released.                      |
| No reply in direct or group chats                | Confirm the bot is available to the target scope and the trigger path matches the DingTalk permissions and bot capability.                                   |
| App changes do not take effect                   | Confirm a new version was created and published in version management.                                                                                       |
| Authorization errors or empty resources          | Confirm the target knowledge base, Agent, group, or resource has been granted to the bot and current user.                                                   |
| HTTP callback mode is unstable                   | DingTalk HTTP callbacks are latency-sensitive. Prefer `Stream` unless there is a specific reason to use HTTP callbacks.                                      |

## Security and Maintenance

* Store real secrets only in the AIvis configuration page. Do not write them into docs, screenshots, tickets, chat records, or repositories.
* If a secret may have leaked, regenerate it in DingTalk and update AIvis immediately.
* Request permissions with the smallest usable scope. Do not enable contacts, approval, or management permissions for a message-only bot.
* When the bot is no longer needed, disable it in AIvis first, then remove permissions or take the DingTalk app version offline.
* In production, record every DingTalk app release time, releaser, change summary, and validation result.

## Related Pages

* [Agents](/aivis/agents/agents) explains how to configure Agents the bot can call.
* [Users, Groups & Roles](/aivis/governance/users-and-groups) explains how access boundaries apply to members and groups.
* [Tracing](/aivis/governance/tracing) explains how to audit bot requests.
* [DingTalk Knowledge Connector](/aivis/knowledge/connectors/dingtalk) explains how to index DingTalk knowledge.