WeChat类

🌐

WeChat 类继承了 Chat类的所有方法，有关聊天框内的操作，请参考 Chat类的文档。

WeChat 类方法

初始化参数

参数	类型	默认值	描述
resize	bool	True	是否自动调整窗口尺寸，默认是
debug	bool	False	是否开启调试模式
version	Literal['微信', 'WeChat']	'微信'	微信客户端版本，设置为`'WeChat'`可支持国际版客户端

from wxautox4 import WeChat

wx = WeChat()

✨保持程序运行 KeepRunning

由于wxautox4使用守护线程来监听消息，当程序仅用于监听模式时，主线程会退出，因此需要调用此方法来保持程序运行

from wxautox4 import WeChat

wx = WeChat()
wx.AddListenChat('张三', callback=lambda msg, chat: ...)

# 保持程序运行，确保正常监听
wx.KeepRunning()

获取当前会话列表 GetSession

sessions = wx.GetSession()
for session in sessions:
    print(session.info)

返回值：

类型：List[SessionElement]
描述：当前会话列表

打开聊天窗口 ChatWith

wx.ChatWith(who="张三", exact=False)

参数：

参数	类型	默认值	描述
who	str	必填	要聊天的对象
exact	bool	False	搜索好友时是否精确匹配

返回值：无

✨获取子窗口实例 GetSubWindow

chat = wx.GetSubWindow(nickname="张三")

参数：

参数	类型	默认值	描述
nickname	str	必填	要获取的子窗口的昵称

返回值：

类型：Chat
描述：子窗口实例

✨获取所有子窗口实例 GetAllSubWindow

chats = wx.GetAllSubWindow()

返回值：

类型：List[Chat]
描述：所有子窗口实例的列表

✨添加监听聊天窗口 AddListenChat

def on_message(msg, chat):
    print(f"收到来自 {chat} 的消息: {msg.content}")

wx.AddListenChat(nickname="张三", callback=on_message)

参数：

参数	类型	默认值	描述
nickname	str	必填	要监听的聊天对象
callback	Callable[[Message, Chat], None]	必填	回调函数，参数为(Message对象, Chat对象)

返回值：

成功时：
- 类型：Chat
- 描述：该监的听子窗口实例
失败时：
- 类型：WxResponse
- 描述：执行结果，成功时包含监听名称

✨移除监听聊天 RemoveListenChat

wx.RemoveListenChat(nickname="张三")

参数：

参数	类型	默认值	描述
nickname	str	必填	要移除的监听聊天对象

返回值：

类型：WxResponse
描述：执行结果

✨开始监听 StartListening

wx.StartListening()

参数：无

返回值：无

✨停止监听 StopListening

wx.StopListening()

参数：

参数	类型	默认值	描述
remove	bool	True	是否移出所有子窗口

返回值：无

切换到聊天页面 SwitchToChat

wx.SwitchToChat()

返回值：无

切换到联系人页面 SwitchToContact

wx.SwitchToContact()

返回值：无

✨进入朋友圈 Moments

moments = wx.Moments(timeout=3)

参数：

参数	类型	默认值	描述
timeout	int	3	等待时间（秒）

返回值：

类型：MomentsWnd
描述：朋友圈窗口实例

✨发送朋友圈 PublishMoment

text = '''oh
今天天气真好
适合出去走走

嘿嘿~
'''
media_files = [
    r"D:\Images\Pictures\1.png",
    r"D:\Images\Pictures\2.png",
    r"D:\Images\Pictures\3.png",
]
privacy_config = {
    'privacy': '白名单',    # 设置为黑名单模式
    'tags': ['家人','朋友']      # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人
}
# privacy_config = {}     # 公开发布，没有任何权限设置
wx.PublishMoment(text, media_files, privacy_config)

✨获取好友申请 GetNewFriends

newfriends = wx.GetNewFriends(acceptable=True)

for new in newfriends:
    print(f"{new.name} ： {new.msg}")
    new.accept(remark='备注名', tags='朋友') # 自动接受好友请求，并添加备注和标签

wx.SwitchToChat() # 操作完成后切换回聊天页面

参数：

参数	类型	默认值	描述
acceptable	bool	True	是否过滤掉已接受的好友申请
roll_times	int	0	向下滚动的次数，为了加载更多好友请求，一般情况下用不到

返回值：

类型：List[NewFriendElement]
描述：新的好友申请列表

示例：

newfriends = wx.GetNewFriends(acceptable=True)
tags = ['标签1', '标签2']
for friend in newfriends:
    remark = f'备注{friend.name}'
    friend.accept(remark=remark, tags=tags)  # 接受好友请求，并设置备注和标签

✨添加新的好友 AddNewFriend

wx.AddNewFriend(keywords="张三", addmsg="我是小明", remark="老张", tags=["同学"], permission="朋友圈", timeout=5)

参数：

参数	类型	默认值	描述
keywords	str	必填	搜索关键词，可以是昵称、微信号、手机号等
addmsg	str	None	添加好友时的附加消息
remark	str	None	添加好友后的备注
tags	List[str]	None	添加好友后的标签
permission	Literal['朋友圈', '仅聊天']	'朋友圈'	添加好友后的权限
timeout	int	float	5

返回值：

类型：WxResponse
描述：添加好友的结果

✨修改好友信息 EditFriendInfo

修改好友的备注和标签

wx.EditFriendInfo(add_tags=['同事', '北京'], remove_tags=['老同学'], remark='张三（北京）')

参数：

参数名	类型	默认值	描述
add_tags	List[str]	None	要添加的标签列表
remove_tags	List[str]	None	要移除的标签列表
remark	str	None	要设置的备注，传入空字符串可清除备注
tag_wait	float	0.2	标签操作等待时间（秒）

返回值：

类型：WxResponse
描述：操作结果

说明：

add_tags、remove_tags、remark 三个参数不能同时为 None，否则返回失败

✨获取下一个聊天窗口新消息 GetNextNewMessage

def callback(msg):
    if msg.type == 'image':
        msg.download()

wx.GetNextNewMessage(callback=callback)

参数：

参数	类型	默认值	描述
filter_mute	bool	False	是否过滤消息免打扰
callback	Callable[[Message], None]	None	获取消息时的操作，不要在此处执行发送消息等操作，会使消息窗口重置，无法正常获取到所有消息

返回值：

类型：Dict[str, List[Message]]
描述：消息列表，键为聊天名称，值为消息列表

示例：

{'chat_name': 'wxauto交流',
  'chat_type': 'group',
  'remark': '群备注名',  # 仅当有备注名时存在
  'msg': [
      <wxautox - TimeMessage(2025年5月2...) at 0x227379555d0>,
      <wxautox - FriendImageMessage([图片]) at 0x2273795ca10>,
      <wxautox - FriendTextMessage(/[微笑]) at 0x22737967c50>,
      <wxautox - FriendTextMessage(你点击发送会自动...) at 0x227366c4f50>, 
      ...
    ]
}

✨获取最近群聊名称列表 GetAllRecentGroups

groups = wx.GetAllRecentGroups()
if groups:
    print(groups)
else:
    print('获取失败')

返回值：

类型：WxResponse | List[str]: 失败时返回WxResponse，成功时返回所有最近群聊列表

✨发送链接卡片 SendUrlCard

wx.SendUrlCard(url="https://example.com", friends="张三", timeout=10)

参数：

参数	类型	默认值	描述
url	str	必填	链接地址
friends	Union[str, List[str]]	None	发送对象，可以是单个用户名或用户名列表
message	str	None	附加消息，默认不发送
timeout	int	10	等待时间（秒）

返回值：

类型：WxResponse
描述：发送结果

✨获取历史消息 GetHistoryMessage

参数：

参数	类型	默认值	描述
n	int	必填	获取数量
callback	Callable[[Message], None]	None	消息回调函数
interval	float	0.2	滚动间隔时间
speed	int	1	滚动速度
goback	bool	True	获取结束后是否返回最新消息位置

def callback(msg):
    if msg.type == 'image':
        msg.download()

wx.ChatWith('工作群') # 先切换到要获取记录的聊天窗口
msgs = wx.GetHistoryMessage(n=50, callback=callback) # 获取50条消息

callback函数支持设置停止条件，当回调函数返回值为 WxParam.CALLBACK_STOP_SIGN 时停止

from wxautox4 import WxParam
from wxautox4.msgs import TimeMessage   # v40.1.9及以上版本支持TimeMessage对象

# 示例：如果找到带有“通知”字眼的消息则停止获取
def history_callback(msg):
    # 当消息内容里包含特定字词时停止
    if '通知' in msg.content:
        print('获取到包含“通知”的消息，停止获取历史消息')
        return WxParam.CALLBACK_STOP_SIGN

    # 当消息时间超过特定时间时停止     # v40.1.9及以上版本支持TimeMessage对象
    if isinstance(msg, TimeMessage) and msg.time < '2026-02-01':
        print('获取到早于2026年2月1日的消息，停止获取历史消息')
        return WxParam.CALLBACK_STOP_SIGN

wx.GetHistoryMessage(n=100, callback=history_callback)

INFO

v40.1.8及以上版本支持CALLBACK_STOP_SIGN作为停止条件
v40.1.9及以上版本支持TimeMessage对象

返回值:

类型：List[Message]

✨获取好友列表 GetFriendDetails

# 获取前10个好友详情信息
messages = wx.GetFriendDetails(n=10)

参数：

参数	类型	默认值	描述
n	int	None	获取前n个好友详情信息，None表示获取所有好友
timeout	int	0xFFFFF	获取超时时间（秒），超过该时间则直接返回结果
save_head_image	bool	False	是否保存头像图片
save_head_wait	int	0	保存头像等待时间
interval	int	0	获取间隔时间
callback	Callable[[str], bool]	None	回调函数，参数为好友昵称，用于定位开始获取的位置，返回True表示从该好友开始获取，返回False表示继续查找
speed	int	3	滚动速度
max_repeat	int	10	最大重复次数

返回值：

类型：List[dict]
描述：所有好友详情信息

# 案例
{'头像': 'D:\\myproject\\wxautox文件下载\\头像\\202511210038064171.png',
  '昵称': '张三',
  '微信号': 'zhangsan',
  '标签': 'wxauto',
  '共同群聊': '3个',
  '个性签名': '天道酬勤',
  '来源': '通过扫一扫添加'}

callback 示例：

# 示例1：从昵称为"陈"开头的好友开始获取
def callback(name):
    if name.startswith('陈'):
        return True

wx.GetFriendDetails(callback=callback)

# 示例2：使用re实现更复杂的定位逻辑
import re

def callback(name):
    # 从张三或者李四开始
    if re.match(r'张三｜李四', name):
        return True

wx.GetFriendDetails(callback=callback)

WARNING

该方法运行时间较长，约0.3~0.5秒一个好友的速度，好友多的话可将n设置为一个较小的值，先测试一下

✨创建群聊 CreateGroup

wx.CreateGroup(contacts=["张三", "李四", "王五"])

参数：

参数	类型	默认值	描述
contacts	List[str]	必填	联系人列表

返回值：

类型：WxResponse
描述：是否创建成功

✨是否在线 IsOnline

wx.IsOnline()

返回值：

类型：bool

✨获取我的信息 GetMyInfo

获取自己的微信号等信息

wx.GetMyInfo()

返回值：

类型：Dict[str, str]

✨获取对话框 GetDialog

获取当前窗口的对话框

dialog = wx.GetDialog(wait=3)

参数：

参数	类型	默认值	描述
wait	int	3	隐性等待时间（秒）

返回值：

类型：WeChatDialog
描述：对话框对象，可对其进行相应处理

WeChat类#

#WeChat 类方法

#初始化参数

#✨保持程序运行 KeepRunning

#获取当前会话列表 GetSession

#打开聊天窗口 ChatWith

#✨获取子窗口实例 GetSubWindow

#✨获取所有子窗口实例 GetAllSubWindow

#✨添加监听聊天窗口 AddListenChat

#✨移除监听聊天 RemoveListenChat

#✨开始监听 StartListening

#✨停止监听 StopListening

#切换到聊天页面 SwitchToChat

#切换到联系人页面 SwitchToContact

#✨进入朋友圈 Moments

#✨发送朋友圈 PublishMoment

#✨获取好友申请 GetNewFriends

#✨添加新的好友 AddNewFriend

#✨修改好友信息 EditFriendInfo

#✨获取下一个聊天窗口新消息 GetNextNewMessage

#✨获取最近群聊名称列表 GetAllRecentGroups

#✨发送链接卡片 SendUrlCard

#✨获取历史消息 GetHistoryMessage

#✨获取好友列表 GetFriendDetails

#✨创建群聊 CreateGroup

#✨是否在线 IsOnline

#✨获取我的信息 GetMyInfo

#✨获取对话框 GetDialog

WeChat类

WeChat 类方法

初始化参数

✨保持程序运行 KeepRunning

获取当前会话列表 GetSession

打开聊天窗口 ChatWith

✨获取子窗口实例 GetSubWindow

✨获取所有子窗口实例 GetAllSubWindow

✨添加监听聊天窗口 AddListenChat

✨移除监听聊天 RemoveListenChat

✨开始监听 StartListening

✨停止监听 StopListening

切换到聊天页面 SwitchToChat

切换到联系人页面 SwitchToContact

✨进入朋友圈 Moments

✨发送朋友圈 PublishMoment

✨获取好友申请 GetNewFriends

✨添加新的好友 AddNewFriend

✨修改好友信息 EditFriendInfo

✨获取下一个聊天窗口新消息 GetNextNewMessage

✨获取最近群聊名称列表 GetAllRecentGroups

✨发送链接卡片 SendUrlCard

✨获取历史消息 GetHistoryMessage

✨获取好友列表 GetFriendDetails

✨创建群聊 CreateGroup

✨是否在线 IsOnline

✨获取我的信息 GetMyInfo

✨获取对话框 GetDialog