Skip to main content
Plan requirement: Every plan can create IM applications for AI SRE conversations. Using an application for On-call notifications requires an active On-call Professional subscription. Learn more
This documentation uses the new version of Dingtalk Open Platform as an example.

Create the Dingtalk app

  1. In Flashduty, create a new Dingtalk integration. Dingtalk app authorization defaults to Create a DingTalk app by scanning (recommended).
  2. Click Save, scan the QR code that appears with Dingtalk, and select the organization to create the app in (you must be an administrator or developer of that organization).
After you confirm the scan, Flashduty automatically:
  • Creates the Dingtalk app, named Flashduty by default
  • Obtains the AgentId, Client ID, and Client Secret
  • Enables the bot and sends the creator a welcome message
  • Generates the Encryption aes_key and Signature token used for event subscription; they are shown only once, in the dialog that opens when creation finishes, so copy them there
Dingtalk doesn’t allow the bot avatar to be set automatically. Change it manually in step 3 below.

Option 2: Existing app, enter credentials

  1. Visit Dingtalk Developer Console → App Development → Enterprise Internal Development and create an app. You can use the Flashduty official icon as the app icon. See Create Enterprise Internal App - H5 Mini App in the Dingtalk documentation. Dingtalk: Create Custom App screenshot
  2. Click the enterprise avatar in the top right corner and copy CorpId from the dropdown menu. Dingtalk: Copy Enterprise CorpId screenshot
  3. On the app details page, go to App Capabilities → Credentials & Basic Info in the left menu and copy AgentId, Client ID, and Client Secret. Dingtalk: Copy App Credential Information screenshot
  4. Return to the Flashduty Dingtalk integration page, fill in CorpId, AgentId, Client ID, and Client Secret, and click Save.
Flashduty generates the Encryption aes_key and Signature token for event subscription. You don’t need to generate them in Dingtalk. They are shown only once, in the form before you save, so copy them before saving. After either option, follow the 6 steps in the next section, “Finish setup in Dingtalk”. The step numbers on the integration detail page match that section.

Finish setup in Dingtalk

1. Grant permissions

Go to Development Configuration → Permission Management and request the permissions in the table below. Basic notifications need only the Basic group; War Room adds the second group (qyapi_get_member_by_mobile is also used for automatic member linking and one-click user linking); streaming AI SRE task progress and reply cards add the third. The integration detail page shows the status of each permission and links straight to each one.
If AICard.Instance.Write is not granted, AI SRE automatically falls back to standard interactive cards or session-webhook bot replies without affecting existing alerts or Q&A. Keep qyapi_robot_sendmsg granted in that mode.
Dingtalk: Request App Permissions screenshot

2. Configure event subscription

Go to Development Configuration → Event Subscription, set the push method to HTTP Push, then enter the Request URL shown in step 2 of the integration detail page, and the Encryption aes_key and Signature token you copied at creation. Click Save. For security, the Encryption aes_key and Signature token are not shown again after they are saved. If you did not keep them, click Generate and show in step 2 of the integration detail page. After you confirm, the old values stop working immediately, so enter the new ones here and in the group bot Message Callback Token. The new values are shown only once, so copy them first.
Dingtalk verifies the request URL as soon as you save, so save the Dingtalk integration in Flashduty first.
Dingtalk: Configure Event Subscription screenshot Below the Save button, select these three group chat events: Group chat name changed, Cool app installed in group, and Cool app uninstalled from group, then click Save. Dingtalk: Configure Event Subscription screenshot

3. Configure the robot

Go to App Capabilities → Bot, switch Message Receiving Mode from Stream to HTTP, and set Message Receiving URL to the address shown in step 3 of the integration detail page. Upload the bot icon (you can use the Flashduty official icon) and click Save. Dingtalk: Configure Bot and Message Push screenshot

4. Add a web app

Go to App Capabilities → Add App Capabilities → Web App, fill in App Homepage URL and PC Homepage URL using the addresses shown on the integration detail page, and click Save.
Filling in homepage URLs only under the legacy Development Management page is not enough. You must add the Web App capability and publish a version before the app appears in the Available Apps list of the scene group template used by War Room.
Dingtalk: Configure App URLs screenshot

5. Create a Cool App

Go to Development Configuration → Add App Capabilities → Cool Apps → Cool Apps List, click Create Cool App, and select Extend to Group Chat. On the Edit Cool App page, complete the following steps:
  1. Fill in basic information. You can use the Flashduty official icon as the icon. Dingtalk: Add App Capabilities screenshot
  2. Configure feature design. Select Group Shortcut Entry and Message Card on the left. You can use the Flashduty official icon for the group shortcut icon; set both the desktop and mobile access URLs to the address shown in step 5 of the integration detail page. Dingtalk: Add App Capabilities screenshot
  3. Skip step three (Feature Development), proceed to step four Preview & Publish, click Publish and confirm.

6. Set visibility and publish

Go to App Publishing → Version Management & Publishing, set the app Visibility to all employees, then create a new version and publish it. Changes from step 1 and steps 3–5 take effect only after publishing; publish again after any later permission or app configuration change. Dingtalk: App Publishing and Usage screenshot After publishing, you can access the app on Mobile or Desktop the same way: Dingtalk → Workspace → search the app name → Open App. First access requires login to link Dingtalk and Flashduty accounts; subsequent access is passwordless.
Optional: server egress IP. Go to Development Management → Server Egress IP and enter the IPs shown on the integration detail page to restrict which IPs can use the app credentials. This isn’t required.

Configure war room

If you don’t need War Room functionality, skip this section.
To configure War Room, first complete 6. Set visibility and publish and 4. Add a web app in “Finish setup in Dingtalk”. After the app is published, you can select it from the Available Apps list of a scene group template.

1. Request app permissions

In step 1 of Finish setup in Dingtalk, also grant qyapi_chat_read and qyapi_chat_base_read in addition to the basic permissions (see Required permissions for what each is for). Skip this if already granted. Dingtalk: Request App Permissions screenshot

2. Configure group template

Navigate to Open Capabilities → Scene Groups from the Dingtalk Open Platform top menu bar.
  1. Configure Group Bot. Select Bot in the left menu, then click Create Group Bot.
    The Group Bot here is different from the App Bot above: it joins war room group chats automatically when they are created, and it has a different Bot ID. War Room requires this additional Group Bot.
    Fill in the group bot configuration. If you need AI SRE, configure Message Callback URL, Message Callback Token, and Source Website as shown below. These fields are used for AI SRE Dingtalk message callbacks.
    Dingtalk’s certificate validation doesn’t accept the ACME certificate on api.flashcat.cloud, so the message callback URL must use the dingtalk-message.flashcat.cloud domain instead (see the table).
    The bot name, avatar, description, and similar descriptive fields can be anything; for the avatar you can use the Flashduty official icon. After configuration, click Create, then click Approve. After “Submission successful” appears in the top right corner, Dingtalk has automatically approved the group bot. Dingtalk: Configure Group Template screenshot
  2. Configure Group Template. Select Group Template in the left menu, click Create Group Template. Set Enterprise Type to Internal, and set Available Apps to the published custom app (steps 4. Add a web app and 6. Set visibility and publish must be done first). Then fill in template information in the next step. Template name, icon, description, and other descriptive information don’t affect group template functionality; use any values you like (for example, template name Flashduty War Room). In Select Bot configuration, click Select Created Bot, select the group bot created in the previous step. Keep other configurations as default. Finally click Save Edit. Dingtalk: Configure Group Template screenshot Dingtalk: Configure Group Template screenshot In the Fill in Gray Group step, click Create Gray Group, then click Publish Gray. Finally, click Group Template in the left menu again, then click to enter the group template just created. Click Submit for Review, after Dingtalk automatically approves, finally click Publish.
  3. On the published group template details page, copy Template ID and Bot ID. Dingtalk: Configure Group Template screenshot Return to Flashduty On-call integration configuration page, fill in the corresponding Template ID and Bot ID, click Save.
Only one IM integration can have War Room enabled at a time; turn it off in the other integration first. See War Room.

AI SRE controls

Configure the AI SRE switches under Enhanced Features. They are enabled by default; see IM platform for what each one does.

Linked users

In the Linked Users tab of the integration detail page, filter members by All / Linked / Unlinked, or search by name or email. Click One-Click Link to match members to Dingtalk accounts by their phone number and link them automatically, the same result as a member logging into Flashduty from Dingtalk. Members receive Dingtalk notifications only after they are linked. If linking fails, verify that the member’s phone number matches their Dingtalk account.

Automatic linking

Members do not need to do anything: the system links them automatically, once right after you save the integration and then once an hour across every enabled Dingtalk integration. Automatic linking resolves each member’s verified phone number in the personal center to a Dingtalk account ID (Dingtalk has no lookup by email), equivalent to the member logging into Flashduty with the same phone number on Dingtalk. Two limits delay retries:
  • A member Dingtalk answered for but no binding was created (the phone number is unknown on the Dingtalk side, or that Dingtalk account is already linked to another member) is not looked up again for 7 days; changing the member’s phone number triggers a new attempt
  • When the Dingtalk app lacks the qyapi_get_member_by_mobile permission (error code 60011) or the server IP is outside the app’s whitelist (error code 60020), automatic linking pauses for that integration for 24 hours; fix the permission or whitelist and save the integration again to resume
One-Click Link ignores the 7-day window above and looks everyone up again right away; if it reports No new members linked, this run produced no new binding (for example the phone number is unknown on the Dingtalk side, or the matching Dingtalk account is already linked to another member).

FAQ

Go to Dingtalk → Workspace → Search app name → Open App, and sign in once to link your Dingtalk and Flashduty accounts. Flashduty needs this identity to deliver messages.If the member has already verified a phone number in the personal center, the system may have linked the account automatically, without any sign-in; check the current linking status in the Linked Users tab of the integration detail page.
  • Go to Dingtalk → Workspace → Search app name → Open App, complete one login to link Dingtalk and Flashduty accounts. If already logged in, try clicking the top-right menu, switch accounts, and re-login to link the account
  • Ensure you’ve purchased sufficient Licenses. View License usage in Console → Billing Center
  1. Go to Dingtalk, install the Cool App in the target group chat, otherwise the group chat list cannot be obtained Dingtalk: Escalation rule Dingtalk group chat list is empty? screenshot Dingtalk: Escalation rule Dingtalk group chat list is empty? screenshot
  2. Return to escalation rule configuration page, refresh and reselect the group chat list
  3. If still unable to get the group chat list, try uninstalling the Cool App from the group and retry the above steps. If the issue persists, contact customer support or your dedicated technical support
After exceeding API call limits, Dingtalk app cannot deliver messages properly. Use notification channels reasonably. See Dingtalk official documentation.