企业微信二次开发：私域数据基石——三大核心基础能力接口实战

在进行企微外部群的主动推送或自动化运营前，技术团队最常面临的第一个问题是："我怎么知道现在手里有哪些群？我该往哪里发？"

答案就是调用底层的基础数据能力。无论是群发、打标签还是自动回复，都离不开对个人信息、群列表、联系人关系的检索。本文将直接用通用的 Python 代码，带你跑通这三大黄金基础接口。

一、 核心基础能力一：获取个人基础信息 (/user/getProfile)

在多账号矩阵中，为了确认当前登录的 guid 究竟对应哪一个员工，我们需要先查询该实例的个人信息（如微信号、昵称、所属企业等）。

import requests

def get_my_profile(guid, token):
    """
    获取当前登录实例的个人基础信息
    """
    url = "http://127.0.0.1:5000/api/qw/doApi"
    headers = {
        "X-QIWEI-TOKEN": token,
        "Content-Type": "application/json"
    }
    
    payload = {
        "method": "/user/getProfile",
        "params": {
            "guid": guid
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=5)
        result = response.json()
        if result.get("code") == 200:
            user_data = result.get("data", {})
            print(f"👤 登录账户: {user_data.get('name')} | 企微号: {user_data.get('alias')}")
            return user_data
        else:
            print(f"❌ 获取个人信息失败: {result.get('msg')}")
    except Exception as e:
        print(f"网络异常: {e}")
    return None

二、 核心基础能力二：获取外部群列表 (/group/getGroupList)

这是做外部群主动推送的核心。只有获取到了群的唯一 ID（roomId），你的推送脚本才能精准定位目标。

def get_external_group_list(guid, token):
    """
    获取当前账号加入的所有外部群聊列表
    """
    url = "http://127.0.0.1:5000/api/qw/doApi"
    headers = {
        "X-QIWEI-TOKEN": token,
        "Content-Type": "application/json"
    }
    
    payload = {
        "method": "/group/getGroupList",
        "params": {
            "guid": guid
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=8)
        result = response.json()
        if result.get("code") == 200:
            groups = result.get("data", {}).get("list", [])
            print(f"📦 成功检索到 {len(groups)} 个群聊：")
            for index, group in enumerate(groups, 1):
                print(f"  [{index}] 群名: {group.get('groupName')} | 群ID(roomId): {group.get('roomId')}")
            return groups
        else:
            print(f"❌ 获取群列表失败: {result.get('msg')}")
    except Exception as e:
        print(f"网络异常: {e}")
    return []

三、 核心基础能力三：查询联系人详细关系 (/contact/getContactDetails)

当你的 Webhook 接收到某条群消息（只带了发言人的 senderWxid）或者有新好友添加时，你需要通过此接口查询该用户的详细资料（如备注名、企业标签、来源渠道等），以便将其精准录入 CRM 系统。

def get_contact_detail(guid, token, contact_wxid):
    """
    获取指定外部联系人/好友的详细信息与标签
    """
    url = "http://127.0.0.1:5000/api/qw/doApi"
    headers = {
        "X-QIWEI-TOKEN": token,
        "Content-Type": "application/json"
    }
    
    payload = {
        "method": "/contact/getContactDetails",
        "params": {
            "guid": guid,
            "wxid": contact_wxid  # 需要查询的联系人微信ID
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=5)
        result = response.json()
        if result.get("code") == 200:
            contact = result.get("data", {})
            print(f"🔍 查询成功 | 昵称: {contact.get('name')} | 备注: {contact.get('remark')}")
            print(f"🏷️ 拥有标签: {contact.get('tags', [])}")
            return contact
        else:
            print(f"❌ 查询联系人失败: {result.get('msg')}")
    except Exception as e:
        print(f"网络异常: {e}")
    return None

四、 二次开发实用避坑指南

1. 群列表的增量更新与本地缓存：

   /group/getGroupList 接口在群数量庞大（如几千个群）时，一次性拉取会消耗较多的带宽和物理时间。在生产环境中，切忌每次发送消息都去调用一次群列表。建议在系统启动时拉取一次并缓存在本地（如 Redis 中），当 Webhook 监听到"新进群"或"退群"事件时，再在本地内存中做增量更新。

2. 联系人 ID 变动逻辑：

   在企业微信中，外部联系人的 wxid 会因企业的不同而产生变化（通常为了保护客户隐私）。在多企业协同二次开发时，存储用户标识应优先使用平台经过转换输出的全局唯一统一标识。