查询批量消息整体进度

批量发送消息或者批量撤回消息后，可通过该接口查询消息的发送进度和撤回进度。

注意事项

• 只能查询 30 天内，通过批量发送消息接口发送的消息。
• 该接口返回的数据为查询时刻的快照数据。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/batch_messages/:batch_message_id/get_progress
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	im:message:send_multi_depts 给一个或多个部门的成员批量发消息 im:message:send_multi_users 给多个用户批量发消息

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数

名称	类型	描述
batch_message_id	string	待查询的批量消息任务 ID，该 ID 为批量发送消息接口返回值中的 message_id 字段，用于标识一次批量发送消息请求。 示例值："bm-0b3d5d1b2df7c6d5dbd1abe2c91e2217"

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ batch_message_send_progress	batch_message_send_progress	批量发送消息的进度。
└ valid_user_ids_count	int	批量发送消息请求中，有效的用户数量。 注意： - 不在当前机器人的通讯录权限数据范围内但有效的用户，也会被统计在内。了解通讯录数据权限范围参见配置应用数据权限。 - valid_user_ids_count 值为 0 有两种情况： - 批量发送消息接口为异步调用，任务还没有开始被调度便查询当前接口则取值为 0。建议你等待片刻再调用该接口。 - 批量发送消息时传入的所有 department_ids、open_ids、user_ids、union_ids 均未包含有效的用户。
└ success_user_ids_count	int	已向用户成功发送消息的数量。 注意：最终 success_user_ids_count 不一定等于 valid_user_ids_count，原因是 valid_user_ids_count 包含了对机器人不可见的用户。
└ read_user_ids_count	int	已读消息的用户数量。
└ batch_message_recall_progress	batch_message_recall_progress	批量撤回消息的进度。
└ recall	boolean	当前查询的批量发送消息任务是否执行过撤回操作。可能值： - true：消息被撤回过 - false：消息未被撤回过
└ recall_count	int	已经成功撤回的消息数量。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "batch_message_send_progress": {
            "valid_user_ids_count": 204,
            "success_user_ids_count": 200,
            "read_user_ids_count": 150
        },
        "batch_message_recall_progress": {
            "recall": true,
            "recall_count": 100
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	230001	Your request contains an invalid request parameter.	参数错误，请根据接口返回的错误信息并参考文档检查输入参数。
400	230006	Bot ability is not activated.	应用未开启机器人能力。开启方式参见如何开启机器人能力。
400	230012	Bot is NOT the sender of the message.	机器人不是消息的发送者。应用机器人只能操作自己发送的消息。
400	230027	Lack of necessary permissions.	无权进行本次操作。可能的原因有： 1. 缺少相应权限，可根据实际的错误信息进行排查。 2. 未检查到用户授权信息。 3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见机器人支持外部群和外部用户单聊。
400	230030	The message id is invalid, record not found.	消息 ID 无效，未找到记录。你需要检查并传入正确的 batch_message_id 参数后重试。

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