Data Agent supports integration with DingTalk bots. After configuration, you can interact with a Data Agent instance through DingTalk group chats or direct messages.
Overview
Data Agent is an AI assistant built into the DataWorks platform. It provides built-in skills for data integration, data development, data governance, and data security. You can use natural language to create data synchronization tasks, generate and debug SQL statements, troubleshoot data quality issues, and query data lineage. The IM channel feature allows you to connect a Data Agent instance to instant messaging tools such as DingTalk, Lark, and WeCom as a bot. After the connection is established, team members can invoke all capabilities of Data Agent by mentioning the bot in their daily communication tool, without having to log on to the DataWorks console.
Prerequisites
A Data Agent instance is created and is in the Running state.
A resource group is bound to the Data Agent instance. This is a prerequisite for testing network connectivity.
You have developer permissions on the DingTalk Open Platform. To obtain developer permissions, contact your organization administrator. For more information, see Obtain developer permissions.
Step 1: Create a DingTalk application
Log on to the DingTalk Open Platform to create an application and obtain credentials for connecting Data Agent to DingTalk.
Select or create an organization
Go to the DingTalk Open Platform and select an organization for which you have developer permissions.
If no organization is available, scan the following QR code on the DingTalk mobile app to create an organization. The DingTalk mobile app version must be 6.5.45 or later.
Create an application and configure a bot
In the developer console, click Create App. Enter the App Name and App Description, upload an application icon, and then save.
On the application details page, click Add App Capability in the left-side navigation pane. Select Bot.
On the bot details page, configure the bot information, including the name, icon, profile, and description. Set the Message Receiving Mode to Stream Mode. Click Publish after you complete the configuration.
Click Permission Management in the left-side navigation pane. Make sure that the application has at least the following permissions:
Permission
Description
snsapi_base
Basic permission required to call the SNS API.
qyapi_base
Basic permission required to call the enterprise API.
qyapi_robot_sendmsg
Permission for bots within the organization to send messages.
Card.Instance.Write
Write permission for interactive card instances.
Card.Streaming.Write
Streaming update permission for AI cards.
Click Event Subscription in the left-side navigation pane. Set the Push Mode in subscription management to Stream Mode.
Make sure that no IP allowlist is configured in the Security Settings of the application. An IP allowlist may cause message delivery to be blocked, preventing the bot from responding.
Click Version Management and Release in the left-side navigation pane. Create a version and publish the application.
After the application is published, click Credentials and Basic Information in the left-side navigation pane. Copy and save the Client ID (AppKey) and Client Secret (AppSecret).
In addition to manual configuration, the DingTalk Open Platform provides a one-click application initialization service. Go to the DingTalk Open Platform. In the developer console, find the banner that says Automatically create an AI Assistant Service bot application with one click and start your intelligent collaboration journey and click the button to create a bot.
Step 2: Test network connectivity
Before you configure the DingTalk IM channel, make sure that the network connection between the Data Agent instance and DingTalk is established.
Log on to the DataWorks console. In the left-side navigation pane, click Data Agent. Open the target instance.
In the left-side navigation pane, click IM Channels.
The IM Channels page displays channel cards for DingTalk, Lark, and WeCom. Each card shows the current configuration status, network status, and enablement status.
On the DingTalk channel card, click Test Network Connectivity to verify the network connection between Data Agent and DingTalk.
If the channel card shows Connected, the network is ready. Proceed to the next step to configure the IM channel.
If the channel card shows Unreachable, proceed to enable the channel network.
(Required only if the connectivity test fails) Click Enable Channel Network.
Data Agent provides a Minimal Setup (recommended) option: only the unreachable channel domains are configured with PrivateZone and PrivateLink, minimizing the impact scope.
NoteMinimal Setup is a VPC-level network change. After the setup is complete, other instances in the same VPC can also access the corresponding channel domains. Before you proceed, make sure that all instances in the VPC can share this network access scope.
In the vSwitch Zone drop-down list, select a vSwitch for each availability zone. Click Connect with One Click. The system automatically configures PrivateZone DNS resolution and PrivateLink. The setup takes approximately 1 to 5 minutes.
To have more granular control over the network configuration, click Manage Network to go to the resource group network configuration page. Click Retest to retest the connectivity of each channel at any time.
After the setup is complete, the system automatically retests the connectivity. After you confirm that the channel card shows Connected, proceed to configure the IM channel.
Step 3: Configure the DingTalk IM channel
After the network connection is established, configure the DingTalk application credentials to connect Data Agent to DingTalk.
On the DingTalk channel card, click Configure. In the IM channel configuration dialog box, configure the following parameters:
Parameter
Description
AppKey
The AppKey of the DingTalk application obtained in Step 1.
AppSecret
The AppSecret of the DingTalk application obtained in Step 1.
Click Advanced Settings to expand additional settings. Configure the following parameters as needed:
Category
Parameter
Description
Session Management
Session Isolation
Specifies whether conversation contexts are isolated between different users or group chats. Valid values:
By User: Each user has an independent conversation context.
By Group/Topic: Messages in the same group chat or topic share one conversation. This is suitable for group collaboration scenarios.
Shared: All users share the same conversation context.
Permission Management
User Access
Specifies which users can interact with the bot. Valid values:
All Members: All members in the organization can use the bot.
Allowlist Only: Only users in the allowlist can use the bot.
Pairing: First-time users who message the bot will receive a pairing code, access is granted once an administrator approves it. Users already on the allowlist do not need to pair.
Allow Group Chat
When enabled, the bot responds only when mentioned or replied to in group chats. You can further configure the Responsive Group Chats scope:
All Group Chats: The bot responds in all group chats.
Specified Group Chats: The bot responds only in specified group chats.
Message Processing
Busy Handling
Specifies how new messages are handled when the bot is processing a message. Valid values:
Interrupt and Redirect: Cancels the current task and processes the new message.
Collect and Merge: Merges the new message with the current task.
Queue: Queues new messages and processes them in order.
Group Chat Context Backfill
When set to a positive integer, authorized group messages that do not mention the bot are cached and used as context the next time the bot is triggered. Set to 0 or leave empty to disable this feature.
Streaming Response
When enabled, the bot sends multiple short messages paragraph by paragraph during the response process, instead of waiting for the complete response. This is suitable for scenarios that require fast feedback. Disabled by default.
Click Save after you complete the configuration.
Step 4: Test the bot
After the configuration is complete, add the bot to DingTalk and test it.
Group chat test
In DingTalk, go to Group Settings and click Bot. On the Bot Management page, click Add Bot.
In the search box, enter the bot name. Select the bot and click Add. Click Finish.
In the DingTalk group, mention the bot by using @bot to send a message. If the bot responds normally, it returns results in streaming card format. If the bot does not respond, check the enablement status and network connectivity on the channel card, and verify that the application permissions are properly configured.
Direct message test
In the search bar at the top of DingTalk, search for the bot name. Click the bot avatar to start a direct message conversation.
Send a message to the bot directly. If the bot responds normally, it returns results in streaming card format. If the bot does not respond, check the enablement status and network connectivity on the channel card, and verify that the application permissions are properly configured.