DingTalk Integration
Connect a DingTalk Stream robot to Mopheus so people can work with agents and receive ticket updates in DingTalk.
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
Complete the following setup in the DingTalk Open Platform:
- Create an application under App Development, then record the application's AppKey and AppSecret.
- Open the application details, select Add Application Capability, and choose Robot.
- Open Robot Configuration, enable Stream mode/Stream event delivery, configure the robot message event, and grant the robot the permissions required to send, receive, and send media messages. If the robot needs to process images or files, also enable the corresponding media permissions.
- Make sure the application's availability scope includes the members and groups that need to use the robot.
Mopheus connects to DingTalk over an outbound Stream connection, so it does not need a public webhook URL, HTTP callback URL, deployment-specific secret, or environment switch. app_url is the address used for Mopheus account-binding links; it is separate from the DingTalk Stream connection.
Permissions and Events
| Configuration | Purpose |
|---|---|
| Robot message received event | Receive direct messages and group messages addressed to the robot |
| Robot message sending permission | Send agent replies, binding prompts, and ticket notifications |
| Image/file media permissions | Download and process images or files in messages |
| Application availability scope | Control which members and groups can use the robot |
After changing permissions or event subscriptions, save the robot configuration and confirm that connected robots use the latest configuration.
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. |