DingTalk Integration Guide

This guide will help you configure a Tencent WorkBuddy bot in DingTalk, so you can remotely control Tencent WorkBuddy on your computer to complete tasks anytime, anywhere.

Prerequisites

Before you begin, make sure you have:

• Tencent WorkBuddy installed on your computer with the Claw remote control feature enabled
• A DingTalk account with enterprise admin permissions

Tip: If you don't have a DingTalk account, download the client from the DingTalk website and create a team.

Step 1: Create a DingTalk App

Log in to the developer console

Open your browser and go to the DingTalk Open Platform. Log in with your admin account.

First time? If the system prompts "This account has not joined an organization", you can create a personal organization with any information.

Create the app

1. On the developer console home page, click App Development, then click Create App.
2. Fill in the following information (all fields can be updated later):

Field	Description
App name	Any name you like
App description	Brief description of the purpose
App type	Can be left blank for now

3. Click Save.

Add bot capability

After the app is created, you will be redirected to the Add App Capability page:

1. Find the Bot option and click Add Bot.
2. Fill in the bot's basic information:
   • Bot name: A name for the bot
   • Bot description: Brief description
   • Preview image: Upload a bot avatar
3. Click Confirm Publish.

Step 2: Configure App Permissions

To allow the bot to send and receive messages, enable the following permissions:

1. In the left sidebar of the app details page, click Permission Management.
2. Search for each of the following permissions and click Enable Now:
   • Card.Streaming.Write
   • Card.Instance.Write
   • qyapi_robot_sendmsg

Step 3: Get App Credentials

App ID and App Secret

1. In the left sidebar, click Credentials & Basic Info.
2. Find the following two credentials:
   • Client ID (also called AppKey)
   • Client Secret (also called AppSecret)

Important: These credentials are critical. Keep them secure and do not share them.

AES Key and Token

In the left sidebar, click Development Configuration → Event Subscription. Under Push Method, select HTTP Push. Click the refresh button to auto-generate your AES Key and Token.

Important: Keep your AES Key and Token secure.

Step 4: Configure DingTalk in Tencent WorkBuddy

Fill in credentials

Open Tencent WorkBuddy, click your avatar in the bottom-left corner, and go to Settings → Claw Settings. Find DingTalk Integration.

Enter the Client ID and Client Secret in the corresponding fields.

Two connection modes are available:

• WebSocket Long Connection — Recommended for personal/home/office users without a public IP. Simpler to configure, no public address required.
• URL Callback — For users with a server and public IP. Requires entering the generated Webhook URL back into the DingTalk developer console.

Register

• WebSocket Long Connection: Click Register. When connected successfully, the status will show Connected.
• URL Callback: Click Register to generate a Webhook URL. The status will show Registered — copy and save the URL.

If you selected URL Callback, you also need to configure the message receive address in DingTalk:

1. Go to the bot configuration page in the DingTalk developer console.
2. Scroll to the bottom and find the message receive configuration.
3. Switch Stream Mode to HTTP Mode.
4. Paste the Webhook URL into the Message Receive Address field.
5. Important: Change http to https in the URL.
6. Click Publish to save the configuration.

Step 5: Publish the App

The app must be published before it can be used in DingTalk.

Create a version

1. Click View Version Details at the top of the app page.
2. Fill in the version description.

Submit for publishing

1. Click Confirm Publish to submit for review.
2. Wait for approval (usually auto-approved quickly).

Step 6: Start Using

DingTalk bots support two usage modes: group chat and direct message.

Use in a group chat

Step 1: Create or select a group chat.

When creating a group, make sure the Affiliated Organization matches the organization used when creating the bot.

Step 2: Add the bot to the group.

1. Click the settings button in the top-right corner of the group.
2. Select Bots.
3. Click Add Bot.
4. Search for and select the bot you created.
5. Confirm to add.

Step 3: Start using.

In the group, @mention the bot and send your request. Tencent WorkBuddy will execute the task and reply with the results.

Use in a direct message

1. In the DingTalk search bar, search for the bot's name.
2. Click the bot to open a chat window and send messages directly.

Congratulations! You have successfully connected Tencent WorkBuddy to DingTalk. You can now remotely control Tencent WorkBuddy from DingTalk anytime, anywhere.

---

Troubleshooting

Bot not responding

1. Check app status: Confirm the app has been published and approved.
2. Check Webhook: Verify the URL is correct and uses https.
3. Check Tencent WorkBuddy: Make sure Tencent WorkBuddy is running and the Claw service is active.
4. Check permissions: Confirm all three permissions have been enabled.

Can't find the bot in a group

1. Confirm the bot app has been published.
2. Confirm the group's Affiliated Organization matches the bot's organization.
3. Try restarting the DingTalk client.