更新已发送的消息卡片

通过消息 ID（message_id）更新已发送的消息卡片的内容。

前提条件

应用需要开启机器人能力。

使用场景

本接口适用于卡片发送后，对卡片无条件直接更新的场景。
如果你需要在用户与卡片进行交互后更新卡片，可参考处理卡片回调，选择在 3 秒内立即更新卡片、或 30 分钟内延时更新卡片的方式。
如果你需要仅更新部分成员接收到的卡片，你需调用延时更新消息卡片接口，指定用户的 open_id。

注意事项

调用该接口的身份（access_token）需与发送卡片的身份一致。
仅支持更新未撤回的卡片。
你需在更新前后卡片的 config 属性中，均显式声明 =="update_multi":true==（表示卡片为共享卡片，卡片的更新对所有接收的用户可见）。

使用限制

不支持更新批量发送的消息。
不支持更新仅特定人可见的卡片。
仅支持更新 14 天内发送的消息。
单条消息更新频控为 5 QPS。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/messages/:message_id
HTTP Method	PATCH
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求调用该 API 所需的权限。开启其中任意一项权限即可调用开启任一权限即可	`im:message` 获取与发送单聊、群组消息 `im:message:send_as_bot` 以应用的身份发消息 `im:message:update` 更新消息

请求头

名称	类型	必填	描述
Authorization	string	是	`tenant_access_token` 或 `user_access_token` 值格式："Bearer `access_token`" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
`message_id`	`string`	待更新的消息 ID，仅支持更新卡片（消息类型为 `interactive`）。ID 获取方式： - 调用发送消息接口后，从响应结果的 `message_id` 参数获取。 - 监听接收消息事件，当触发该事件后可以从事件体内获取消息的 `message_id`。 - 调用获取会话历史消息接口，从响应结果的 `message_id` 参数获取。示例值："om_dc13264520392913993dd051dba21dcf"

请求体

名称	类型	必填	描述
`content`	`string`	是	消息卡片的内容，支持卡片 JSON 或搭建工具构建的卡片，需为 JSON 结构序列化后的字符串。 - 要使用卡片 JSON，参考卡片 JSON 结构。 - 要使用搭建工具构建的卡片模板，参考下文请求体示例。注意： - 更新的卡片消息最大不能超过 30 KB。若消息中包含大量样式标签，会使实际消息体长度大于你输入的请求体长度。 - 以下示例值未转义，使用时请注意将其转为 JSON 序列化后的字符串。示例值："{"elements":[`{"tag":"div","text":{"content":"This is the plain text","tag":"plain_text"}`}],"header":`{"template":"blue","title":{"content":"This is the title","tag":"plain_text"}`}}"

请求体示例

json

{  // 使用卡片 JSON 示例
    "content": "{\"elements\":[{\"tag\":\"div\",\"text\":{\"content\":\"This is the plain text\",\"tag\":\"plain_text\"}}],\"header\":{\"template\":\"blue\",\"title\":{\"content\":\"This is the title\",\"tag\":\"plain_text\"}}}"
}

json

{  // 使用搭建工具构建的卡片模板示例
  "content": "{\"type\":\"template\",\"data\":{\"template_id\":\"AAqyjwfhabcef\",\"template_version_name\":\"1.0.0\"}}"
}

使用搭建工具构建的卡片模板时，参数说明如下所示：

参数	必填	说明
type	是	卡片类型。要发送由搭建工具搭建的卡片（也称卡片模板），固定取值为 `template`。
data	是	卡片模板的数据，要发送由搭建工具搭建的卡片，此处需传入卡片模板 ID、卡片版本号等。
└ template_id	是	搭建工具中创建的卡片（也称卡片模板）的 ID，如 `AAqigYkzabcef`。可在搭建工具中通过复制卡片模板 ID 获取。
└ template_version_name	否	搭建工具中创建的卡片的版本号，如 `1.0.0`。卡片发布后，将生成版本号。可在搭建工具版本管理处获取。注意：若不填此字段，将默认使用该卡片的最新版本。即在搭建工具发布卡片新版本后，该新版本的卡片内容将立即对卡片 API 调用生效。
└└ template_variable	否	若卡片绑定了变量，你需在该字段中传入实际变量数据的值。详情参考配置卡片变量。

响应

响应体

名称	类型	描述
`code`	`int`	错误码，非 0 表示失败
`msg`	`string`	错误描述
`data`	`\-`	-

响应体示例

json

{
    "code": 0,
    "data": {},
    "msg": "ok"
}

错误码

HTTP状态码	错误码	描述	排查建议
400	230001	Your request contains an invalid request parameter.	参数错误，请根据接口返回的错误信息并参考文档检查输入参数。
400	230006	Bot ability is not activated.	应用未启用机器人能力。启用方式参见如何启用机器人能力。
400	230011	The message is recalled.	消息已被撤回，不支持该操作。
400	230013	Bot has NO availability to this user.	目标用户（以用户的 user_id/open_id/union_id/email 指定的消息接收者）或单聊用户（以群聊的 chat_id 指定的消息接收者，但 chat_id 对应的群聊类型为单聊 `p2p`）不在应用机器人的可用范围内，或者是在应用的禁用范围内。注意：如果目标用户已离职，也会报错 230013。解决方案： 1. 登录开发者后台，找到并进入指定应用详情页。 2. 在左侧导航栏进入应用发布 > 版本管理与发布页面，点击创建版本。 3. 在版本详情页面，找到可用范围区域，点击编辑。 4. 在弹出的对话框内，配置应用的可用范围，将用户添加至可用范围内。 5. 在页面底部点击保存，并发布应用使配置生效。 6. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录管理后台，在工作台 > 应用管理中进入指定应用详情页，在应用可用范围内查看该用户是否被设置为了禁用成员。具体操作参见配置应用可用范围。
400	230020	This operation triggers the frequency limit.	当前操作触发限频，请降低请求频率后重试。
400	230025	The length of the message content reaches its limit.	消息体长度超出限制。文本消息最大不能超过 150 KB，卡片及富文本消息最大不能超过 30 KB。此外，若消息中包含大量样式标签，会使实际消息体长度大于你输入的请求体长度。
400	230027	Lack of necessary permissions.	无权进行本次操作。可能的原因有： 1. 缺少相应权限，可根据实际的错误信息进行排查。 2. 未检查到用户授权信息。 3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见机器人支持外部群和外部用户单聊。
400	230028	The messages do NOT pass the audit.	消息的数据防泄漏审查未通过。当消息内容包含有明文电话号码、明文邮箱地址等内容时可能会触发该错误。请根据接口返回的错误信息检查并修改消息内容。
400	230031	Message can only be modified within 14 days after sending.	在消息发送后的 14 天内允许更新消息内容，超过 14 天则无法更新。
400	230099	Failed to create card content.	创建卡片内容失败，请参考当前接口返回的具体报错信息，并参照接口文档中的子错误码排查建议解决。
400	230110	Action unavailable as the message has been deleted.	消息已删除，无法进行本操作。
400	232009	Your request specifies a chat which has already been dissolved.	群组已被解散，无法执行操作。

230099 子错误码

错误码	描述	排查建议
100290	Failed to create card content, ext=ErrCode: 100290; ErrMsg: There is an invalid user resource(at/person) in your card; ErrorValue: %v	卡片中存在无效的人员 id。请检查卡片中的 at 人、人员等组件中使用的用户 id 值是否正确，参考如何获取不同的用户 ID。 1. 打开 API 调试台，在左侧 API 目录中找到「通讯录」下的「通过手机号或邮箱获取用户 ID」，点击该 API 切换当前调试 API 为「通过手机号或邮箱获取用户 ID」。 2. 点击 API 调试台左侧查看鉴权凭证中 tenant_access_token 中的点击获取。 3. 点击右侧参数列表，将查询参数中的 user_id_type 参数设置为需要获取的 ID 类型。 4. 切换至请求体 Tab，将请求体中的示例 ID 删除，并修改为需要查询的手机号或 Email。 5. 点击右侧开始调试，调用成功后，在下方响应体中即可获取到查询的 User ID。响应体中返回的用户 ID 类型由查询参数中设置的 user_id_type 参数决定。
200380	Failed to create card content, ext=ErrCode: 200380; ErrMsg: template does not exist, please confirm whether this template has been released; ErrorValue: templateID: %v	未找到卡片。请确认当前模版卡片已保存并发布，参考预览与发布卡片。 1. 在飞书卡片搭建工具目标卡片编辑页面的右上角，点击保存，然后点击发布。 2. 在发布卡片对话框，设置卡片版本号，并点击发布。首次发布时版本号一般设置为 `1.0.0`。 3. 发布卡片后，你可参考发送由搭建工具构建的卡片调用 API 发送卡片。
note

卡片发布后，将对线上的卡片相关的 API 调用立即生效。你需确认本次发布是否会对服务端代码逻辑产生不兼容变更。为避免此类情况，在请求发送卡片时，你可将 `template_version_name` 参数设置为固定的卡片版本号，避免在工具上发布卡片后立即影响线上业务逻辑。
:::

200381 Failed to create card content, ext=ErrCode: 200381; ErrMsg: template is not visible to app, please confirm whether the app is allowed to use this template; ErrorValue: %v, templateID: %v

无卡片使用权限。请检查当前发送卡片的应用或自定义机器人是否具有该卡片的使用权限，参考管理卡片模板权限。

在卡片模板的编辑页面，点击应用图标。
在 添加自定义机器人/应用 弹窗中，添加应用或自定义机器人，使该应用或自定义机器人拥有调用该卡片模板的权限。

200621 Failed to create card content, ext=ErrCode: 200621; ErrMsg: parse card json err, please check whether the card json is correct; ErrorValue: %v 卡片 JSON 格式错误。请参考卡片 JSON 代码结构检查卡片内容。

200732 Failed to create card content, ext=ErrCode: 200732; ErrMsg: the actual type of the variable is inconsistent with the specified type in the template. Please check the type of the variable; ErrorValue: %v, specifiedType: %v, actualType: %v 卡片变量类型错误。请检查发送模版卡片时使用的变量的数据类型与构造该模版时指定的变量数据类型是否一致。

200550 Failed to create card content, ext=ErrCode: 200550; ErrPath: ROOT -> elements -> %v; ErrMsg: chart spec is invalid; ErrorValue: %v

卡片中的图表组件配置错误。请检查图表组件中的 chart_spec 属性配置是否正确，参考图表组件。

json

{
  "code": 230099,
  "msg": "Failed to create card content, ext=ErrCode: 200550; ErrPath: ROOT -> elements -> [2](tag: chart); ErrMsg: chart spec is invalid; ErrorValue: - (root): Must validate at least one schema (anyOf)\n- axes: Invalid type. Expected: array, given: null\n; ",
  "error": {
    "log_id": "202409131613579778D691D6E05516DE2D",
    "troubleshooter": "排查建议查看（Troubleshooting suggestions）： https://open.feishu.cn/search?from=openapi&log_id=202409131613579778D691D6E05516DE2D&code=230099&method_id=6921911482032898068"
  }
}

ErrPath 示例说明: ROOT -> elements -> [2](tag: chart)

200861 Failed to create card content, ext=ErrCode: 200861; ErrPath: ROOT -> body -> elements -> %v; ErrMsg: cards of schema V2 no longer support this capability; ErrorValue: unsupported tag %v 卡片中使用了schema 1 支持但 schema 2 不再支持的组件。请检查卡片内容，移除或替换不支持的标签，参考废弃组件说明文档。

200570 Failed to create card content, ext=ErrCode: 200570; ErrMsg: card contains invalid image keys; ErrorValue: image key %v 卡片中的图片资源无效。请检查卡片中是否使用了正确的 img_key，你可以调用上传图片接口或在搭建工具中上传图片，获取图片的 key。

200914 table rows is invalid

表格行无效。可能原因与排查方案：

表格的 rows 部分不是一个合法的 JSON，示例参考表格 JSON 结构。
单元格数据类型解析错误。例如，某列的单元格类型是富文本，但该列该行的数据按富文本解析失败。该场景下可根据返回的单元格行列索引（从 0 开始计数），定位问题单元格，然后参考表格中的 data_type 字段说明，检查是否配置有误。

其他未列出的错误码请参见服务端通用错误码。

更新已发送的消息卡片 ​

前提条件 ​

使用场景 ​

注意事项 ​

使用限制 ​

请求 ​

请求头 ​

路径参数 ​

请求体 ​

请求体示例 ​

响应 ​

响应体 ​

响应体示例 ​

错误码 ​

230099 子错误码 ​

更新已发送的消息卡片

前提条件

使用场景

注意事项

使用限制

请求

请求头

路径参数

请求体

请求体示例

响应

响应体

响应体示例

错误码

230099 子错误码