Connect a DingTalk Stream robot to Mopheus so people can work with agents and receive ticket updates in DingTalk.

DingTalk Integration

The DingTalk integration connects a DingTalk Stream robot to an agent or team in Mopheus. Direct messages are processed immediately. In a group, a message must mention the robot. Messages, images, ticket status changes, and regular ticket comments are returned to the originating DingTalk conversation.

Prerequisites

Create an internal robot application in the DingTalk Open Platform and enable Stream event delivery. Configure the bot message event and grant the robot the permissions required to receive and send messages. Record the application's AppKey and AppSecret.

Mopheus connects to DingTalk over Stream, so no public webhook URL or deployment-specific callback secret is required.

Configure Mopheus

In Settings → System Config, configure these values:

Setting	Value
Enable Channels (`channel_enabled`)	`true`
Enable DingTalk (`dingtalk_enabled`)	`true`
DingTalk Secret Key (`dingtalk_secret_key`)	A base64-encoded 32-byte key used to encrypt installed AppSecrets
App URL (`app_url`)	The public URL of the Mopheus web application, such as `https://app.example.com`

The App URL is used in the one-time account-link message. It must point to the web application that serves /dingtalk/bind, not to an unavailable local development port or the API host.

Use Generate or Rotate next to dingtalk_secret_key in System Config. Rotation re-encrypts every installed DingTalk AppSecret before the new key is stored. Do not replace the value manually after installations exist.

Connect a Robot

Open an agent or team, then select Connect DingTalk App in its integrations section. The form accepts exactly two values:

Field	DingTalk value
AppKey	Application AppKey
AppSecret	Application AppSecret

Mopheus validates the credentials before saving them and encrypts the AppSecret at rest. After the installation is committed, the channel supervisor reconciles its connections and starts the robot when both channel switches are enabled.

Link Accounts

The first unbound sender receives a private Markdown link to /dingtalk/bind. Open the link while signed in to Mopheus to connect the DingTalk identity to the current Mopheus account. The token is single-use and expires after 15 minutes.

The binding link is always sent as a direct message, even when the original message came from a group. This prevents another group member from binding somebody else's DingTalk identity.

Messages and Media

Direct messages are routed to the selected agent or the leader of the selected team.
Group messages are routed only when the robot is mentioned.
DingTalk images, including images embedded in rich text, are downloaded immediately, validated as image content, stored as Mopheus attachments, and made available to the agent task.
Files are fetched through a restricted download client: local, private, loopback, and unsafe redirect targets are rejected.
Long agent replies are split into valid DingTalk Markdown messages. Access tokens are cached and automatically refreshed once if DingTalk rejects an expired token.

Ticket Notifications

When an agent creates a ticket from a DingTalk conversation, Mopheus stores the immutable source chat session and source message in the ticket metadata at creation time. Later status changes and regular comments are delivered back to that original conversation. Older tickets without a source-message anchor fall back to the conversation route.

Troubleshooting

Symptom	Check
The installation is saved but no Stream logs appear	Confirm both `channel_enabled` and `dingtalk_enabled` are `true`. Saving an installation reconciles supervisors only after the database transaction succeeds.
The account-link page fails	Confirm `app_url` is the reachable frontend URL and that the user is signed in before opening the link. Generate a new link after correcting an old URL.
The bot ignores a group message	Mention the robot in the group and confirm the installation is active.
The bot cannot read an image	Check the bot's media permissions and make sure the image is within the inbound size limit.
Existing robots fail after key changes	Use the System Config rotation action; manually replacing `dingtalk_secret_key` cannot decrypt prior AppSecrets.