Chat

聊天区域操作类，提供消息发送、消息读取、群聊管理、联系人管理等功能。

属性

属性	类型	说明
chat_name	str | None	当前聊天名称
nickname	str | None	联系人昵称（备注优先）
remark	str | None	备注名
member_count	int | None	群成员数（仅群聊）
chat_type	str	聊天类型："contact" / "room"

消息发送

send_text(content, quote=None, timeout=0)

发送文本消息。

• content str — 文本内容
• quote Message | int | None — 引用的消息或 msg_id
• timeout float — 发送状态检测超时（秒），0 不等待
• 返回 MessageStatus

send_file(file_path, quote=None, timeout=0)

发送文件。

• file_path str | List[str] — 文件路径或路径列表，支持 URL
• 返回 MessageStatus

send_image(file_path, quote=None, timeout=0)

发送图片。

• file_path str | List[str] — 图片路径或路径列表，支持 URL
• 返回 MessageStatus

send_video(file_path, quote=None, timeout=0)

发送视频。

• file_path str | List[str] — 视频路径或路径列表，支持 URL
• 返回 MessageStatus

send_at(content, at_members, quote=None, timeout=0)

发送@消息（群聊）。

• content str — 文本内容
• at_members List[str] — 要@的成员，["所有人"] 可@全员
• 返回 MessageStatus

send_emotion(keyword=None, index=1, quote=None, timeout=0)

发送表情。

• keyword str | None — 搜索关键词，None 发送自定义表情
• index int — 第几个表情（从 1 开始）
• 返回 MessageStatus

send_collection(keyword, quote=None, timeout=0)

发送收藏内容。

• keyword str — 收藏搜索关键词
• 返回 MessageStatus

send_card(receiver_nickname)

将当前聊天联系人的名片发送给指定接收者。

• receiver_nickname str — 接收名片的联系人
• 返回 bool

消息读取

get_visible_messages(sender_cache=None)

获取当前消息列表中可见的所有消息。

• sender_cache Dict[int, tuple] | None — 发送者缓存（用于跨调用加速 OCR）
• 返回 List[Message]

iter_recently_messages(count=None)

从最新到最旧逐条遍历消息（通过滚动）。

• count int | None — 最多获取条数，None 获取所有
• Yields Message

page_end()

滚动消息列表到底部（最新消息）。

message_view_rect()

获取消息列表区域的矩形坐标。

• 返回 Tuple[int, int, int, int] — (left, top, right, bottom)

输入框操作

clear_input()

清空输入框内容。

paste_input(content)

将内容粘贴到输入框。

• content str | List[str] — 文本或文件路径列表

cancel_quote()

取消当前引用。

• 返回 bool — 是否成功取消

通话

voice_call()

发起语音通话。

• 返回 VoipCall

video_call()

发起视频通话。

• 返回 VoipCall

独立窗口

separate()

将当前聊天分离为独立窗口。

• 返回 SeparateChat

群聊管理

set_room_info(name=None, announcement=None, remark=None, ...)

一次性设置群聊信息。

参数（均可选）：

• name str — 群名
• announcement str — 群公告
• remark str — 群备注
• nickname str — 我在群里的昵称
• pin bool — 置顶
• mute bool — 免打扰
• fold bool — 折叠
• show_member_nickname bool — 显示群成员昵称
• save_to_contacts bool — 保存到通讯录

set_room_name(name)

设置群名称。

set_room_announcement(content)

设置群公告。

set_room_remark(remark)

设置群备注名。

set_room_nickname(nickname)

设置我的群昵称。

add_room_members(members)

添加群成员。

• members List[str] — 要添加的联系人列表

remove_room_members(members)

移除群成员。

• members List[str] — 要移除的成员列表

exit_room()

退出群聊。

clear_room_chat_history()

清空群聊天记录。

pin_room_chat() / unpin_room_chat()

群聊置顶 / 取消置顶。

mute_room_chat() / unmute_room_chat()

群消息免打扰。

fold_room_chat() / unfold_room_chat()

折叠 / 取消折叠群聊。

add_room_address_book() / remove_room_address_book()

保存到 / 移出通讯录。

display_room_member_nickname() / hidden_room_member_nickname()

显示 / 隐藏群成员昵称。

联系人管理

get_contact_profile()

获取当前聊天联系人的资料。

• 返回 dict

set_contact_info(*, remark=None, labels=None, phones=None, description=None, images=None)

一次性设置联系人信息。

set_contact_remark(remark)

设置备注名。

add_contact_label(labels) / remove_contact_label(labels)

添加 / 移除标签。

add_contact_phone(phones) / remove_contact_phone(phones)

添加 / 移除电话。

add_contact_image(images) / remove_contact_image(indexes)

添加 / 移除图片描述。

set_contact_star() / cancel_contact_star()

设为 / 取消星标朋友。

black_contact() / unblack_contact()

加入 / 移出黑名单。

delete_contact()

删除联系人。

get_friend_permission()

获取朋友权限设置。

• 返回 dict

set_friend_permission(permission="all", hide_my_posts=False, hide_their_posts=False)

设置朋友权限。

• permission "all" | "chatonly" — 权限级别

recommend_contact(receiver_nickname)

推荐该联系人给其他人。

• 返回 bool

通用操作

pin_chat() / unpin_chat()

置顶 / 取消置顶聊天（自动区分群聊和联系人）。

mute_chat() / unmute_chat()

免打扰 / 允许通知。

fold_chat() / unfold_chat()

折叠 / 取消折叠。

is_pinned()

检查是否已置顶。

• 返回 bool

is_muted()

检查是否已免打扰。

• 返回 bool

clear_chat_history()

清空聊天记录。

示例

from pywxauto import Weixin

wx = Weixin()
chat = wx.chat_with("工作群")

# 发送消息
chat.send_text("大家好")
chat.send_at("开会了", at_members=["张三", "李四"])

# 读取消息
messages = chat.get_visible_messages()
for msg in messages:
    print(f"[{msg.type_label}] {msg.sender}: {msg.content}")

# 群管理
chat.set_room_name("项目组")
chat.add_room_members(["新同事"])