The Unified IM Gateway is a tenant-level IM access capability provided by the DataWorks Management Center. It centrally hosts the bot credentials for DingTalk, Feishu, and WeCom, processes messages with the permissions of the account that created the IM gateway, and connects Agent instances such as Data Agent to IM. You do not need to create and maintain a bot for each instance; instead, you can @ the bot in IM to converse with an Agent and complete operations such as data queries and task diagnostics. This topic describes the core concepts, configuration steps, and common usage of the Unified IM Gateway.
Overview
In enterprise data development and O&M scenarios, IM platforms such as DingTalk, Feishu, and WeCom are usually the primary entry points for team collaboration and communication. The Unified IM Gateway manages IM bots and their credentials at the tenant level, so you do not need to create and maintain a bot for each Agent instance. The same bot can be bound to instances of different Agent types, such as Data Agent, AI Assistant Service, and senior domain Agent, and you can switch between instances as needed. Messages are routed to the bound target Agent instance and processed by the Agent with the permissions of the DataWorks account that created the Unified IM Gateway. Without switching platforms, you can @ the bot in an IM group chat or one-on-one chat to interact with the Agent, complete conversational data queries, task diagnostics, and O&M handling, and view the Agent execution process in real time.
The Unified IM Gateway provides the following core capabilities:
Unified bot hosting: Creates and maintains DingTalk, Feishu, and WeCom bots and their credentials centrally at the tenant level. All Agent instances share the same set of bots, so no duplicate creation is needed.
Unified execution permissions: The Unified IM Gateway processes messages with the permissions of the DataWorks account that created the gateway. When a user converses with an IM bot, the gateway routes the message to the bound Data Agent, and the Data Agent operates within the permissions of the account under which the IM bot is registered, for example, listing the Agent instances under that account.
Agent binding and message routing: Binds a bot to one or more Agent instances and routes IM messages to the target instance per session.
Consistent interaction across platforms: Provides consistent interaction capabilities such as conversation, instance switching, and sleep and wake in DingTalk, Feishu, and WeCom.
Scheduled task result push: Serves as the result-push channel for scheduled tasks in modules such as Operation Center, pushing task execution results to a specified IM session.
The Unified IM Gateway covers two usage scenarios. Scenario 1: converse with an Agent in IM to complete data queries, task diagnostics, and O&M handling. Scenario 2: use the Unified IM Gateway as the push channel for scheduled task execution results, pushing results to a specified IM session. The following sections first introduce the core concepts and onboarding steps, then describe the configuration and usage of the two scenarios.
Core concepts
Bot hosting and binding
The Unified IM Gateway creates and maintains DingTalk, Feishu, and WeCom bots and their credentials centrally at the tenant level. All Agent instances share the same set of bots, so no per-instance duplicate creation is needed. Binding refers to the association between a bot and an Agent instance: the same bot can be bound to instances of different Agent types, such as Data Agent, AI Assistant Service, and senior domain Agent, and can switch between bound instances as needed. After a user sends a message, the Unified IM Gateway routes the message to the target Agent instance according to the binding relationship of the current session.
In a group chat, if the bot is configured in group-shared mode, all members in the group converse with the same Agent instance.
Execution permissions and tenant isolation
The Unified IM Gateway processes messages with the permissions of the DataWorks account that created the gateway: after a message is routed to the bound Agent instance, the instance operates within the permissions of that creating account, for example, pulling data resources under the account. Messages are isolated by tenant and are not transferred across tenants.
Scenario 1: message link
After the Unified IM Gateway is connected, messages flow through the following link: a user sends a message to the bot on the IM platform; the Unified IM Gateway receives the message and routes it to the bound target Agent instance; the instance processes the message and returns the result to the Unified IM Gateway; finally the bot replies on the IM platform.
Scenario 2: result push link
Scheduled tasks in DataWorks modules such as Operation Center support selecting the Unified IM Gateway in the result-push configuration. After a task completes, the execution result is sent by the Unified IM Gateway through the hosted bot to the specified IM session (group chat or one-on-one chat), with no need to create a separate bot for the scheduled task.
Prerequisites
DataWorks is activated, and the current account has the management permission for tenant configuration in the Management Center.
A target Agent instance (such as Data Agent) is created. For creation methods, see Data Agent introduction.
An enterprise bot is created on the corresponding IM platform, and the bot credentials (such as AppKey and AppSecret) are obtained. The credentials in the examples in this topic are placeholders; replace them with your actual values.
Limits
The supported IM platforms are DingTalk, Feishu, and WeCom.
Interaction capabilities differ across platforms, as shown in the following table.
Capability
DingTalk
Feishu
WeCom
Streaming reply
Supported (streaming card)
Supported (streaming card)
Supported (native streaming)
Stop reply
Supported (stop button)
Supported (stop button)
Not supported
Supplementary information
Asks back in message body
Asks back in message body
Asks back in message body
Read referenced file content
Supported
Not supported yet
Supported
In a group chat, you must @ the bot before sending a message. If the bot is configured in group-shared mode, all members in the group converse with the same Agent instance; after any member switches the instance, the switch takes effect for all members in the group.
Messages are isolated by tenant and are not transferred across tenants.
Onboarding steps
The following steps connect the Unified IM Gateway: add a bot in the Unified IM Gateway, bind Agent instances to the bot, and verify the connection in IM.
Step 1: Add a bot in the Unified IM Gateway
Log on to the DataWorks console and go to Management Center.
In the left-side navigation pane, choose Tenant Configuration > Unified IM Gateway, and click the Bot tab.
Click Add Bot, select an IM platform (DingTalk, Feishu, or WeCom), enter the bot credentials, configure the group-shared mode as needed, and then click OK.
Credential examples (replace with your actual values):
AppKey:
<YOUR-APP-KEY>AppSecret:
<YOUR-APP-SECRET>
In the bot list, you can perform the following management operations on existing bots:
Operation | Description |
Edit | Modifies the bot name, credentials, or group-shared mode. |
Enable / Disable | Controls whether the bot takes effect. After a bot is disabled, it no longer receives or replies to messages. |
Delete | Deletes the bot. You must enter the bot name for secondary confirmation before deletion. |
The Unified IM Gateway processes messages with the permissions of the DataWorks account that created the gateway. For details, see Execution permissions and tenant isolation.
Step 2: Bind Agent instances to the bot
A bot can process messages only after it is bound to Agent instances. You can complete the binding from either of the following entries; the binding relationships of the two entries are synchronized with each other.
Method 1: Bind on the Unified IM Gateway side
In the Bot list, find the target bot and click Bind in the Actions column.
In the dialog box, select the Agent type (Data Agent, AI Assistant Service, or senior domain Agent) and the target Agent instance, and then click Bind.
View the binding result in the bound list. You can filter by type, refresh, and Unbind.
Data Agent and AI Assistant Service support creating multiple instances, and the drop-down list shows the instances already created under the type. A senior domain Agent is a built-in agent for each business domain (Data Integration, Data Quality, Data Governance, Data O&M, and Knowledge Assistant); each type has only a single instance (that is, the built-in agent under the AI workbench of the corresponding module), so no separate creation is needed and you can bind it directly after selection. For more information, see Agent types and selection.
Method 2: Bind on the instance-side IM channel
Go to the details page of the target Data Agent instance and click IM Channel. The page displays the binding status and connection status for DingTalk, Feishu, and WeCom.
On the channel card of the target platform, click Configure: if a bindable hosted bot exists, select the target bot in the dialog box to complete the binding directly; if no bindable bot exists, click Create and Bind, enter the bot name and credentials (such as App ID and App Secret) in the dialog box, and the bot is created, automatically bound to the current Agent, and brought under Unified IM Gateway hosting.
After the binding completes, the channel card displays the bot name and the ready and connection status. To unbind, click Unbind on the card.
The binding and unbinding operations of the two entries are synchronized with each other: after a binding or unbinding is completed at either entry, the binding status displayed at the other entry is updated accordingly.
Step 3: Verify the connection
Start a one-on-one chat with the bot on the IM platform, or @ the bot in a group chat.
Send a data query or task diagnostic message. If the bot returns the Agent processing result normally, the connection is successful. For how to use the Agent selection card and switch instances in the first conversation, see Scenario 1: Converse with an Agent in IM.
Scenario 1: Converse with an Agent in IM
After the binding completes, you can converse with the Agent in a one-on-one chat or group chat to complete conversational operations such as data queries and task diagnostics. The following uses DingTalk as an example; operations on Feishu and WeCom are the same.
Converse with the Agent
In IM, start a one-on-one chat with the bot and send a request directly; in a group chat, @ the bot and then send. Example: @bot diagnose the failure cause of yesterday's sync task for instance X.
In the first conversation, the bot returns an Agent selection card; select the Agent type and instance on the card. The selection takes effect for the current session, and you can run
/listagain later to change it.The Agent processes the request with the permissions of the creating account (see Core concepts) and returns the result in the session. When supplementary information is needed, DingTalk asks back with an interactive card, while Feishu and WeCom ask back in the message body.
Conversation effect
Example conversation effect (DingTalk group chat):
User: @bot diagnose the failure cause of yesterday's sync task for instance X.
Agent: returns the diagnostic conclusion and handling suggestions with execution details; the user can continue to follow up in the session, or run /list to switch to another Agent instance.
Agent types and selection
The Agents that a bot can be bound to are divided into the following types; the selection card marks the type and running status:
Agent type | Description | Instance display scope | Sleep / Wake |
Data Agent | A general-purpose agent. Supports creating multiple instances. | Shows all bound instances, including sleeping ones. | Supported. If the instance is sleeping during a session, it is woken automatically. |
AI Assistant Service | An agent for data O&M scenarios. Supports creating multiple instances. | Running instances only. | Not supported. |
Senior domain Agent | Built-in agents such as Data Integration, Data Quality, Data Governance, Data O&M, and Knowledge Assistant. Each type has only one instance, with no separate creation needed. | Shows all bound instances, including sleeping ones. | Supported. If the instance is sleeping during a session, it is woken automatically. |
IM commands
The following commands are supported in a one-on-one chat or group chat. The selection result of a command takes effect per session; running /list again and selecting overwrites the previous selection.
Command | Description |
| Returns the Agent selection card; clicking an option switches the default Agent of the current session. |
| Lists running Data Agents; after confirmation, asynchronously sleeps the selected instance. |
| Lists sleeping Data Agents; selecting one wakes the selected instance automatically. |
Interaction capabilities
One-on-one chat and group chat: In a one-on-one chat, send a message directly to converse with the Agent; in a group chat, you must @ the bot.
Streaming reply and stop: The Agent processing process is displayed in real time in a streaming manner. DingTalk and Feishu support stopping during a reply.
Card More Actions (DingTalk): The reply card in a DingTalk session provides a More Actions menu for session and instance management: Start New Session, Reset Session, Compress Context, Switch Agent, and Wake Instance.
Supplementary information: When the Agent needs supplementary information, DingTalk collects it via a Q&A card, while Feishu and WeCom ask back in the message body; reply in a subsequent message to continue processing.
Images and files: Supports sending images and files for the Agent to recognize and process. When only a file is sent, a receipt is returned; after you reference the file and ask a question, the Agent reads and processes it.
Quoted message: Supports quoting a message and following up; the Agent reply incorporates the quoted content.
Scenario 2: Push scheduled task results to IM
In addition to conversing with the Agent in IM, the Unified IM Gateway can serve as the push channel for scheduled task execution results. Scheduled tasks in DataWorks modules such as Operation Center support selecting the Unified IM Gateway in the result-push configuration; after a task completes, the result is pushed to the specified IM session.
Configure result push
The following uses an AI scheduled task in Operation Center as an example:
In the create or edit scheduled task dialog box, switch to Result Push.
In Push Method, select Unified IM Gateway.
Select the IM bot and the session type (group chat or one-on-one chat).
Select a push target. The target can be a user or a group chat. The drop-down list shows only objects that have exchanged messages with the bot, that is, users to whom the bot has sent messages, or group chats in which the bot has sent messages. Click Add Push Target to configure multiple push targets.
Complete the remaining task configuration and save. After the task completes, the execution result is pushed to the specified IM session through the Unified IM Gateway.
Push effect
After the task completes, the bot sends a result message to the specified group chat or one-on-one chat. The content includes the task name, success or failure status, execution summary, and details entry. When a task fails, relevant personnel can perceive and handle it immediately in IM.
Result push reuses the bots already hosted by the Unified IM Gateway, with no additional credential configuration needed; the push target must be an IM session reachable by the bot.
FAQ
Q: After connecting the Unified IM Gateway, do I still need to enter bot credentials separately in the instance?
A: When binding a bot already hosted on the gateway side, no duplicate credential entry is needed. If you create a new bot and bind it in the instance-side IM Channel, you must enter the bot credentials at creation; afterwards the credentials are hosted centrally by the Unified IM Gateway.
Q: How do I choose between Unified IM Gateway connection and instance-side standalone Channel connection?
A: The Unified IM Gateway hosts bots at the tenant level; a bot can be shared by multiple instances and credentials are maintained centrally, suitable for unified connection across multiple instances and platforms. The instance-side standalone Channel connection maintains credentials separately at the instance level, suitable for standalone connection of a single instance. The Unified IM Gateway is recommended.
Q: What should I note when migrating from instance-side standalone Channel to the Unified IM Gateway?
A: First add the bot in the Unified IM Gateway and complete Agent binding, then disable the original standalone Channel configuration in the instance. The same bot should not be enabled in both places at the same time; otherwise duplicate connections and duplicate replies may occur.
Q: How do I troubleshoot when the bot does not respond or message sending/receiving is abnormal?
A: Troubleshoot layer by layer according to the following responsibility boundaries:
Platform connection: Confirm that the bot is enabled and the credentials are entered correctly.
Execution permissions and instance routing: Confirm that the creating account's permissions cover the target resources (see Core concepts), and that the bot is bound to the target Agent instance.
Instance execution: Confirm that the target instance is running; if it is sleeping, send
/awaketo wake it.Final reply: Confirm that the involved capabilities are supported on the target IM platform (for platform capability differences, see Limits).
Q: What do I do if @ the bot in a group chat gets no response?
A: Confirm that the bot is enabled and bound to an Agent instance. If the bot is configured in group-shared mode, group members share the same Agent instance; after any member switches the instance, the switch takes effect for all members in the group.