DingTalk Bot integration

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. The agent selected during setup is the robot's default for DMs and newly discovered groups. The same robot can join multiple groups, and each group can then be routed to a different agent. (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

1. Go to the DingTalk Open Platform and create an enterprise internal app (企业内部应用).
2. Open the app and add the robot (机器人) capability.
3. 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:

There is no webhook URL and no OAuth redirect URL, because the robot runs over Stream mode and BYO doesn't use OAuth.

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

1. Open the agent in Agents → your agent → the Integrations tab (or the Integrations section in the left sidebar).
2. Click Connect DingTalk.
3. Paste the AppKey and the AppSecret, then click Connect.
4. The agent shows Connected to DingTalk. The bot is now listening over its own Stream connection.

What the integration does

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.

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, 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 /new by itself to apply the fresh start to your next non-empty message. A bare /new gets 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).
• Group routing lists every group discovered by a bot. Owners and admins can select one fixed agent per group; all members can see the current routes.
• Every route change starts a new chat session for the selected agent. Routing Agent A → Agent B → Agent A does not resume A's earlier session. Archiving an assigned agent preserves the route but pauses processing with an unavailable notice until that agent is restored or the group is reassigned.
• 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.

1. 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.

2. 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.

Next

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