Overview
DataClaw supports two WeCom message receiving modes:
Feature | URL callback mode | Long-lived connection mode |
Connection method | WeCom actively pushes messages to the callback URL | The instance actively connects to the WeCom server |
Public network endpoint | Required (automatically created) | Not required |
Applicable scenarios | Containerized deployment, fine-grained access control | Quick integration, no public network required |
IP access control | Supports IP whitelist | Not applicable |
Authentication method | API Key | BotId + Secret |
URL callback mode: The WeCom server actively pushes user messages to the DataClaw instance through an HTTPS callback URL. This mode is suitable for scenarios that require fine-grained control over inbound IPs.
Long-lived connection mode: The DataClaw instance actively connects to the WeCom server to establish a persistent connection. This mode is suitable for quick integration scenarios that do not require a public network endpoint.
Prerequisites
A DataClaw instance has been created and is in the Running state.
You have the permissions to manage the WeCom admin console.
Create a WeCom robot
Go to the WeCom admin console. In the left navigation pane, click . Click Create Bot, and then click Create Manually.
Create an intelligent robot in API mode.
On the Create intelligent robot page, scroll to the bottom and click Create in API Mode.
Configure the following parameters and click Save.
Visibility Scope: Set the robot's visibility.
API Configuration: In the Connection Method section, select a connection mode.
Use Long-lived Connection: The instance actively connects to the WeCom server. In the Configuration Method section, under Secret, click Click to get and save the Bot ID and Secret.
Use URL Callback: The WeCom server actively pushes messages to the callback URL through HTTPS. You do not need to obtain a Bot ID or Secret. You only need to manually configure the Token and EncodingAESKey when configuring the instance in the DataWorks console.
Permissions: Set the required permissions for the robot.
Configure with long-lived connection mode
Return to the DataWorks console and go to the Channel Configuration section on the Basic Information tab of the instance details page.
In the Channel Configuration section, select WeCom as the channel.
Select Use Long-lived Connection as the connection mode.
Enter the Bot ID and Secret (obtained from the WeCom admin console).
Click Save.
Configure with URL callback mode
Configure the DataWorks AI assistant service instance
Return to the DataWorks console and go to the Channel Configuration section on the Basic Information tab of the instance details page.
In the Channel Configuration section, select WeCom as the channel.
Select Use URL Callback as the connection mode.
Enter or randomly generate the following parameters:
Parameter
Description
Format requirements
Token
Verifies the request source to ensure requests come from the WeCom server.
3 to 32 characters (letters or digits)
EncodingAESKey
Encrypts message content to prevent data from being intercepted or tampered with during transmission.
Format requirements: Must be exactly 43 characters (digits or letters).
Encryption standard: AES-256-CBC algorithm.ImportantKeep the Token and EncodingAESKey secure and do not disclose them to any third party.
The Token and EncodingAESKey can be generated either in the DataWorks console or in the WeCom admin console. After generating them in one console, copy the values to the other. The parameter values on both sides must be identical.
Configure the IP whitelist: Restrict access to the callback URL to specified IP ranges only. The IP whitelist must include the WeCom server IPs. For details on how to obtain them, see WeCom callback IP documentation.
Click Save.
After saving the configuration, wait until the instance status changes to Running.
In the WeCom channel information on the instance details page, you can view the Callback URL (callbackUrl) in the following format:
https://ai-assistants.cn-beijing.data.aliyuncs.com/xxxx/plugins/wecom/bot?apikey=sk-ai-assistants-xxxxxCopy the complete callback URL (including the ?apikey=... parameter) for use in the next step when configuring the WeCom admin console. If the page displays Callback configuration failed, check the failure reason and save the configuration again.
Configure in the WeCom admin console
Log on to the WeCom admin console.
Go to Security & Management > Management Tools > Intelligent Bot > Create Bot, and switch to Create in API Mode.
Set the connection method to URL Callback.
Enter the following three items:
Configuration item
Value
Description
URL
The callback URL copied from the DataWorks console
The complete URL, including the
?apikey=...parameterToken
Must be the same as the Token configured in the DataWorks console
Must be identical on both sides
EncodingAESKey
Must be the same as the EncodingAESKey configured in the DataWorks console
Must be identical on both sides (43 characters)
Click Save.
After saving, the WeCom server automatically sends a verification request to the callback URL:
Verification succeeded: The WeCom admin console displays a success message, and the instance can start receiving messages.
Verification failed: Check whether the Token and EncodingAESKey are exactly the same, the instance is in the Running state, the callback URL is fully copied (including the
?apikey=part), and the IP whitelist has been configured.
IP whitelist
The IP whitelist restricts which IPs can access the callback URL to prevent unauthorized requests.
Configuration method
In the IP Whitelist section on the instance edit page:
Add IP: Enter an IP address or CIDR block (such as
101.226.62.xxor10.0.0.0/8), and click Add.Delete IP: Click Delete in the whitelist.
We recommend that you obtain the latest callback IP list from the WeCom admin console and add it to the whitelist to prevent callback requests from being blocked.
Behavior when the whitelist is empty
If no whitelist has ever been configured: No IP access control is created, and all IPs can access the callback URL.
If all whitelist IPs are deleted:
127.0.0.1is automatically added, which blocks all external access (effectively disabling the callback endpoint temporarily). Add the WeCom callback IP ranges again to restore access.
API Key rotation
If the API Key is compromised or needs to be rotated periodically, hover over the URL Callback button, and click the refresh button in the pop-up window to refresh the API Key. After the refresh:
A new API Key is generated, and the old callback URL becomes invalid immediately.
You must update the new callback URL in the WeCom admin console.
After rotation, you must update the callback URL in the WeCom admin console. Otherwise, messages cannot be received.
Test the robot
In a group chat, click to add a member, search for the robot by name, and add it to the group.
In a group chat with the robot, @mention it to start a streaming conversation.
URL callback mode test: After the configuration is successful, when a user sends a message to the robot in WeCom, the DataClaw instance receives and processes the message in real time. You can check the channel status on the instance details page. A status of Connected indicates that the configuration is successful.
Switch modes
Switch from WebSocket to URL callback
In the channel configuration, change the connection mode to URL Callback.
Enter the Token and EncodingAESKey.
After clicking Save, complete the WeCom admin console configuration as described in Configure in the WeCom admin console.
Switch from URL callback back to WebSocket
In the channel configuration, change the connection mode to Use Long-lived Connection.
Enter the Bot ID and Secret.
After clicking Save, the webhook gateway resources are automatically cleaned up.
Modifying the channel configuration triggers an instance restart. After the restart, only workspace data (memory and skills) is retained. Custom dependencies must be reinstalled.
FAQ
Callback URL verification failed?
Check whether the Token and EncodingAESKey are exactly the same as those configured in the DataWorks console.
Verify that the instance is in the Running state and the callback configuration does not show a failure.
Verify that the callback URL is fully copied (including the
?apikey=...part).
Configuration succeeded but no messages received?
Check whether the IP whitelist includes the WeCom callback IP ranges.
Verify that the API Key has not been rotated (if rotated, update the callback URL in the WeCom admin console).
Check the instance details page for any callback-related error messages.
Callback still active after deleting the instance?
When an instance is deleted, all gateway resources are automatically cleaned up and the callback URL becomes invalid immediately. No additional action is required.
Callback not working after deleting the whitelist?
After all whitelist IPs are deleted, 127.0.0.1 is automatically added to block all external access. Add the WeCom callback IP ranges again to restore access.