钉钉机器人发送卡片消息的按钮如何添加

文章导读
群里有人问钉钉机器人发的卡片为什么没有按钮,或者按钮点了没反应。我处理这类问题一般先不急着改代码,而是先确认机器人是哪一种接入方式,因为两种方式能做的事不一样,后面排查的方向也不同。
📋 目录
  1. A 先确认你用的是哪种机器人
  2. B 容易误判的两个地方
  3. C 建议的处理顺序
  4. D 验证方法和边界条件
  5. E 后续维护注意几点
A A

群里有人问钉钉机器人发的卡片为什么没有按钮,或者按钮点了没反应。我处理这类问题一般先不急着改代码,而是先确认机器人是哪一种接入方式,因为两种方式能做的事不一样,后面排查的方向也不同。

先确认你用的是哪种机器人

首先明确当前机器人类型。钉钉机器人有两种常用接入方式:自定义机器人使用Webhook地址,仅支持actionCard等基础卡片;企业内部机器人使用应用凭证和Stream/HTTP回调,可发送interactive交互卡片。如果只是给群聊添加一个带按钮的消息,优先使用自定义机器人的actionCard;如果需要按钮点击后回调后端或打开复杂侧边栏,建议改用企业内部机器人。判断时查看机器人创建方式,若在群聊中通过“自定义”生成的即为Webhook。

这里有个容易忽略的点:自定义机器人虽然也叫“机器人”,但本质上只是一个Webhook入口,没有回调能力。按钮只能做跳转,不能把点击事件传回你的服务器。如果产品需求里写了“点击按钮后同步状态到我们的系统”,那自定义机器人这条路基本走不通,别在actionCard上硬抠,早点切到企业内部机器人更稳妥。

容易误判的两个地方

不少开发者把按钮放在markdown消息中,结果发现不生效。因为自定义机器人的markdown类型不支持按钮,只有actionCard类型才支持。另一个误区是actionURL填写相对路径或javascript:伪协议,钉钉会拒绝或无法点击。务必使用完整的http或https链接。

钉钉机器人发送卡片消息的按钮如何添加

这两种错误我在实际看代码时经常碰到。第一种是把消息里的text字段写得很丰富,但msgtype始终是markdown,按钮字段被钉钉直接忽略;第二种是直接把前端路由的相对路径写了进去,比如/detail?id=123,钉钉客户端拿到后不知道往哪里跳。这两种情况都不报错,消息能发送成功,但就是没有按钮或者点了没反应,特别容易让人误以为是权限问题。

建议的处理顺序

确认是自定义机器人后,建议按下面这个顺序处理。先构造一条actionCard消息,发送到Webhook地址,确认按钮能显示;再调整按钮跳转链接和排列方式;最后才考虑加签、限流这些边界因素。不要一上来就同时改消息格式、加安全设置、调样式,出了问题很难定位。

对于自定义机器人,构造actionCard时,msgtype设为actionCard,text字段填写卡片正文,title设置标题,btnOrientation设为0或1控制按钮排列方向。关键在btns数组,每个元素包含title和actionURL。示例中定义两个按钮,一个“查看详情”跳转到指定网页,一个“忽略”设置为空串。发送JSON到Webhook地址,钉钉即可在群中渲染带按钮的卡片。注意检查按钮数量和标题长度,建议控制在合理范围内。

{
  "msgtype": "actionCard",
  "actionCard": {
    "title": "线上告警",
    "text": "支付服务响应时间超过阈值,请及时处理。",
    "btnOrientation": "0",
    "btns": [
      {
        "title": "查看详情",
        "actionURL": "https://example.com/alert/detail?id=123"
      },
      {
        "title": "忽略",
        "actionURL": ""
      }
    ]
  }
}

btnOrientation填0表示按钮竖向排列,填1表示横向排列。按钮较多时建议用竖向,避免手机端被挤到屏幕外面。title字段在actionCard里主要作用是客户端通知栏展示,不一定显示在卡片正文上方,所以别把关键信息只放在title里。发送后先看Webhook返回的JSON结果,正常会返回errcode为0,如果不为0,优先排查JSON格式问题和字段名大小写。

钉钉机器人发送卡片消息的按钮如何添加

验证方法和边界条件

发送后若发现按钮没有显示或点击无反应,先到钉钉客户端查看消息详情,确认是否收到最新版本。再检查Webhook返回的JSON结果,正常会返回errcode为0。如果返回错误码,常见原因是JSON格式错误或字段名大小写不符,比如actionURL写成了actionUrl。此外,可在PC端和手机端分别查看,因为不同客户端对按钮美观度支持不同,但功能一致。若使用企业内部机器人,还需在开发者后台查看回调日志。

按钮点击跳转的URL必须对外可访问,钉钉客户端不会做二次代理,若目标网站有反爬或需要登录,可能无法打开。另外,自定义机器人对消息频率有限制,虽然具体阈值随组织调整,但不宜高频发送,否则可能被限流。企业内部机器人发送interactive卡片时,按钮的action可以设置为回调,但需要提前声明请求地址,并能够在3秒内返回响应,否则会有失败重试。这些边界条件应在设计时考虑。

验证按钮跳转时,建议在PC端和手机端分别点一次。PC端能打开不代表手机端没问题,部分内部系统在手机浏览器上会强制跳转登录页,点回来发现按钮又没了,这时候问题其实出在目标站点,不是钉钉侧。

钉钉机器人发送卡片消息的按钮如何添加

后续维护注意几点

如果机器人启用了加签安全设置,发送时需要在请求头或参数中携带时间戳+密钥,否则请求会返回错误码。加签逻辑在本地先测通,再放到服务器定时任务里,避免时间戳和服务器时间偏差过大导致签名校验失败。另外,自定义机器人的Webhook地址如果泄露,可以在群设置里重置,重置后旧地址立即失效,线上脚本要同步更新。

再补一个排查习惯:把Webhook返回的完整响应体打印到日志里,不要只打印errcode。有时候errcode为0但消息实际没渲染成功,响应体里会有其他提示字段,能帮你少走弯路。企业内部机器人则要在开发者后台看回调日志,确认钉钉是否真的把按钮事件推送到了你的服务器。

最后说下维护频率的问题。消息模板一旦固定下来,尽量少改动,每次改动都要回归测试两种场景:按钮能否正常显示,点击后能否正常跳转。如果后续要增加按钮数量,先确认当前机器人类型是否支持,别在actionCard里塞超过5个按钮,钉钉端渲染效果会变差。如果需求开始涉及表单提交或多步交互,可以从actionCard迁移到企业内部机器人的interactive卡片,再配合回调接口实现更完整的交互链路。