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

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

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

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

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

python 复制代码
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),你的推送脚本才能精准定位目标。

python 复制代码
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 系统。

python 复制代码
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 会因企业的不同而产生变化(通常为了保护客户隐私)。在多企业协同二次开发时,存储用户标识应优先使用平台经过转换输出的全局唯一统一标识。

相关推荐
码客-ygluu12 小时前
X3 LUA 异步分布式微服务集群框架
c++·架构·lua
Decay__17 小时前
VMware 安装 SQL Server 双节点 AlwaysOn 可用性组教程 —— WSFC、AG 与侦听器完整部署(系列核心篇)
运维·数据库·sql·mysql·架构
wangruofeng17 小时前
从 GIF 到 AVIF:网页图片格式演进与 2026 年选型指南
前端·架构
Softmaxmap19 小时前
从零做一个中文小模型:600 亿 token 数据、mHC + Engram 结构、到强化学习的全流程(开源)
架构
你三大爷19 小时前
从 Hessian 迁移到 protostuff:深嵌套模型反序列化耗时与高并发类加载锁的根治实战
后端·架构
Funlang1 天前
在 Windows 95 上跑 Fun
windows
一条Go1 天前
接收方合并去重:同一个人为什么只该收到一次通知
后端·架构·github
吴建旭 智宅焕1 天前
智能家居全国交付标准化架构的轻重分离设计:重勘测节点与轻执行流程的系统实现
架构·智能家居
flash俊杰1 天前
v0.5-01 让桌面 AI 助手记得住:预算组装、递归摘要、长期记忆与评估基线
数据库·安全·架构
leo在掘金1 天前
只挂了11小时,5000台开发机被塞进SSH公钥
后端·架构