核心功能：获取客户群详情及成员列表

能力介绍

获取外部群成员接口允许企业通过 API 调取指定客户群内的完整成员清单。该能力不仅可以获取成员的 userid（内部员工）或 external_userid（外部客户），还能识别成员在群内的角色（群主、管理员）、入群时间以及入群方式（通过扫描二维码、成员邀请等）。这是进行社群活跃度分析、客户分层管理及安全审计的基础数据来源。

10 分钟接入 Demo

1. 确定 ChatID：通过 groupchat/list 接口获取需要查询的客户群 ID。

2. 权限声明：确保调用接口的应用拥有“客户联系”权限，且目标群聊在应用的管理范围内。

3. 调用接口：向 POST /externalcontact/groupchat/get 发起请求。

4. 解析数据：在返回的 member_list 数组中提取成员信息。

5. 字段对齐：根据 type 字段区分内部成员（type=1）和外部联系人（type=2）。

API 示例代码

以下为获取客户群成员列表的标准 Python 示例：

import requests
import json

def get_group_members(access_token, chat_id):
    url = f"https://api.qiweapi.com/cgi-bin/externalcontact/groupchat/get?access_token={access_token}"
    
    payload = {
        "chat_id": chat_id,
        "need_name": 1  # 1表示返回群成员的名字，0则不返回
    }
    
    response = requests.post(url, data=json.dumps(payload))
    res_data = response.json()
    
    if res_data.get("errcode") == 0:
        return res_data.get("group_chat").get("member_list")
    else:
        return res_data

# 调用示例
# members = get_group_members("YOUR_TOKEN", "wrOgQhDgAAxxxxxxxx")
# for m in members:
#     print(f"姓名: {m.get('name')}, 类型: {'外部' if m['type']==2 else '内部'}")

使用场景说明

• 社群审计与风控：通过定期拉取成员列表，排查是否有竞品账号混入群聊，或监控是否有违规被踢出的成员再次入群。

• 进群来源追踪：分析 join_scene 字段，识别哪些群是通过线下二维码引流的，哪些是通过员工主动拉取的，从而评估各渠道引流效果。

• 活跃客户识别：结合消息统计，将群成员列表与业务系统打通，识别出长期在群的高价值忠诚客户。

• 离职继承校验：当群主离职触发群继承后，通过此接口确认新群主是否已成功接管并更新群内管理逻辑。

FAQ

• Q：为什么返回的成员名字是“企业微信用户”或为空？

  • A：如果外部联系人未向你的企业授权展示昵称，或者 need_name 未设置为 1，则可能无法获取真实昵称。

• Q：接口有翻页功能吗？如果群成员超过 500 人怎么办？

  • A：该接口目前一次性返回当前群内的所有成员列表，由于客户群上限为 500 人，通常不需要分页处理。

• Q：可以获取成员在群里的聊天记录吗？

  • A：该接口仅用于获取成员身份信息。如需获取聊天内容，需通过“会话内容存档”功能（需额外开通及合规授权）。

引导入口

• 查看完整文档：QiWe API 文档 - 客户群管理详情

• 企微官网：QiWe 官网