DingTalk
1. Prerequisites
- A DingTalk Open Platform account (either an internal enterprise app or a third-party app works)
- Admin permissions on the Agentic Engine platform
2. Create a DingTalk app and get credentials
Go to DingTalk Open Platform, log in, and follow these steps:
- Go to Developer Console > App Development > Internal Enterprise Apps, and click Create App.
- Enter the app name and description.
- After the app is created, go to the app details page > Credentials & Basic Info and note down the following two values:
| Field name | Platform field | Description |
|---|---|---|
| AppKey | Client ID | Unique app identifier, used for OAuth authorization |
| AppSecret | Client Secret | App secret. Keep it safe and don't disclose it |
Get the company CorpId
Open DingTalk Developer Platform and log in. Find CorpId in the company information card on the right side of the home page, and copy the complete value. When you add a DingTalk channel, you must enter this CorpId together with the Client ID and Client Secret.
CorpId uniquely identifies the current company, and each company has a different value. Use the complete value shown on your own company's page, and don't copy the value from examples or screenshots.
- Go to Add App Capabilities > Robot, and in the robot configuration, set the message receiving mode to Stream Mode.
- In the app's Permission Management, enable the following permissions:
Read personal contact information,Employee mobile number information,DingTalk group basic information management,Read member information,Send messages by enterprise robots,Write interactive card instances,AI card streaming updates, andWrite intelligent interactive cards. You don't need to enable Enterprise Storage App Read permission: This permission is for enterprise storage APIs, which the current channel implementation doesn't call. - In Security Settings, add the Agentic Engine server IP to the outbound IP whitelist, and set the OAuth redirect URL (callback domain) to:
https://<your-domain>/api/dingtalk-oauth/callback - Each time you change the configuration, go to Version Management and Release, click View version details, edit the version number and version description, and then click Publish.
3. Add a DingTalk channel in the platform
As an admin, log in to Agentic Engine and go to System Admin > Agent Management > Channels:
- Click New Channel and select DingTalk as the channel type.
- Fill in the following configuration items:
| Config items | Required | Description |
|---|---|---|
| Channel Name | Required | Display name, such as "Company DingTalk". |
| Corp ID | Required | Unique identifier of the DingTalk company, used to verify the company identity and set up the group chat space. You can copy it from the company information in the DingTalk admin console. |
| Client ID | Required | Enter the AppKey of the DingTalk app. |
| Client Secret | Required | Enter the AppSecret of the DingTalk app. |
| Interactive question card template ID | Optional | ID of the DingTalk AI Card template, in the format "xxxxxxxx.schema". Use a published DingTalk AI Card template that conforms to the project's variable contract. If left empty, questions automatically fall back to text replies. |
| Default Model | Optional | Used for single-Agent channel tasks. If left empty, the system-wide default model is used. Teams use the models configured for each member. |
| Channel Input Suffix | Optional | Appended to each round of channel input as additional instructions. It doesn't replace the Agent's own system prompt. |
- Click Save. After the channel is created, its status shows Running.
One company can create multiple DingTalk channel instances, but the same DingTalk bot identity can't be configured more than once in the same environment. After you change the Client ID, Client Secret, or Corp ID, you need to verify again and re-enable the corresponding group chat space. Changing only the name, default model, or channel input suffix doesn't invalidate a verified space.
4. Bind a DingTalk account
After the admin finishes configuring the channel, regular users can bind their own DingTalk accounts in Channel Accounts in the user menu:
OAuth authorization binding
- Open the AE user menu, go to Channel Accounts, find the target channel instance under DingTalk, and click Bind.
- The system redirects you to the DingTalk OAuth authorization page. Scan the QR code or log in to your DingTalk account to complete authorization.
- After authorization succeeds, you're automatically redirected back to the platform, and the binding status changes to Bound.
If a binding code dialog appears after you click Bind, send the complete binding command from the dialog to the bot in a direct message in DingTalk (the binding code is valid for 10 minutes). For details, see Channel overview and binding.
5. Group chat message routing
Group chat message routing lets the same DingTalk bot hand different questions to different Agents or Teams based on rules. A Group Chat Space corresponds to the company CorpId in the configuration, and the rules apply to group chats in that company that use this bot. Only members who have bound an Agentic Engine account and explicitly @mention the bot in the group can start tasks.
Admin setup
- Make sure that the app uses Stream mode, that the Client ID, Client Secret, and CorpId are all filled in, and that the permissions described earlier in this document are enabled, such as group basic information, bot message sending, interactive cards, and AI card streaming updates.
- Go to System Admin > Agent Management > Channels, and open Message Routing on the corresponding DingTalk channel (the dialog is titled Group Chat Message Routing). After verification succeeds, the system creates a group chat space based on the CorpId.
- Select the Default Agent/Team. You must configure the default before you enable group chat routing.
- Add up to 19 rules as needed. For each rule, select an Agent/Team, fill in the required Command, and optionally add up to 10 keywords. Then turn on the enable switch and save.
- Send
@机器人 /helpin the group to verify the setup.
| Config items | Rule |
|---|---|
| Default Agent/Team | Required before enabling. Used when no command is specified and no keyword is matched. |
| Command | Required, 1–32 characters. You can use letters, digits, -, and _, but not system-reserved commands. Differences in letter case or between full-width and half-width characters don't make commands distinct. |
| Keywords | Optional. Up to 10 per rule, each 2–32 characters. When multiple keywords match, the longer keyword takes priority. If no unique match can be determined among keywords of the same length, the default Agent/Team is used. |
| Available options | You can select enabled and runnable system/company Agents, as well as Teams in the current company. Personal Agents don't appear as candidates. |
Use in group chats
| Purpose | Example | Description |
|---|---|---|
| View available capabilities | @机器人 /help@机器人 能力清单 | Shows only the capabilities that the current user can use and that can currently run. |
| Specify an Agent/Team | @机器人 /analysis 分析本周数据 | You can also send @机器人 @analysis 分析本周数据. |
| Route by keyword | @机器人 帮我检查埋点方案 | Uses the matching rule when a keyword matches, and the default otherwise. |
| Cancel a task | @机器人 /cancel | Must be sent exactly as the entire message. Text already output is kept, and a separate cancellation confirmation is sent. |
| Legacy syntax | @机器人 /agent analysis 分析本周数据 | Still supported, but using /analysis directly is recommended. |
Command scope: Group chat routing doesn't support /new. Direct messages still support /new, /agent, and /cancel. To start a regular new task, you must first @mention the bot. When the bot is waiting for your reply, continue by following the bot's card or text prompt.
Public context and personal data: For reference, the system uses only recent public group chat turns that explicitly @mentioned the bot and were actually processed. Regular group messages that don't @mention the bot, other groups, direct messages, and personal memories are never mixed in.
6. FAQ
Abnormal channel status / connection failure
- Check that the Client ID and Client Secret are entered correctly.
- Make sure that the app's status on DingTalk Open Platform is Online or In Development.
OAuth callback failure
- Make sure that the platform server IP whitelist has been added in Security Settings of the DingTalk app.
- Make sure that the callback URL is configured correctly and exactly matches the platform's actual deployment domain, including the protocol and path.
Users can't bind their accounts
- Make sure that the required permissions are enabled for the DingTalk app.
- Make sure that the app's callback URL is configured correctly.
Related pages and next steps
- See the setup instructions for other platforms: Channel management.
- Learn about the overall flow of channel connection and binding: Channel overview and binding.
- Configure the Agent to use: Agent.
- See how to use conversations in the platform: Conversations.