获取群成员明细

按 chat_id 分页列出企业微信客户群内的外部联系人（客户）成员，每个成员一次带出：群内身份与入群/退群时间、三个来源不同的名字、关联的平台会员身份（uid + 脱敏手机号）、系统归属员工，以及企业微信上的跟进员工。用于把群名册落到具体的人——各群人数汇总请用获取企业外部群列表。

信息

只列客户，不列员工：本接口只输出群内的外部联系人，企业员工成员不在返回范围内。需要「群内员工数」请用获取企业外部群列表 的 staff_count。

GET/api/getQiyeChatUserList

核心语义

1. 只读查询：只查询群成员明细，不落库、不改动任何数据，可安全轮询与重复调用。
2. 默认含已退群成员：不传 status 时在群与已退群的成员都返回，便于统计「进群人数」；只想看当前在群名册请传 status=0。
3. 排序：按入群时间、记录 ID 倒序（最新入群的在前）。
4. 入群/退群时间：join_time / out_time 为原始时间戳，另给 join_time_str / out_time_str 可读格式；时间戳为 0 时对应字符串返回空串，平台不猜测、不回填时间。
5. 在群状态：status 为原值，status_str 为可读文案（0 → 在群，非 0 → 已退群）。群被解散时该群全部成员都会被记为已退群，此时整群 status_str 都是 已退群，属既有落库行为，不是数据异常。
6. 三个名字字段来源不同、各自独立，都可能为空，平台不做优先级合并（合并会丢掉「群昵称 vs 档案名」的差异信息）：

   字段	含义
   name	群成员昵称（企业微信侧带回的成员名）
   group_nickname	该成员在本群的群内昵称，未设置时为空串
   profile_name	客户的外部联系人档案名（可能含员工备注）；查不到该客户档案时为空串

7. external_userid 与 userid 同值：群成员表里客户这一行的 userid 存的就是外部联系人 ID，两个键都给是为了与获取企微外部联系人列表 的字段直接对齐。库里存在 userid 为空串的残缺历史行，这类行关联不到档案与好友，profile_name / uid / qiye_friend_staff 均为空——接口照常返回该行且不报错，请按空值兼容。
8. unionid 会自动补齐：优先取群成员记录自身的 unionid；为空时用该客户的外部联系人档案里的 unionid 补上。「入群时还没打通、后来才关联上」的客户很常见，补齐后同样能拿到 uid / phone / staff_*，与外部联系人列表接口的结果保持一致。
9. 会员与员工字段口径与外部联系人列表接口完全一致：uid / phone / staff_uid / staff_name / qiye_friend_staff(_list) 的含义、脱敏规则、姓名回落与跟进员工去重，均见获取企微外部联系人列表 的核心语义；两接口对同一客户返回的会员身份一致。
10. 群档案缺失不报错：成员记录存在但群档案缺失（群未同步等）时照常返回成员明细，只把 chat_name 置为空串。仅当群档案查不到、且一条成员都没有时，才判定 chat_id 传错并返回错误文案。
11. 契约：code 恒为 0；成功时 msg 为空、data 为结果对象；失败时 msg 非空、data 为空数组。业务成功与否以 msg 判定。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由 获取访问令牌 获得
chat_id	String	群 ID	必填	-	见 获取企业外部群列表
status	Number	在群状态筛选	选填	全部	0：只看当前在群；1：只看已退群；不传：两者都返回
name	String	群成员昵称	选填	不筛选	模糊匹配，传关键词即可
starttime	String	入群时间筛选起点	选填	不限	支持秒级/毫秒级时间戳、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss；闭区间
endtime	String	入群时间筛选终点	选填	不限	写法同 starttime；仅给到日期时自动含当天全天（至 23:59:59）；闭区间
pageNum	Number	页码	选填	1	从 1 开始
pageSize	Number	每页条数	选填	20	最大 100（超出按 100 返回；传 0 或负数按 20 处理）

starttime / endtime 按入群时间筛选，不是退群时间；因此默认（含已退群成员）下，某成员先入群后退群再被统计时，仍以入群时间落进区间。

CURL

V1（GET）

curl --location --request GET 'https://open.xinduobang.cn/api/getQiyeChatUserList?token=YOUR_TOKEN&chat_id=wrXXXXchatid00000000000000000001'

V1（POST）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeChatUserList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'chat_id=wrXXXXchatid00000000000000000001' \
--data-urlencode 'status=0' \
--data-urlencode 'starttime=2026-01-01' \
--data-urlencode 'endtime=2026-11-09' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=50'

V2（appid 为 V2 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeChatUserList' \
--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 'chat_id=wrXXXXchatid00000000000000000001' \
--data-urlencode 'name=小明' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=20'

信息

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

成功响应

第一条为当前在群、资料齐全；第二条为已退群、且群内昵称与档案名都取不到，两种形态都会出现。

{
  "code": 0,
  "msg": "",
  "data": {
    "chat_id": "wrXXXXchatid00000000000000000001",
    "chat_name": "示例夏令营1群",
    "total": 2,
    "pageNum": 1,
    "pageSize": 20,
    "list": [
      {
        "id": 9,
        "external_userid": "wmXXXXexternaluserid01",
        "userid": "wmXXXXexternaluserid01",
        "unionid": "oXXXXXXXXXXXXXXXXXXXXXXX",
        "name": "小明",
        "group_nickname": "小明（三期家长）",
        "profile_name": "张小明",
        "status": 0,
        "status_str": "在群",
        "join_time": 1741688353,
        "join_time_str": "2025-03-11 18:19:13",
        "out_time": 0,
        "out_time_str": "",
        "uid": 7891,
        "phone": "131****7671",
        "staff_uid": 2699,
        "staff_name": "sales01",
        "qiye_friend_staff": "张丽（华东销售组）",
        "qiye_friend_staff_list": [
          { "userid": "zhangli", "name": "张丽（华东销售组）" }
        ]
      },
      {
        "id": 6,
        "external_userid": "wmXXXXexternaluserid02",
        "userid": "wmXXXXexternaluserid02",
        "unionid": "",
        "name": "小红",
        "group_nickname": "",
        "profile_name": "",
        "status": 1,
        "status_str": "已退群",
        "join_time": 1741485600,
        "join_time_str": "2025-03-09 10:00:00",
        "out_time": 1741868800,
        "out_time_str": "2025-03-13 20:26:40",
        "uid": 0,
        "phone": "",
        "staff_uid": 0,
        "staff_name": "",
        "qiye_friend_staff": "",
        "qiye_friend_staff_list": []
      }
    ]
  }
}

若群档案缺失，chat_name 返回空字符串，list 内容不受影响。

data 字段说明

键	类型	说明
chat_id	String	本次查询的群 ID，回传入参
chat_name	String	群名称；群档案缺失时为空字符串
total	Number	该群符合条件的成员总条数（用于计算总页数）
pageNum	Number	当前页码
pageSize	Number	每页条数
list	Array	群内外部联系人列表，按入群时间、记录 ID 倒序（最新入群在前）

list[] 字段说明

字段	类型	说明
id	Number	群成员记录主键
external_userid	String	外部联系人 ID
userid	String	与 external_userid 同值，便于与外部联系人列表接口对齐；历史残缺行可能为空串
unionid	String	微信 unionid；成员行为空时已自动用客户档案补齐，两者都没有时为空串
name	String	群成员昵称
group_nickname	String	群内昵称，未设置时为空串
profile_name	String	外部联系人档案名，查不到档案时为空串
status	Number	在群状态原值：0 在群、非 0 已退群
status_str	String	在群状态文案：在群 / 已退群
join_time	Number	入群时间（unix 时间戳，秒级）；未同步到时为 0
join_time_str	String	入群时间可读格式 YYYY-MM-DD HH:mm:ss；join_time 为 0 时为空串
out_time	Number	退群时间（unix 时间戳，秒级）；仍在群时为 0
out_time_str	String	退群时间可读格式；out_time 为 0 时为空串
uid	Number	关联的平台会员编号；未关联到会员时为 0
phone	String	会员手机号，固定脱敏（如 131****7671）；无手机号或未关联会员时为空字符串
staff_uid	Number	系统归属员工编号；0 表示无归属销售
staff_name	String	系统归属员工姓名，真实姓名为空时回退账号名
qiye_friend_staff	String	企业微信跟进员工姓名串，多个用中文逗号（，）分隔；无数据时为空字符串
qiye_friend_staff_list	Array	企业微信跟进员工明细，与 qiye_friend_staff 顺序一致；无数据时为空数组 []
qiye_friend_staff_list[].userid	String	跟进员工的企业微信 userid
qiye_friend_staff_list[].name	String	跟进员工姓名；查不到姓名时回落显示该员工的 userid

失败响应

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

{ "code": 0, "msg": "chat_id不能为空", "data": [] }

{ "code": 0, "msg": "群不存在或该群没有符合条件的成员：wrXXXXchatid_not_exist", "data": [] }

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

错误文案	说明
chat_id不能为空	未传 chat_id
群不存在或该群没有符合条件的成员：xxx	群档案查不到，且按条件一条成员也没有——通常说明 chat_id 传错；群档案缺失但成员存在时不会报此错
starttime格式错误：xxx	starttime 无法解析为时间戳或日期字符串
endtime格式错误：xxx	endtime 无法解析为时间戳或日期字符串

注意事项

• 本接口不返回邀请人、入群方式与渠道归因串：这三类信息当前不对外输出，如业务需要请联系平台确认开通计划。
• 默认含已退群成员：统计「进群人数」用默认；要「当前在群名册」传 status=0；群解散会让整群显示 已退群，需结合获取企业外部群列表 的 is_delete 判断原因。
• 三个名字字段勿混用：name 是企业微信侧成员昵称、group_nickname 是本群昵称、profile_name 是客户档案名，来源与更新时机都不同，展示时建议按 profile_name → group_nickname → name 自行选择优先级并留空值兜底。
• 空值都是正常数据：unionid、phone、staff_*、qiye_friend_staff、group_nickname、profile_name 取不到时为空字符串，uid / staff_uid 为 0，请一律按「可能为空」解析。
• 翻页建议按 total 计算页数：Math.ceil(total / pageSize)；本接口返回总条数，无需靠「返回空页」判断结束。

相关接口

• 获取访问令牌（取 token）：获取访问令牌
• 群名册与各群人数（取 chat_id、比员工数）：获取企业外部群列表
• 全量客户名册（会员/员工字段同一口径）：获取企微外部联系人列表
• 群变更的原始事件记录：查询企微消息回调记录

变更记录

日期	变更
2026-11-09	首次发布：/api/getQiyeChatUserList（GET/POST，chat_id 必填，其余筛选参数可选）。按群分页列出群内外部联系人成员，每条带出在群状态与入群/退群时间、三个来源不同的名字字段、关联的平台会员身份（uid、脱敏 phone）、系统归属员工与企业微信跟进员工；默认同时返回已退群成员，unionid 在成员行为空时自动用客户档案补齐，群档案缺失时照常返回明细且 chat_name 为空串。企业外部群列表、企微外部联系人列表两篇文档同步增加互链导航