DingTalk Bot

After connecting an agent to DingTalk, members of the agent's workspace can DM the Bot, @-mention it in a group, or use the /issue command to create a trackica issue directly. Conversations and run records are saved to the trackica workspace.

Connect the Bot

The agent's creator or a workspace owner/admin can connect the agent to DingTalk. Agents and DingTalk Bots have a one-to-one connection.

1. Create a Stream-mode robot

1. Create an enterprise internal app in the DingTalk Open Platform.
2. Enable the robot capability and set Message Receiving Mode to Stream Mode.

2. Grant permissions to the robot

The Robot Message Sending permission (qyapi_robot_sendmsg) is added by default. To show the Bot's name in trackica, manually add the DingTalk Group Basic Information Management permission (qyapi_chat_manage).

3. Get the application credentials

Open Credentials & Basic Information page and copy the Client ID (AppKey) and Client Secret (AppSecret).

4. Connect the agent to DingTalk

1. Return to trackica and open Agents → your agent → Capabilities → Integrations.
2. Click Connect DingTalk.
3. Enter the AppKey and AppSecret, then submit.

5. Link your DingTalk and trackica accounts

DM the Bot in DingTalk or @-mention it in a group to trigger a linking request. You will receive a link in your DM with the Bot; it is valid for about 15 minutes. Open the link. When the success message appears, account linking is complete.

Give the agent work in DingTalk

Direct messages

Send the Bot a message. When the agent finishes the work, it replies with the result in the DM.

Group chats

Add the Bot to a DingTalk group, then send @your-bot <message>. You must @-mention the Bot again in every follow-up. The Bot processes only messages that @-mention it.

Send images

Direct messages and group chats both support messages containing text and images. Supported image formats are PNG, JPEG, GIF, WebP, and BMP. Each message can contain up to 4 images, with a maximum size of 10 MB per image. Files and voice messages are not currently supported.

Create an issue with /issue

Send /issue <title> or /issue <title>{newline}<detailed description> to create a new trackica issue and automatically assign it to the agent connected to the Bot. Images in the same message are also added to the issue as attachments. Unlike regular chat messages, the /issue command leaves no record in trackica Chat.

Start over with /new

Send /new, and the next message sent successfully will be processed by the agent in a fresh context. You can also send /new <message> to have the agent process that message immediately in a fresh context.

The /new command only makes the agent process messages in a fresh context. It does not create a new trackica Chat.

Manage connections

• On Agents → your agent → Capabilities → Integrations, the agent's creator and workspace owners/admins can connect the agent to DingTalk or disconnect it. Once connected, this page shows the Bot's name, DingTalk groups where it has successfully processed messages, and its activity status data in those groups. Any workspace member with read access to the agent can see this information. Groups with no successfully processed messages in the last 90 days are placed under Long inactive and loaded when expanded.
• Settings → Integrations lists every DingTalk-connected agent in the current workspace that the viewer can read, along with the Bot's activity status data in DingTalk groups. Workspace owners/admins can also disconnect any listed agent from DingTalk. After disconnection, the Bot stops receiving messages, while the installation record is retained for audit. Workspace owners/admins can also forget a group. This removes the group from the list without deleting conversations or messages. The group reappears if a workspace member with a linked DingTalk account later @mentions the Bot there and trackica accepts the message.

Self-hosting setup

A private deployment must first set a key for encrypting the DingTalk AppSecret:

TRACKICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>

Generate one with:

openssl rand -base64 32

Restart the API service, then connect DingTalk. Keep this key permanently: if it is changed or lost, existing tokens cannot be decrypted and the connection must be set up again.

Account-linking URLs use TRACKICA_APP_URL, falling back to FRONTEND_ORIGIN when it is unset. The URL must point to a trackica address that members can access.

Next

• Chat integrations — how the Channel engine, sessions, and authorization work
• Agents · Chat · Issues
• Environment variables — complete self-hosting configuration reference