获取企业外部群列表

分页列出企业微信侧的客户群（外部群），每个群一次带出群 ID、群名称、群主、建群时间，以及该群的进群客户人数、累计入群人次、离群人数、群内员工数四项计数。支持按群 ID、群名称、群主、建群时间区间筛选，并可选择是否把已解散的群一并列出。

信息

只给人数，不给名单：本接口返回的是各群的汇总人数。需要具体是哪些人在群里，请用获取群成员明细。

GET/api/getQiyeChatList

核心语义

1. 只读查询：只查询客户群名册与人数，不落库、不改动任何数据，可安全轮询与重复调用。
2. 默认只列未解散的群：传 include_dismiss=1 时把已解散的群一并列出，解散群通过 is_delete = 1 标识。
3. 排序：按建群时间、记录 ID 倒序（最新建的群在前）。
4. 四项人数的口径（详见下表）：分别对应「当前在群的客户」「已离群的客户」「累计入群人次」「当前在群的员工」。
5. 闭合不变量：member_count + left_count = join_total_count，任何一条记录都成立，可用它做接入自校验。
6. join_total_count 是「人次」不是「人」：按入群记录条数统计，同一客户退群后又重新进群会累计两条，因此 join_total_count 可能大于该群实际服务过的客户人数。当前在群人数（member_count）不受此影响。
7. 解散群的人数表现：群解散时群内所有成员都会被记为已离群，因此解散群表现为 member_count = 0、left_count 等于累计入群人次——这是正常数据，不是取数异常。
8. 建群时间可能取不到：addtime 取自企业微信侧的建群时间，早期同步或企微未返回该字段的历史群会是 addtime = 0，此时 addtime_str 返回空字符串（平台不猜测、不回填一个时间）。
9. 群名称为空时返回平台生成的占位名：企业微信侧没有群名称时，chat_name 返回 创建者：{群主} 创建时间【YYYY-MM-DD HH:mm:ss】 形式的拼串，与平台后台群下拉的显示完全一致，避免调用方在一串空名里分不清是哪个群。群主未同步到时该串形如 创建者： 创建时间【--】。这个拼串不是企业微信侧的真实群名，请勿当作群名称入库展示。
10. 契约：code 恒为 0；成功时 msg 为空、data 为结果对象；失败时 msg 非空、data 为空数组。业务成功与否以 msg 判定。

人数口径

字段	含义	统计范围
member_count	进群客户人数	类型为客户、且当前仍在群
left_count	离群人数	类型为客户、曾入群但当前已不在群（含自己退群、被移出、群解散）
join_total_count	累计入群人次	类型为客户的全部入群记录（含已离群）
staff_count	群内员工数	类型为企业员工、且当前仍在群

信息

与平台后台「企业微信群数据分析」页的人数卡片有一处口径差异：后台页面会把「成员类型登记为客户、但账号实际是员工」的人从客户中剔除并计入员工数；本接口按企业微信侧登记的成员类型原值统计，不做这层剔除。因此本接口的 member_count 可能略大、staff_count 可能略小，两边有小幅出入属正常口径差异，不是取数错误。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由 获取访问令牌 获得
chat_id	String	群 ID	选填	不筛选	精确匹配
chat_name	String	群名称	选填	不筛选	模糊匹配，传关键词即可
owner	String	群主	选填	不筛选	群主的企业员工 userid，精确匹配
starttime	String	建群时间筛选起点	选填	不限	支持秒级/毫秒级时间戳、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss；闭区间
endtime	String	建群时间筛选终点	选填	不限	写法同 starttime；仅给到日期时自动含当天全天（至 23:59:59）；闭区间
include_dismiss	Number	是否包含已解散的群	选填	0	1：已解散的群一并列出（is_delete = 1）；0：只列未解散的群
pageNum	Number	页码	选填	1	从 1 开始
pageSize	Number	每页条数	选填	20	最大 100（超出按 100 返回；传 0 或负数按 20 处理）

所有筛选条件均为「传了才生效」，都不传即返回全量群（按分页）。时间戳同时接受 13 位毫秒级，自动换算。

starttime / endtime 不会自动放宽解散群：include_dismiss 未传 1 时，即使时间区间覆盖了已解散的群，它们也不会出现。

CURL

V1（GET）

curl --location --request GET 'https://open.xinduobang.cn/api/getQiyeChatList?token=YOUR_TOKEN&pageSize=20&pageNum=1'

V1（POST）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeChatList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'chat_name=夏令营' \
--data-urlencode 'starttime=2026-01-01' \
--data-urlencode 'endtime=2026-11-09' \
--data-urlencode 'include_dismiss=1' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=50'

V2（appid 为 V2 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeChatList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Timestamp: 1770000000' \
--header 'X-Nonce: 3f9c1a7b2e6d4058' \
--header 'X-Signature: <computed_hmac_sha256>' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'owner=staff_zhangli' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=20'

信息

V2 签名算法及 X-Signature 计算方式见 V2 接入示例。

成功响应

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 36,
    "pageNum": 1,
    "pageSize": 2,
    "list": [
      {
        "chat_id": "wrXXXXchatid00000000000000000001",
        "chat_name": "示例夏令营1群",
        "owner": "staff_zhangli",
        "addtime": 1758765000,
        "addtime_str": "2025-09-25 09:50:00",
        "is_delete": 0,
        "member_count": 42,
        "join_total_count": 55,
        "left_count": 13,
        "staff_count": 3
      },
      {
        "chat_id": "wrXXXXchatid00000000000000000002",
        "chat_name": "创建者： 创建时间【--】",
        "owner": "",
        "addtime": 0,
        "addtime_str": "",
        "is_delete": 0,
        "member_count": 3,
        "join_total_count": 5,
        "left_count": 2,
        "staff_count": 0
      }
    ]
  }
}

第二条正好覆盖三个边界：addtime = 0（建群时间未从企业微信同步到，故 addtime_str 为空串）、owner 为空（群主未同步到，占位群名里的创建者一段随之为空）、staff_count = 0（群内没有登记为企业员工的成员）。两条均满足 member_count + left_count = join_total_count。

data 字段说明

键	类型	说明
total	Number	符合条件的群总个数（用于计算总页数）
pageNum	Number	当前页码
pageSize	Number	每页条数
list	Array	客户群列表，按建群时间、记录 ID 倒序（最新在前）

list[] 字段说明

字段	类型	说明
chat_id	String	群 ID（企业微信客户群唯一标识）
chat_name	String	群名称；企业微信侧无群名时为平台生成的占位串 创建者：{群主} 创建时间【YYYY-MM-DD HH:mm:ss】，见核心语义第 9 条
owner	String	群主的企业员工 userid；群主未同步到时为空字符串
addtime	Number	建群时间（unix 时间戳，秒级）；未同步到时为 0
addtime_str	String	建群时间可读格式 YYYY-MM-DD HH:mm:ss；addtime 为 0 时为空字符串
is_delete	Number	群状态：0 未解散、1 已解散（仅在 include_dismiss=1 时会出现 1）
member_count	Number	进群客户人数（当前仍在群的客户）
join_total_count	Number	累计入群人次（含已离群，按记录条数计，非按人去重）
left_count	Number	离群人数（曾入群、当前已不在群的客户）
staff_count	Number	群内员工数（当前仍在群的企业员工）

失败响应

契约下 code 恒为 0，失败通过非空 msg 与空 data 标识。

{ "code": 0, "msg": "starttime格式错误：abc", "data": [] }

错误文案	说明
starttime格式错误：xxx	starttime 无法解析为时间戳或日期字符串
endtime格式错误：xxx	endtime 无法解析为时间戳或日期字符串

注意事项

• 人数为 0 是有效值：staff_count = 0 表示群内没有登记为企业员工的成员，member_count = 0 且 join_total_count > 0 通常是群已解散或客户已全部离群，请结合 is_delete 判断，勿当作取数失败。
• chat_name 可能是占位串：以 创建者： 开头的值是平台在群名为空时生成的，不是企业微信侧真实群名；若要展示群名称，建议先判前缀或直接以 chat_id 为准。
• 按群主筛选传 userid：owner 接收的是企业员工 userid，不是员工姓名。
• 时间筛选为闭区间：starttime、endtime 均含边界；endtime 仅写到日期时自动补到当天 23:59:59。
• 翻页建议按 total 计算页数：Math.ceil(total / pageSize)；本接口返回总条数，无需靠「返回空页」判断结束。

相关接口

• 获取访问令牌（取 token）：获取访问令牌
• 按 chat_id 查群内具体成员名单：获取群成员明细
• 客户维度的名册与会员/员工身份：获取企微外部联系人列表
• 群变更的原始事件记录：查询企微消息回调记录

变更记录

日期	变更
2026-11-09	首次发布：/api/getQiyeChatList（GET/POST，筛选参数全部可选）。分页列出企业微信客户群，每群带出群 ID、群名称、群主、建群时间与四项人数（进群客户人数、累计入群人次、离群人数、群内员工数，满足 member_count + left_count = join_total_count）；支持群 ID / 群名称 / 群主 / 建群时间区间筛选，include_dismiss=1 可一并列出已解散的群，按建群时间倒序分页输出