转发话题

调用该接口将话题转发至指定的用户、群聊或话题。

前提条件

• 应用需要开启机器人能力。
• 调用接口的机器人必须在待转发话题所在的群中，且可见该话题。
• 向用户转发话题时，用户需要在机器人的可用范围内。
• 向群组中转发话题，需要机器人在该群组中，且拥有发言权限。

使用限制

• 为避免消息发送频繁对用户造成打扰，向同一用户发送消息的限频为 ==5 QPS==、向同一群组发送消息的限频为群内机器人共享 ==5 QPS==。
• 转发话题生成的新消息的消息内容为固定值==Merged and Forwarded Message==，其中的子消息可以使用获取指定消息的内容接口获取。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/threads/:thread_id/forward
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	im:message 获取与发送单聊、群组消息 im:message:send_as_bot 以应用的身份发消息
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

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

路径参数

名称	类型	描述
thread_id	string	要转发的话题ID，获取方式参见话题概述的 如何获取 thread_id 章节。 示例值："omt_dc132645203"

查询参数

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

请求体

名称	类型	必填	描述
receive_id	string	是	消息接收者 ID，ID 类型与 receive_id_type 的值一致。 示例值："oc_a0553eda9014c201e6969b478895c230"

请求体示例

{
    "receive_id": "oc_a0553eda9014c201e6969b478895c230"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	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	消息类型。类型定义参考接收消息内容。
└ 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 可参见消息管理概述。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "message_id": "om_dc13264520392913993dd051dba21dcf",
        "root_id": "om_40eb06e7b84dc71c03e009ad3c754195",
        "parent_id": "om_d4be107c616aed9c1da8ed8068570a9f",
        "thread_id": "omt_d4be107c616a",
        "msg_type": "merge_forward",
        "create_time": "1609296809",
        "update_time": "1609336806",
        "deleted": false,
        "updated": false,
        "chat_id": "oc_5ad11d72b830411d72b836c20",
        "sender": {
            "id": "cli_9f427eec54ae901b",
            "id_type": "app_id",
            "sender_type": "app",
            "tenant_key": "736588c9260f175e"
        },
        "body": {
            "content": "Merged and Forwarded Message"
        }
    }
}

错误码

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	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	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	230050	The message is invisible to the operator.	消息对于当前操作者不可见，无法进行本操作。
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	The thread to be forwarded is invalid.	要转发的话题 ID 是无效的，请检查该 thread_id 是否存在。
400	230066	The thread to be forwarded is in a secret group, forwarding is not supported.	要转发的话题归属于密聊群，不支持转发。
400	230070	Forwarding of messages in restricted mode is not allowed.	要转发的话题所属的群聊已开启防泄密模式，不支持转发。
400	230073	The thread is invisible to the operator.	要转发的话题对于当前操作者不可见。如果群聊关闭了 新成员可查看历史消息 且此话题为当前操作者进入群聊之前创建的，则该话题需要当前操作者被动订阅才可见（如其他用户在话题中@操作者）。
400	230074	The target thread is invisible to the operator.	要转发到的话题对于当前操作者不可见。 如果群聊关闭了 新成员可查看历史消息 且此话题为当前操作者进入群聊之前创建的，则该话题需要当前操作者被动订阅才可见（如其他用户在话题中@操作者）。
400	230110	Action unavailable as the message has been deleted.	消息已被删除，无法执行当前操作。
400	232009	Your request specifies a chat which has already been dissolved.	指定的群已被解散，无法进行操作。如需更换为其他群，参见 获取群 ID。

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