跳转到主要内容
版本要求:所有版本均可创建 IM 应用用于 AI SRE 对话;将应用用于 On-call 分派通知,需有效的 On-call 专业版订阅。了解更多
本文档以钉钉开放平台新版为例。

创建钉钉应用

方式一:扫码创建(推荐)

  1. 在 Flashduty 新建钉钉集成,钉钉应用授权 默认为 扫码创建钉钉应用(推荐)。
  2. 点击 保存,使用钉钉扫描弹出的二维码,并选择要创建应用的组织(需要是该组织的管理员或开发者)。
扫码确认后,Flashduty 会自动完成以下操作:
  • 创建钉钉应用,默认名称为 Flashduty
  • 获取 AgentId、Client ID 和 Client Secret
  • 开启机器人,并向创建者发送一条欢迎消息
  • 生成事件订阅所需的 加密 aes_key 和 签名 token,只在创建完成的弹窗里显示一次,请先复制
钉钉不支持自动设置机器人头像,请在下文步骤 3中手动更换。

方式二:已有应用,填写凭证

  1. 访问 钉钉开发者后台 → 应用开发 → 企业内部开发,创建应用,图标可使用 Flashduty 官方 icon。详见钉钉开发文档 创建企业内部应用-H5 微应用。 钉钉:创建自建应用 界面截图
  2. 点击页面右上角企业头像,在下拉菜单中复制 CorpId。 钉钉:复制企业 CorpId 界面截图
  3. 进入应用详情,通过左侧菜单栏前往 应用能力 → 凭证与基础信息 页面,复制 AgentId、Client ID 和 Client Secret。 钉钉:复制应用凭证信息 界面截图
  4. 回到 Flashduty 钉钉集成配置页,在表单中填入 CorpId、AgentId、Client ID 和 Client Secret,点击 保存。
事件订阅用的 加密 aes_key 和 签名 token 由 Flashduty 生成,无需在钉钉中生成。它们只在保存前的表单里显示一次,请在保存前复制。 两种方式建好后,都按下一节「在钉钉完成配置」的 6 步操作;集成详情页的步骤编号与本节一致。

在钉钉完成配置

1. 开通权限

进入 开发配置 → 权限管理 页面,按需申请下表权限。基础通知只需要“基础”一组;开启作战室时再加第二组(qyapi_get_member_by_mobile 也用于自动关联成员);需要 AI SRE 实时流式展示任务清单与回复时再加第三组。集成详情页会显示各项权限的开通状态,并提供直达每项权限的链接。
如果未开通 AICard.Instance.Write,AI SRE 会自动降级使用普通版互动卡片或会话机器人消息回复,现有告警通知与问答功能不受影响,此时仍需要保留 qyapi_robot_sendmsg。
钉钉:申请应用权限 界面截图

2. 配置事件订阅

进入 开发配置 → 事件订阅 页面,设置推送方式为 HTTP推送,然后填入集成详情页第 2 步显示的 请求网址,以及创建时复制的 加密 aes_key 和 签名 token,点击 保存。 出于安全考虑,加密 aes_key 和 签名 token 保存后不再显示。没有记下的话,在集成详情页第 2 步点 生成并显示,确认后旧值立即失效,再把新值填到这里和群机器人的 消息回调 token。新值只显示一次,请先复制。
钉钉保存时会立即校验请求网址,因此需要先在 Flashduty 保存好钉钉集成。
钉钉:配置事件订阅 界面截图 在 保存 按钮下方,选中 群会话更换群名称、群内安装酷应用 和 群内卸载酷应用 三种群会话事件,点击 保存。 钉钉:配置事件订阅 界面截图

3. 配置机器人

进入 应用能力 → 机器人 页面,将 消息接收模式 从 Stream 切换为 HTTP,并将 消息接收地址 设置为集成详情页第 3 步显示的地址。上传机器人图标(可使用 Flashduty 官方 icon),点击 保存。 钉钉:配置机器人与消息推送 界面截图

4. 添加网页应用

进入 应用能力 → 添加应用能力 → 网页应用,根据集成详情页显示的地址填写 应用首页地址 和 PC 端首页地址,点击 保存。
只在旧版 开发管理 页面填写首页地址并不够,必须添加 网页应用 能力并发布版本后,该应用才会出现在作战室所用场景群模板的 可选应用 列表中。
钉钉:配置应用地址 界面截图

5. 创建酷应用

进入 开发配置 → 添加应用能力 → 酷应用 → 酷应用列表 页面,点击 创建酷应用,选择 扩展到群会话。 进入 编辑酷应用 页面,完成以下步骤:
  1. 填写基本信息。图标可使用 Flashduty 官方 icon。 钉钉:添加应用能力 界面截图
  2. 配置功能设计。在左侧选中 群快捷入口 和 消息卡片。群快捷入口图标可使用 Flashduty 官方 icon,桌面端和移动端访问地址都填集成详情页第 5 步显示的地址。 钉钉:添加应用能力 界面截图
  3. 跳过第三步功能开发,进入第四步 预览发布,点击 发布 按钮并确认。

6. 调整可见范围并发布

进入 应用发布 → 版本管理与发布,将应用 可见范围 设置为全部员工,创建新版本并发布。步骤 1 和步骤 3–5 的修改发布后才会生效;之后再调整应用权限或配置,也需要重新发布。 钉钉:应用发布与使用 界面截图 应用发布后,即可通过 手机端 或 PC 端 访问应用,入口相同:钉钉 → 工作台 → 搜索应用名称 → 打开应用。首次访问需要登录并关联钉钉与 Flashduty 账号,后续可以免登录使用。
可选:服务器出口 IP。进入 开发管理 → 服务器出口 IP,填入集成详情页显示的 IP,可限制只有这些 IP 能使用应用凭证。该项不是必需配置。

配置作战室

若您无需配置作战室功能,可跳过本节。
如果需要配置作战室,请先完成 在钉钉完成配置 中的 6. 调整可见范围并发布 和 4. 添加网页应用。应用发布后,才能在场景群模板的 可选应用 列表中选择该应用。

1. 申请应用权限

在 在钉钉完成配置 的步骤 1 中,除基础权限外,再开通 qyapi_chat_read 和 qyapi_chat_base_read(用途见所需权限)。若已开通,可跳过。 钉钉:申请应用权限 界面截图

2. 配置群模板

通过钉钉开放平台顶部菜单栏,前往 开放能力 → 场景群。
  1. 配置 群机器人。在左侧菜单栏中选择 机器人,然后点击 创建群机器人。
    这里的 群机器人 与上文的 应用机器人 不同,会在创建作战室群聊时自动加入群,二者的 机器人 ID 也不同。开启作战室必须额外配置群机器人。
    填写群机器人配置。若需要使用 AI SRE,请按下表配置 消息回调地址、消息回调 token 和 信息来源网站。这三项用于 AI SRE 的钉钉消息回调。
    钉钉的证书校验不兼容 api.flashcat.cloud 的 ACME 证书,因此消息回调地址需把域名换成 dingtalk-message.flashcat.cloud(见下表)。
    机器人名称、头像、简介等介绍性信息可任意填写,头像可使用 Flashduty 官方 icon。 完成配置后,点击 创建,然后点击 审批。右上角弹出 “提交成功” 后,钉钉已自动完成群机器人的审批。 钉钉:配置群模板 界面截图
  2. 配置 群模板。在左侧菜单栏中选择 群模板,点击 创建群模板。 将 企业类型 设置为 企业内部,将 可选应用 设置为已发布的自建应用(需已完成步骤 4 添加网页应用和步骤 6 发布)。然后,在下一步骤中填写模板信息。 模板名称、图标、描述等介绍性信息不影响群模板功能,可任意填写(例如模板名称 Flashduty 作战室)。 在 选择机器人 配置项中,点击 选择已创建的机器人,选择上一步骤中创建的群机器人。其他配置项保持默认。最后点击 保存编辑。 钉钉:配置群模板 界面截图 钉钉:配置群模板 界面截图 在 填写灰度群 步骤中,点击 创建灰度群,然后点击 发布灰度。 最后,再次点击左侧菜单栏的 群模板,然后点击进入刚才创建的群模板。点击 提交审核,待钉钉自动通过审核后,最后点击 发布。
  3. 在已经发布的群模板详细信息页,复制 模板 ID 和 机器人 ID。 钉钉:配置群模板 界面截图 回到 Flashduty On-call 集成配置页面,在表单中填入对应的 模版 ID 和 机器人 ID,点击 保存 按钮。
同一时间只能有一个 IM 集成开启作战室,需先在其他集成中关闭,详见 作战室。

AI SRE 控制项

在 增强功能 中配置 AI SRE 开关,默认均为开启,各开关含义见 IM 平台。

关联用户

在集成详情页的 关联用户 页签中,可按 全部 / 已关联 / 未关联 筛选成员,也可按名称或邮箱搜索。点击 一键关联,系统会用成员的手机号匹配钉钉账号并自动关联,效果等同于成员在钉钉中登录 Flashduty。 成员完成关联后,才能收到钉钉消息通知。关联失败时,请确认成员的手机号与钉钉账号一致。

自动关联

成员无需手动操作,系统会自动完成关联:保存集成后立即尝试一次,之后每小时再自动扫描一次,覆盖所有已启用的钉钉集成。 自动关联使用成员在个人中心已验证的手机号换取钉钉账号 ID(钉钉不支持按邮箱查询),效果等同于成员用同一手机号在钉钉登录 Flashduty。有两处限制会让重试延后:
  • 钉钉答复过、但没能建立绑定的成员(例如手机号在钉钉侧查不到,或该钉钉账号已经绑定到其他成员),7 天内不再重复尝试;成员的手机号发生变化时会重新尝试
  • 钉钉应用缺少 qyapi_get_member_by_mobile 权限(错误码 60011),或服务器 IP 不在应用白名单内(错误码 60020)时,该集成的自动关联暂停 24 小时;补齐权限或白名单后重新保存集成即可恢复
一键关联 会忽略上面的 7 天重试窗口,立即重新查询一次;如果提示 没有关联到新成员,说明本次查询没有产生新的绑定(例如手机号在钉钉侧查不到,或对应钉钉账号已经绑定到其他成员)。

常见问题

前往 钉钉 → 工作台 → 搜索应用名称 → 打开应用,完成一次登录以关联钉钉与 Flashduty 账号,系统才能获取用户身份并推送消息。如果成员在个人中心已经验证过手机号,系统也可能已经自动完成关联,无需成员登录;可在集成详情页的 关联用户 页签确认当前关联状态。
  • 前往 钉钉 → 工作台 → 搜索应用名称 → 打开应用,完成一次登录以关联钉钉与 Flashduty 账号。如果已经登录过,尝试点击右上角菜单,切换账户,重新登录来绑定账号
  • 确保您已购买足够的 License。已使用 License 情况,可以在 控制台 → 费用中心 查看
  1. 前往钉钉,选择群聊会话安装酷应用,否则无法获取群聊列表 钉钉:分派策略钉钉群聊列表为空? 界面截图 钉钉:分派策略钉钉群聊列表为空? 界面截图
  2. 回到分派策略配置页面,刷新后重新选择群聊列表
  3. 如果仍然无法获取群聊列表,请尝试在群内卸载酷应用后,重试以上步骤。如果问题依旧,请联系客服或专属技术支持
超出 API 调用量限制后,钉钉应用将无法正常推送消息。建议合理使用通知渠道。详见 钉钉官方文档。