Configure Personal Messages via DingTalk

This topic describes how to configure DingTalk personal message delivery in NineData so that users can receive message notifications at key workflow stages.

Overview

NineData supports configuring personal notification channels for individual users. With Personal Channel Management, you can:

• Bind a dedicated DingTalk channel for a specific member.
• Receive more timely notifications without affecting the default subscription settings.
• Enable or disable personal-channel notifications for specific subscription types and workflow nodes.

Prerequisites

• You have created or joined an organization, and this organization has subscribed to either DevOps Pro or DevOps Enterprise. Please ensure that your annual or monthly subscription is still active. For more information, please refer to Manage Organizations.
• Your current account has switched to the target organization. For more information, please refer to Switching to an Organization.

• You are logged in to DingTalk Developer Platform with enterprise admin or app admin permissions.
• A target internal app is already prepared. If you need to create a new app, use only Chinese characters, uppercase or lowercase English letters, and Arabic numerals in the app name. Avoid spaces and special characters.
• You are logged in to the NineData console as a system administrator.

Notes

• This guide uses an internal DingTalk app and matches receivers in NineData by Phone.
• To send a custom DingTalk card message, create and publish a message card template in DingTalk Card Platform first. The template must contain the title, markdown, and msgUrl variables. Then copy the template ID to NineData.
• If Template ID is left empty, NineData sends the DingTalk message in the default format. To keep a consistent custom card style, enter a published template ID.
• Make sure that the target receiver is within the app visibility scope.

Procedure

Step 1: Prepare DingTalk App Credentials

1. Sign in to DingTalk Developer Platform and open the target app.

2. Go to Credentials & Basic Info, and record the following values:

   • Client ID (used as AppKey in NineData)
   • Client Secret (used as AppSecret in NineData)

   

3. Go to Robot and turn on Robot Configuration. If Robot is not displayed in the left navigation pane, click Add App Capability first and add the Robot capability.

   

   After you turn on robot configuration, you can use the app name and app icon as the robot name and icon, and complete the robot introduction, robot description, and other required fields.

   

4. Go to Permission Management and configure the address book API authorization scope. Select All Employees or Some Employees as needed. If you select Some Employees, make sure the test receiver is included in the authorization scope.

5. Make sure the following permissions are enabled. snsapi_base and qyapi_base are usually enabled by default. qyapi_get_member_by_mobile, qyapi_robot_sendmsg, and Card.Instance.Write do not require approval. If any of them is not enabled, click Enable Now in DingTalk Developer Platform.

   Permission	Permission code	Purpose
   Basic permission required for SNS API calls	snsapi_base	Used for basic SNS APIs such as creating shortcuts and querying personal authorization records.
   Obtain member basic information by phone number	qyapi_get_member_by_mobile	Used to query and match DingTalk members by the receiver's phone number.
   Basic permission required for enterprise API calls	qyapi_base	Used for basic enterprise API calls such as obtaining Access Token and generating jsapi ticket.
   Enterprise internal robot message sending permission	qyapi_robot_sendmsg	Used for sending normal robot messages in one-to-one conversations, and for querying, recalling, or downloading robot messages.
   Interactive card instance write permission	Card.Instance.Write	Used for creating, updating, closing, and delivering interactive cards.

   

   

Step 2: Create a DingTalk Card Template and Copy the Template ID (Optional)

DingTalk does not support creating a card and returning the template or card ID directly through an API. If you need to fill Template ID in NineData, create the message card template manually in DingTalk Card Platform first.

1. Sign in to DingTalk Developer Platform and open Card Platform. You can also go to Open Capabilities > Card Platform from the developer platform home page.

2. In Template Management, click New Template and create a blank template. Enter the Template Name, select Message Card, select Standard Card in Card Template Scenario, associate the DingTalk app prepared in Step 1, and click Create.

   

3. In the card editor, click Variables on the left, choose Add > Add Regular Variable, and create the following regular text variables:

   Card Content	Suggested Component	Variable Name
   Card title	Card header or title text	title
   Message body	Rich text or Markdown content	markdown
   Redirect URL	Single button	msgUrl

   

4. Add card elements from the component library as needed, and bind the title, body, redirect button, and other content to the variables above. The button text can be customized. We recommend setting the button display condition to show the button only when msgUrl is not empty, and binding the button URL to msgUrl.

5. Click Save, and then click Test Card. After you confirm in the dialog, DingTalk sends a test card to DingTalk Card Assistant by using the saved template.

   

6. After the test passes, click Publish. Confirm the operation and wait until the page displays Template Published Successfully.

   

7. After publishing the template, copy the Template ID in the upper-left corner of the page. The copied value usually ends with .schema. Enter this value in Template ID in NineData.

   

Step 3: Bind the DingTalk App in NineData

1. Log in to the NineData Console.

2. Go to Notification > Subscription, and then click the Channel Management tab.

3. On this tab, locate the Dingtalk personal channel card, click Configure, and open the Configure Ding Ding Message Channels dialog. Complete the fields and click OK.

   Parameter	Description
   AppKey	Enter the Client ID recorded in Step 1.
   AppSecret	Enter the Client Secret recorded in Step 1.
   Template ID	Optional. If you use a custom DingTalk card, enter the template ID copied in Step 2. If you do not use a custom card, leave it empty.
   Source Column	The current UI supports Phone.
   Receiver Info	Enter the DingTalk member's Phone and click Test Message Sending to validate delivery.

4. Click Test Message Sending and confirm that the page displays Successful.

   

Step 4: Enable the Personal Channel in Subscription Management

1. Log in to the NineData Console.

2. Go to Notification > Subscription.
3. On the Subscription tab, locate the target subscription type and select the checkbox in the Personal Channel column. For more information, see Subscription Management.

Result

After the configuration is complete, target users with the personal channel enabled can receive notifications in DingTalk when the workflow reaches the subscribed notification node.