DingTalk Bot integration
Connect a Kolleague agent to your own DingTalk app — create a Stream-mode robot in the DingTalk Open Platform, copy its AppKey + AppSecret, paste them into Kolleague, then DM it, @-mention it in a group, or type /issue from inside DingTalk.
Connect any agent to a DingTalk bot and your team can work with it from inside DingTalk — DM the bot, @-mention it in a group, send it screenshots, or type /issue to file a Kolleague issue without opening the app.
DingTalk uses a bring-your-own-app (BYO) model: a workspace admin creates a DingTalk app, adds a Stream-mode robot to it, and pastes its credentials into Kolleague. Each agent gets its own DingTalk app — so several agents can each have a distinct, separately @-mentionable bot in the same organization. (This differs from Lark, where binding is a scan-to-install flow.)
The whole setup is below and takes about five minutes. You'll end up with two credentials to paste into Kolleague:
- an AppKey — the app's client id
- an AppSecret — the app's client secret
Set up your DingTalk app
1. Create the app and add a Stream-mode robot
- Go to the DingTalk Open Platform and create an enterprise internal app.
- Open the app and add the robot capability.
- In the robot settings, set the message-receiving mode to Stream mode. This is what lets the bot connect out over a long-lived push connection instead of receiving a webhook.
This is everything Kolleague needs at the platform level — it connects out over Stream mode, so you don't configure any public address:
| Setting | Why it's there |
|---|---|
| Enterprise internal app | The app container that owns the robot and issues the AppKey / AppSecret credentials. |
| Robot capability | Creates the bot identity that gets @-mentioned and posts replies. |
| Stream mode | The bot connects out over a long-lived Stream connection — no public webhook / URL needed. |
| Robot send permission | Lets the bot send messages back into DingTalk (the agent's replies and proactive messages). |
| Message-read scopes | So the bot receives 1:1 messages and the group messages that @-mention it. |
There is no webhook URL and no OAuth redirect URL, because the robot runs over Stream mode and BYO doesn't use OAuth.
DingTalk has no native typing / reaction indicator, so — unlike Slack — the bot instead posts a short "working on it" acknowledgement when it starts, and the full reply follows once the agent is done. A quick burst of messages is coalesced into a single acknowledgement.
2. Grant the robot its permissions
Grant the robot the scopes it needs so it can receive messages and send messages back (the robot message-send permission). Without the send permission the agent can run but its reply can't be delivered.
3. Copy the AppKey and AppSecret
Open the app's Credentials & Basic Information section and copy:
- the AppKey — this is your app's client id
- the AppSecret — this is your app's client secret
4. Connect it in Kolleague
- Open the agent in Agents → your agent → the Integrations tab (or the Integrations section in the left sidebar).
- Click Connect DingTalk.
- Paste the AppKey and the AppSecret, then click Connect.
- The agent shows Connected to DingTalk. The bot is now listening over its own Stream connection.
Both credentials must be from the same DingTalk app, and that app maps to exactly one agent. Connecting an app that's already connected to a different agent or workspace is refused. To move an app to another agent, disconnect it first; re-connecting an agent with a new app updates that agent's bot in place.
Setting this up for multiple agents? Repeat the whole flow once per agent — each agent gets its own DingTalk app and its own AppKey / AppSecret, and they show up as separate bots in your organization.
What the integration does
| Surface | Behavior |
|---|---|
| Agent → Integrations | Owners and admins see Connect DingTalk; once connected it flips to a Connected to DingTalk badge with a Disconnect control. |
| DM the bot | A workspace member messages the bot in a 1:1 chat. The conversation becomes a Kolleague chat session with the agent; every message is read. |
| @-mention in a group | Add the bot to the group and @-mention it. Only the mentioning message is read — the bot does not listen to the whole group. |
| Send images | Images in a DM, or sent alongside a group @-mention, land in the conversation for the agent to see — PNG, JPEG, GIF, WebP, or BMP, up to 4 images per message and 10 MB each. Each image is copied into Kolleague storage, so it stays visible in the chat after DingTalk's temporary link expires. Images sent with /issue go to the created issue instead of the chat turn. Files and voice messages aren't supported. |
/issue command | Starting a message with /issue <title> creates a Kolleague issue directly from your input, attributed to you, and posts the issue ID and title back into the same conversation. Put the description on following lines. Images sent in the same DingTalk message are attached to the created issue. The command itself does not appear in Kolleague Chat; the created issue is the result recorded in Kolleague. |
/new command | Starting a message with /new <your message> runs that message without prior conversation context. Sending /new by itself records the same fresh-start intent for your next non-empty message without creating an empty turn, and the bot confirms when that intent is ready. The pending intent remains active until a later chat task is successfully queued. The conversation history remains intact. |
| Reply | The agent's answer is posted back into the same 1:1 chat or group. |
Use the bot (members)
First message: link your account
The first time you @-mention or DM the bot, it replies with a link your account prompt pointing at the in-product /dingtalk/bind page. Tap the link, sign in to Kolleague, and your DingTalk identity is bound to your Kolleague membership — this is what lets the agent act as you (e.g. /issue files under your name). The link is single-use and expires in about 15 minutes; just message the bot again for a fresh one.
Only members of the workspace can use the bot. If you aren't a member, or you skip the identity link, the bot won't run — your message is dropped (recorded for audit, without its contents).
Chat and commands
- In a group — add the bot to the group, then
@your-bot <your message>. Re-mention it for each follow-up (the bot only reads messages that mention it). - In a 1:1 chat — open the bot and message it directly; no mention needed, every message is read.
- Send images — send screenshots or photos, with or without text; they show up in the conversation for the agent to work with. PNG, JPEG, GIF, WebP, or BMP; up to 4 images per message, 10 MB each.
- File an issue — send
/issue the login redirect is broken on Safari; add the description on following lines if needed. Kolleague creates the issue synchronously, attaches images from that message to it, and posts its ID and title back into the chat. - Start fresh — send
/new <your message>to run that message without prior context, or send/newby itself to apply the fresh start to your next non-empty message. A bare/newgets a confirmation, and its pending intent remains active until a later chat task is successfully queued. Neither form removes the existing conversation history.
Manage and disconnect
Workspace-wide management lives in Settings → Integrations:
- Connected bots lists every bot in the workspace and the agent each is bound to (visible to all members).
- Disconnect is owner / admin only. It stops the bot from receiving DingTalk messages and tears down its connection; the installation record is kept for audit, and you can re-connect later.
Permissions
- Connect / disconnect require workspace owner or admin.
- Talking to the bot requires being a workspace member with a linked DingTalk identity. Everyone else is dropped.
- Message bodies for dropped messages are never stored — only a drop reason, for audit.
Next
- Chat integrations — how the channel engine, sessions, and authorization work
- Agents · Chat · Issues