DingTalk Bot integration

Connect a Multica agent to your own DingTalk app — create a Stream-mode robot in the DingTalk Open Platform, copy its AppKey + AppSecret, paste them into Multica, 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 Multica issue without opening the app.

DingTalk support is community-maintained: it ships in every release, but it carries no official support SLA. Report problems in GitHub issues.

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 Multica. 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 Multica:

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 (Stream 模式 / 推送模式). This is what lets the bot connect out over a long-lived push connection instead of receiving a webhook.

This is everything Multica 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) and copy:

the AppKey — this is your app's client id
the AppSecret — this is your app's client secret

4. Connect it in Multica

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 Multica 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 Multica storage, so it stays visible in the chat after DingTalk's temporary link expires. Files and voice messages aren't supported.
`/issue` command	Starting a message with `/issue <title>` creates a Multica 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 remain attached to the chat turn; they are not copied onto the directly created issue.
`/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. 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 Multica, and your DingTalk identity is bound to your Multica 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. Multica creates the issue synchronously and posts its ID and title back into the chat. Images in that message stay on the chat turn and are not attached to the issue.
Start fresh — send /new <your message> to run that message without prior context, or send /new by itself to apply the fresh start to your next non-empty message. 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.

Self-host setup

On Multica Cloud the integration is already available — skip this section.

For self-host, DingTalk is off until you set an at-rest encryption key. The key encrypts each app's AppSecret before it reaches the database; the AppKey remains the installation's non-secret routing identifier. BYO needs no OAuth client id/secret at the deployment level — each installation uses the credentials the admin pastes.

Generate a 32-byte key and set it on the API server:
```
MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>
```
For example: openssl rand -base64 32.
Restart the API. Until the key is set, Settings → Integrations shows a "DingTalk integration not enabled" notice and the Connect DingTalk entry points stay hidden.

The key must decode to exactly 32 bytes — openssl rand -base64 32 does this. Treat it as a long-lived secret: rotating or losing it makes already-stored credentials undecryptable, forcing every bot to reconnect. The "link your account" link is built from your web app URL (MULTICA_APP_URL, falling back to FRONTEND_ORIGIN) — a normal deployment already sets this, so there's nothing extra to configure.

Chat integrations — how the channel engine, sessions, and authorization work
Agents · Chat · Issues
Environment variables — full self-host configuration reference