DingTalk
This document describes how to create a DingTalk enterprise internal app bot that receives one-on-one text messages or messages that @ the bot in enterprise internal groups over HTTP, invokes the Agent in Tencent Cloud EdgeOne Makers, and returns the result to the original conversation.
Prerequisites and Scope of Application
1. You already have a DingTalk organization and account with permissions to create, manage, and publish enterprise internal apps.
2. The organization meets DingTalk's authentication and publishing requirements.
3. Makers has been activated.
4. This document covers text mentions in one-on-one chats and internal enterprise group chats within the organization. It does not cover external groups, third-party enterprise apps, or interactive cards.
Creating an Application and Configuring a Bot
1. Log in to the DingTalk Developer Console and select the target organization.
2. Go to App Development > DingTalk Apps, create an enterprise internal app, and enter the app name, description, and icon.
3. In the app details, go to App Capability > Add App Capability and add Bot.
4. Go to App Capability > Bot, enable the bot configuration, and enter the bot name, icon, introduction, description, and message preview image.
5. Go to Basic Info > Credentials & Basic Info and copy the Client ID and Client Secret.
6. Copy the bot code robotCode in the bot configuration.
The preceding steps will yield the following credentials:
Credential | Corresponding Value in Template | Purpose |
Client ID | AppKey | Identify internal enterprise applications |
Client Secret | AppSecret | Verify HTTP message signatures and obtain API access credentials. |
robotCode | Robot Code | Specify the application bot for sending messages. |
Configuring Sending Permissions
1. Go to Permission Management in the app, search for and enable the Bot Message Sending Permission in Enterprise.
2. If the organization requires approval, complete the approval.
3. Verify that the APIs available to the app include bot one-on-one chat sending and group chat sending.
Function | Required Configuration |
Receive user messages. | Enable the application bot, select HTTP mode, and set the message receiving address. |
Reply using `sessionWebhook`. | Use the address carried in the current valid message event, which is automatically processed by the template. |
OpenAPI single or group chat reply | Enable the permission for the in-enterprise bot to send messages, ensure the application is published, and ensure the bot can access the target conversation. |
Deploying the Makers Template
1. Open the Makers Agent for IM template.
2. In the project environment variable settings, fill in the following variables (copy .env.example to .env).
Environment Variable | Required | Description |
DINGTALK_APP_KEY | Yes | Client ID |
DINGTALK_APP_SECRET | Yes | Client Secret |
DINGTALK_ROBOT_CODE | Yes | robotCode |
3. Save the configuration and deploy it.
4. Copy the production HTTPS domain name, and append /dingtalk to the end.
5. Note that the service should be deployed in a mainland China AZ so that DingTalk services can be accessed correctly.
Configuring the HTTP Message Receiving Address
1. Return to App Capability > Bot in the DingTalk app.
2. Set Message Receiving Mode to HTTP mode.
3. In Message Receiving Address, enter the full URL from step 3.
4. Click Publish to save the bot configuration.
Publishing an Application and Adding a Bot
1. Go to App Publishing > Version Management and Release, and click Create New Version.
2. Enter the version number and version description, and select Bot in Content to Publish.
3. In App Visible Range, select test members or departments.
4. Click Save > Publish Directly. If your organization requires review, wait for the review to complete and confirm that the version has been published.
5. Open the test internal group in the DingTalk client, go to Group Settings > Group Management > Bot, click Add Bot, and select the current bot to add it.
Sending a Message and Verifying It
1. In the test group, enter `@`, select the current bot from the candidate list, and send `Please introduce Tencent Cloud EdgeOne Makers in one sentence.`.
2. Wait for the Agent to finish, and confirm that the original group receives a new Markdown reply.
3. @ the bot again and send `Please shorten the previous answer to no more than ten words.` to verify the second-round reply.
4. To test single chats, use a member account within the visible range to open a single chat window with the bot and send the same question. You do not need to @ the bot in single chats.
