This documentation uses the new version of Dingtalk Open Platform as an example.
Create the Dingtalk app
Option 1: Create by QR code (recommended)
- In Flashduty, create a new Dingtalk integration. Dingtalk app authorization defaults to Create a DingTalk app by scanning (recommended).
- 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).
- Creates the Dingtalk app, named Flashduty by default
- Obtains the
AgentId,Client ID, andClient Secret - Enables the bot and sends the creator a welcome message
- Generates the
Encryption aes_keyandSignature tokenused 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
-
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.
-
Click the enterprise avatar in the top right corner and copy
CorpIdfrom the dropdown menu.
-
On the app details page, go to App Capabilities → Credentials & Basic Info in the left menu and copy
AgentId,Client ID, andClient Secret.
-
Return to the Flashduty Dingtalk integration page, fill in
CorpId,AgentId,Client ID, andClient Secret, and click Save.
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.
2. Configure event subscription
Go to Development Configuration → Event Subscription, set the push method toHTTP 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.
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.
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.
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.
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:-
Fill in basic information. You can use the Flashduty official icon as the icon.
-
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.
- 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.
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
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 grantqyapi_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.
2. Configure group template
Navigate to Open Capabilities → Scene Groups from the Dingtalk Open Platform top menu bar.-
Configure Group Bot. Select Bot in the left menu, then click Create 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.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.The bot name, avatar, description, and similar descriptive fields can be anything; for the avatar you can use the Flashduty official icon.Dingtalk’s certificate validation doesn’t accept the ACME certificate on
api.flashcat.cloud, so the message callback URL must use thedingtalk-message.flashcat.clouddomain instead (see the table).After configuration, click Create, then click Approve. After “Submission successful” appears in the top right corner, Dingtalk has automatically approved the group bot.
-
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 nameFlashduty 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.
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.
-
On the published group template details page, copy Template ID and Bot ID.
Return to Flashduty On-call integration configuration page, fill in the corresponding Template IDandBot ID, click Save.
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_mobilepermission (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
FAQ
Messages cannot be delivered to individuals, operation log shows 'App not linked'?
Messages cannot be delivered to individuals, operation log shows 'App not linked'?
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.
Escalation rule Dingtalk group chat list is empty?
Escalation rule Dingtalk group chat list is empty?
-
Go to Dingtalk, install the Cool App in the target group chat, otherwise the group chat list cannot be obtained
- Return to escalation rule configuration page, refresh and reselect the group chat list
- 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
Why isn't War Room working as expected?
Why isn't War Room working as expected?
- Check again if the app has been granted the required permissions for War Room functionality
- See the FAQ section in War Room documentation
Dingtalk custom app API call limits?
Dingtalk custom app API call limits?