Administration & GovernanceIntegrations

DingTalk Bot

View as Markdown

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

ScenarioGuidance
Team knowledge Q&APublish the bot only to approved DingTalk organizations or members, and bind it to the Agent or document set that team can access.
Internal supportUse a dedicated DingTalk internal app so credential rotation, logs, and permission reviews are easier.
Project-group assistantLimit knowledge and tool scope to the project group, then remove access or take the bot offline after the project ends.
Sensitive knowledge Q&AValidate user, group, and document-set permissions first. Do not use the bot as a shared permission bypass.

Management Boundary

AreaGuidance
EntryUse an approved DingTalk internal app, bot capability, and event subscription.
IdentityBind the bot to a clear AIvis workspace and owner. Do not treat it as an admin proxy.
ResponsesReturn only knowledge and tool results available to the current user, group, or bound Agent.
PermissionsEnable only the message permissions required by the bot. Add broader conversation permissions only when needed.
OperationsTrack 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 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

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

AIvis bot configuration page selecting Stream mode and saving DingTalk credentials

DingTalk Developer PlatformAIvis configuration fieldNotes
Client IDClient IDIdentifies the DingTalk internal app.
Client SecretClient SecretUsed for app authentication and the Stream connection.
Message receive mode StreamConnection mode StreamThe 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

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

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

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

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

DingTalk bot message test succeeds

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

SymptomPriority checks
AIvis cannot establish the DingTalk connectionConfirm 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 logsConfirm 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 chatsConfirm the bot is available to the target scope and the trigger path matches the DingTalk permissions and bot capability.
App changes do not take effectConfirm a new version was created and published in version management.
Authorization errors or empty resourcesConfirm the target knowledge base, Agent, group, or resource has been granted to the bot and current user.
HTTP callback mode is unstableDingTalk 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.