合并转发消息

将来自同一个会话内的多条消息，合并转发给指定的用户、群聊或话题。

前提条件

• 应用需要开启机器人能力
• 向用户合并转发消息时，用户需要在机器人的可用范围内。
• 向群组合并转发消息，机器人需要在该群组中，且拥有发言权限。
• 合并转发生成的新消息的消息内容为固定值==Merged and Forwarded Message==，其中的子消息可以使用获取指定消息的内容接口获取。

使用限制

• 不支持合并转发系统消息（system）。
• 不支持合并转发来自不同群聊的消息。
• 不支持同时合并转发来自多个话题中的消息。
• 不支持同时合并转发普通消息与话题中的消息。
• 不支持再次合并转发 合并转发消息中的子消息（含有==upper_message_id==字段的消息）。
• 为避免消息发送频繁对用户造成打扰，向同一用户发送消息的限频为 ==5 QPS==、向同一群组发送消息的限频为群内机器人共享 ==5 QPS==。

请求

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

请求头

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

查询参数

名称	类型	必填	描述
receive_id_type	string	是	消息接收者 ID 类型。 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - email: 以用户的真实邮箱来标识用户。 - chat_id: 以群 ID 来标识群聊。了解更多：如何获取群 ID - thread_id: 以话题 ID 来标识话题。了解更多：话题介绍
uuid	string	否	自定义设置的唯一字符串序列，用于在合并转发消息时请求去重。持有相同 uuid 的请求，在 1 小时内向同一目标的合并转发只可成功一次。 示例值：b13g2t38-1jd2-458b-8djf-dtbca5104204 数据校验规则： - 最大长度：50 字符

请求体

名称	类型	必填	描述
receive_id	string	是	消息接收者 ID，ID 类型与 receive_id_type 的值一致。 示例值："oc_a0553eda9014c201e6969b478895c230"
message_id_list	string\[\]	是	待转发的消息 ID 列表，列表内的消息必须来自同一个会话。ID 获取方式： - 调用发送消息接口后，从响应结果的 message_id 参数获取。 - 监听接收消息事件，当触发该事件后可以从事件体内获取消息的 message_id。 - 调用获取会话历史消息接口，从响应结果的 message_id 参数获取。 示例值：["om_dc13264520392913993dd051dba21dcf"] 数据校验规则： - 长度范围：1 ～ 100

请求体示例

{
    "receive_id": "oc_a0553eda9014c201e6969b478895c230",
    "message_id_list": ["om_d862083dd13b61cc009e66c40a0f0a56","om_61244dab1ef11257621dcd7g0e256651"]
}

cURL请求示例

curl --location --request POST 'https://open.feishu.cn/open-apis/im/v1/messages/merge_forward?receive_id_type=chat_id' \
--header 'Authorization: Bearer t-XXX' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "message_id_list": ["om_d862083dd13b61cc009e66c40a0f0a56", "om_61244dab1ef11257621dcd7g0e256651"],
    "receive_id": "oc_a0553eda9014c201e6969b478895c230"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ message	message	合并转发生成的新消息。
└ message_id	string	消息 ID。合并转发后由系统自动生成的消息唯一标识。后续对消息的管理维护操作均需要使用该 ID。
└ root_id	string	根消息 ID，仅在回复消息场景会有返回值。了解 root_id 可参见消息管理概述。
└ parent_id	string	父消息 ID，仅在回复消息场景会有返回值。了解 parent_id 可参见消息管理概述。
└ thread_id	string	消息所属的话题 ID（不返回说明该消息非话题消息），了解话题可参见话题概述。
└ msg_type	string	消息类型，取值 merge_forward 表示合并转发消息。了解消息类型定义，参考接收消息内容。
└ create_time	string	消息生成的时间戳。单位：毫秒
└ update_time	string	消息更新的时间戳。单位：毫秒
└ deleted	boolean	消息是否被撤回。返回 false 表示未被撤回。
└ updated	boolean	消息是否被更新。返回 false 表示未被更新。
└ chat_id	string	消息所属的群 ID。你可以调用获取群信息接口，根据群 ID 获取群详情。
└ sender	sender	消息的发送者信息。
└ id	string	发送者的 ID。
└ id_type	string	发送者的 ID 类型。 可能值有： - open_id：表示发送者为用户，且返回的 ID 是用户的 open_id。 - app_id：表示发送者为应用，切返回的 ID 是应用的 app_id。
└ sender_type	string	发送者类型。 可能值有： - user: 用户 - app: 应用 - anonymous: 匿名 - unknown: 未知
└ tenant_key	string	租户唯一标识。该标识用来识别租户，也可以用来获取租户访问凭证（tenant_access_token）。
└ body	message_body	通过 body 内的 content 参数，返回所发送的消息内容。
└ content	string	消息内容，JSON 结构序列化后的字符串，合并转发生成的新消息的消息内容为固定值==Merged and Forwarded Message==，其中的子消息可以使用获取指定消息的内容接口获取。
└ mentions	mention\[\]	发送的消息内，被 @ 的用户或机器人列表。
└ key	string	被 @ 的用户或机器人序号。例如，第 3 个被 @ 到的成员，取值为 @_user_3。
└ id	string	被 @ 的用户或者机器人的 open_id。
└ id_type	string	被 @ 的用户或机器人 ID 类型，目前仅支持 open_id (什么是 Open ID)。
└ name	string	被 @ 的用户或机器人的姓名。
└ tenant_key	string	租户唯一标识。该标识用来识别被 @ 用户或机器人的租户，也可以用来获取租户访问凭证（tenant_access_token）。
└ upper_message_id	string	合并转发消息中，上一层级的消息 ID。了解 upper_message_id 可参见消息管理概述。
└ invalid_message_id_list	string\[\]	无效的消息 ID 列表，如不存在的消息、已被撤回的消息、当前操作者不可见的历史消息、接口不支持的消息类型等。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "message": {
            "message_id": "om_dc13264520392913993dd051dba21dcf",
            "root_id": "om_40eb06e7b84dc71c03e009ad3c754195",
            "parent_id": "om_d4be107c616aed9c1da8ed8068570a9f",
            "msg_type": "merge_forward",
            "create_time": "1615380573411",
            "update_time": "1615380573411",
            "deleted": false,
            "updated": false,
            "chat_id": "oc_a0553eda9014c201e6969b478895c230",
            "sender": {
                "id": "cli_9f427eec54ae901b",
                "id_type": "app_id",
                "sender_type": "app",
                "tenant_key": "736588c9260f175e"
            },
            "body": {
                "content": "Merged and Forwarded Message"
            },
        },
        "invalid_message_id_list": [
            "om_61244dab1ef11257621dcd7g0e256651"
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	230001	Your request contains an invalid request parameter.	参数错误，可根据接口实际返回的错误信息，并参考接口文档内容，检查输入参数是否填写错误。
400	230002	The bot can not be outside the group.	机器人不在对应群组中。你需要将应用机器人添加到消息相应的群组中。如何添加机器人参考机器人使用指南。
400	230006	Bot ability is not activated.	应用未启用机器人能力。启用方式参见如何启用机器人能力。
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	230018	These operations are NOT allowed at current group settings.	当前操作被群设置禁止，例如群聊设置了仅指定成员可以在此群发言。请检查群设置或联系群管理员修改群设置。
400	230019	The thread does NOT exist.	要转发到的话题不存在，请检查 thread_id 是否正确。
400	230020	This operation triggers the frequency limit.	当前操作触发频率限制，请降低请求频率后重试。
400	230027	Lack of necessary permissions.	无权进行本次操作。可能的原因有： 1. 缺少相应权限，可根据实际的错误信息进行排查。 2. 未检查到用户授权信息。 3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见机器人支持外部群和外部用户单聊。
400	230029	User has resigned.	指定的用户已离职，无法发送消息。
400	230034	The receive_id is invalid.	消息接收者 ID（receive_id）无效，请传入与 receive_id_type 类型相匹配的 ID，且保证 ID 正确。
400	230035	Send Message Permission deny.	没有发送消息的权限。请排查群聊是否已开启禁言、机器人是否被接收者屏蔽或受到租户维度的沟通权限管控。
400	230036	Tenant crypt key has been deleted.	租户加密密钥已被删除，导致被该秘钥加密的数据不可用。请联系企业管理员进行解决。
400	230038	Cross tenant p2p chat operate forbid.	跨租户的单聊不允许通过本接口发送消息。
400	230049	The message is being sent.	消息正在发送中，请稍后。
400	230053	The user has stopped the bot from sending messages.	用户已设置不再接收机器人消息，无法主动给用户发送单聊消息。
400	230062	No permission to forward to third-party encryption group.	没有权限转发到第三方加密群。
400	230063	The chat_id of group to forward is invalid.	待转发到的群是无效的，请检查 chat_id 对应的群组是否存在。
400	230064	All messages to be forwarded are invalid.	待转发的消息均为无效的，如消息不存在、已被撤回、对当前操作者不可见等。你需要确保传入的消息均有效且接口可用。
400	230065	All messages to be forwarded have been recalled.	待转发的消息都已被撤回，无法执行当前操作。
400	230066	The messages to be forwarded are in a secret group and do not support forwarding.	不支持转发密聊群中的消息。
400	230067	The source of the messages to be merged and forwarded are not in compliance.	待合并转发的消息来源不合规，请检查消息列表中的消息是否来自多个话题回复、或同时包含普通消息与话题回复中的消息。
400	230069	Does not support forwarding messages from different groups.	消息列表中的消息不属于同一个群，无法进行合并转发。
400	230070	Forwarding of messages in restricted mode is not allowed.	指定的群组已解散，无法执行当前操作。
400	230074	The target thread is invisible to the operator.	要转发到的话题对于当前操作者不可见。 如果群聊关闭了 新成员可查看历史消息 且此话题为当前操作者进入群聊之前创建的，则该话题需要当前操作者被动订阅才可见（如其他用户在话题中@操作者）。
400	232009	Your request specifies a chat which has already been dissolved.	指定的群已被解散，无法进行操作。如需更换为其他群，参见 获取群 ID。

更多错误码信息，参见通用错误码。