钉钉机器人发送 ActionCard 类型消息的具体配置参数有哪些

钉钉机器人发送 ActionCard 消息主要分整体跳转和独立跳转两种模式，具体参数取决于你使用的是自定义机器人 Webhook 还是企业内部应用 API，配置时需重点区分 msgtype 与 msgKey 的使用场景。

先说结论：ActionCard 消息配置核心在于区分机器人类型，自定义机器人直接使用 JSON body 参数，企业内部应用则需通过模板 key 调用。

适合：系统通知、告警推送、需要用户点击交互的场景
先看：确认机器人类型是自定义 Webhook 还是企业内部应用
建议：跳转链接必须使用 https 协议，发送前先在测试群验证

配置参数详解

ActionCard 消息的核心参数如下，自定义机器人与企业内部应用在字段命名上略有差异，请对照使用。

参数名	类型	必填	说明
msgtype	String	是	固定为 actionCard
title	String	是	卡片标题，建议控制在 20 字以内
text	String	是	卡片内容，支持 Markdown 格式，注意长度限制
singleTitle	String	否	整体跳转按钮文案，与 btns 互斥
singleURL	String	否	整体跳转链接，必须为 https 协议
btnOrientation	String	否	按钮排列方向，0 竖排，1 横排
btns	Array	否	独立跳转按钮数组，包含 title 和 actionURL

请求报文示例

核心在于构造正确的 HTTP POST 请求体，以下是具体 JSON 结构。

自定义机器人（Webhook）

{
    "msgtype": "actionCard",
    "actionCard": {
        "title": "任务通知",
        "text": "## 任务状态更新 \n - 任务 ID: 12345 \n - 状态：已完成",
        "singleTitle": "查看详情",
        "singleURL": "https://example.com/detail/12345"
    }
}

企业内部应用

企业内部应用需通过 msgKey 指定模板，msgParam 传递 JSON 字符串。

{
    "robotCode": "YOUR_ROBOT_CODE",
    "msgKey": "sampleActionCard",
    "msgParam": "{\"title\": \"任务通知\", \"text\": \"## 任务状态更新\", \"singleTitle\": \"查看详情\", \"singleURL\": \"https://example.com\"}",
    "openConversationId": "cid..."
}

验证与错误排查

发送请求后，直接观察钉钉群聊窗口是否收到卡片消息。点击卡片上的按钮，确认是否能正常跳转到预设链接。如果是企业内部应用，可通过接口返回的 errorCode 判断，成功通常返回 0 或 success 状态。

错误码	描述	解决方案
310000	Invalid Token	检查 Webhook 地址或 access_token 是否过期
310001	Frequency Limit	请求过于频繁，建议增加发送间隔
400	Param Error	检查 JSON 格式及必填字段，确保链接为 https

常见注意事项

跳转链接限制：ActionCard 中的跳转链接必须使用 https 协议，且域名需在企业管理后台配置白名单，否则无法跳转。
内容长度限制：注意 text 字段的内容长度限制（通常不超过 20KB），过长可能导致发送失败或被截断。
参数格式混淆：自定义机器人的 actionCard 是对象结构，而企业内部应用的 msgParam 往往是 JSON 字符串，两者容易弄混，导致解析失败。
按钮数量与布局：独立跳转模式支持多个按钮，但需注意 btnOrientation 参数控制横排或竖排，配置错误会导致样式展示异常。
权限问题：企业内部应用机器人发送消息需要相应的权限配置，如企业内机器人发送消息权限，未授权会导致接口调用被拒。