QiWe开放平台 · 开发者名片
API驱动企微自动化，让开发更高效
核心能力：为开发者提供标准化接口、快速集成工具，助力产品高效拓展功能场景
官方站点：https://www.qiweapi.com
团队定位：专注企微API生态的技术服务团队
对接通道：搜「QiWe 开放平台」联系客服
核心理念：合规赋能，让企微开发更简单、更高效
1. 为什么必须使用 Cursor 分页？
传统的page_number分页在数据频繁变动（如拉取过程中有新群产生）时容易出现跳项或重复。Cursor 分页通过记录“上一次查询的终点”作为“下一次查询的起点”，确保了：
高并发下的稳定性：即使数据在翻页过程中发生增删，也不会导致分页偏移。
性能一致性：在大数据量下，查询速度不会随着页码增加而变慢。
2. 接口调用流程
接口地址：
POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/list关键请求参数：
cursor：分页游标。首次请求传空字符串""。limit：每页返回的记录数。最大值为1000，生产环境下建议设置为500。
3. 分页迭代逻辑（伪代码）
在用户模块中，你可以按照以下逻辑实现自动翻页，将所有chat_id同步到本地数据库：
all_chat_ids = [] cursor = "" while True: # 构造请求参数 payload = { "cursor": cursor, "limit": 500, "status_filter": 0 # 0代表正常状态的群 } response = requests.post(url, json=payload).json() if response['errcode'] == 0: # 1. 提取当前页的群ID batch_ids = [item['chat_id'] for item in response['group_chat_list']] all_chat_ids.extend(batch_ids) # 2. 获取下一页的游标 cursor = response.get('next_cursor') # 3. 退出条件：如果没有新的游标返回，说明拉取完毕 if not cursor: break else: # 处理 Token 过期或接口限频等异常 handle_error(response) break4. 接入时的注意事项
过滤器 (status_filter) 的使用
在分页请求时，建议明确指定status_filter。
0：仅拉取当前存在的群。
1：拉取已解散的群。
通常在执行“主动推送”前，只需拉取状态为
0的群。
配合群详情接口使用
分页接口list仅返回chat_id和status。
建议方案：在分页拉取到
chat_id列表后，将其放入任务队列。后续动作：由另一个 Worker 实例批量调用
groupchat/get接口，根据chat_id获取群名、群主及成员详情。
频率保护
虽然分页接口限频较宽，但在处理数万个群时，建议在循环请求中加入100ms-200ms 的随机延迟，以保护企业号的安全权重。
总结
群分页是外部群管理的基础。通过cursor稳定拉取chat_id，配合数据库的唯一索引存储，可以构建起一套实时更新的群资源图谱。
