钉钉机器人发卡片消息提示 invalid parameter 错误是什么原因？

出现 invalid parameter 通常是因为请求体中的 JSON 字段名称、类型或结构与钉钉接口定义不一致，针对卡片消息，最常见的原因是 actionCard 或 feedCard 内部结构缺失或字段错误。最推荐的处理方向是先用在线 JSON 校验工具检查报文格式，再对照官方文档核对 msgtype 与卡片内容字段是否匹配。

先说结论：该错误代表服务端无法解析或拒绝了你提交的参数，卡片消息多数情况是 btns 数组结构错误或 msgtype 与内容块不匹配。

先确认：HTTP 请求头 Content-Type 是否为 application/json
先处理：核对 msgtype 为 actionCard 时，是否包含完整的 actionCard 对象及 btns 数组
再验证：使用 curl 或 Postman 重发请求观察返回码

快速处理思路

这不是系统命令问题，而是接口调用问题。建议直接复制以下卡片消息最小可用模板，替换 webhook 和 content 后测试：

curl 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
   -d '{
     "msgtype": "actionCard",
     "actionCard": {
         "title": "测试卡片",
         "text": "## 测试内容 \n > 这是一条测试消息",
         "btnOrientation": "0",
         "btns": [
             {
                 "title": "查看详情",
                 "actionURL": "https://www.dingtalk.com"
             }
         ]
     }
   }'

为什么会这样

钉钉机器人接口会对接收到的 JSON 数据进行 schema 校验。当代码中构造的参数字段名大小写错误、缺少必填项、或者 msgtype 声明的类型与实际内容字段不符时，服务端无法映射到内部处理逻辑，就会返回 invalid parameter。对于卡片消息，如果 btns 数组格式错误、缺少 actionURL 或 title，也会触发此错误。此外，如果开启了安全设置但未传递签名或关键词不匹配，也可能触发参数无效的错误提示。

分步处理

1. 检查请求头：确保 HTTP Header 中包含 Content-Type: application/json，否则服务端可能无法识别 body 内容。

2. 核对 msgtype 与内容块：确认 JSON 根目录下的 msgtype 字段值（如 actionCard、feedCard）是否与下层对应的内容字段 key 一致。例如 msgtype 为 actionCard 时，必须包含 actionCard 对象。

3. 检查卡片特有字段：actionCard 必须包含 title、text、btns 等字段。btns 必须是对象数组，每个对象需包含 title 和 actionURL。

4. 检查安全设置：登录钉钉群机器人设置页面，查看是否开启了“自定义关键词”或“签名”。如果开启了签名，必须在请求参数中加入 timestamp 和 sign 字段，否则会被拦截。

怎么验证是否生效

发送请求后，观察 HTTP 响应状态码是否为 200，且响应 body 中包含 errcode: 0。同时查看钉钉群聊窗口，确认是否收到预期格式的消息卡片。如果仍然报错，查看返回的 errmsg 字段，通常会提供更具体的字段错误信息。

常见坑

1. 特殊字符未转义：content 或 text 内容中包含双引号、换行符时，必须在 JSON 中进行转义，否则会导致 JSON 解析失败。

2. 字段大小写敏感：所有参数字段名均为小写，例如 msgtype 不能写成 MsgType 或 msgType，actionURL 注意 URL 大写。

3. btns 结构错误：btns 必须是数组 []，内部元素是对象 {}，缺少 title 或 actionURL 都会导致 invalid parameter。

4. 内容长度限制：消息内容过长可能触发限制，虽然通常报错不同，但极端情况下也可能导致参数异常。

参考来源

钉钉开放平台 - 自定义机器人接入，URL: https://open.dingtalk.com/document/robots/custom-robot-access