11 KiB
11 KiB
WechatHookBot API 文档
WechatHookClient API 参考
基于个微大客户版 Hook API 封装的 Python 客户端。
消息发送
send_text - 发送文本消息
await client.send_text(to_wxid: str, content: str) -> bool
参数：
to_wxid: 接收者 wxid（个人或群聊）content: 文本内容
返回： 是否发送成功
示例：
await client.send_text("wxid_xxx", "你好，世界")
await client.send_text("123@chatroom", "群聊消息")
send_image - 发送图片
await client.send_image(to_wxid: str, image_path: str) -> bool
参数：
to_wxid: 接收者 wxidimage_path: 图片文件路径
支持格式： jpg, png, gif
示例：
await client.send_image("wxid_xxx", "D:/images/photo.jpg")
send_file - 发送文件
await client.send_file(to_wxid: str, file_path: str) -> bool
参数：
to_wxid: 接收者 wxidfile_path: 文件路径
示例：
await client.send_file("wxid_xxx", "D:/documents/report.pdf")
send_video - 发送视频
await client.send_video(to_wxid: str, video_path: str) -> bool
参数：
to_wxid: 接收者 wxidvideo_path: 视频文件路径
示例：
await client.send_video("wxid_xxx", "D:/videos/demo.mp4")
send_card - 发送名片
await client.send_card(to_wxid: str, card_wxid: str, card_nickname: str) -> bool
参数：
to_wxid: 接收者 wxidcard_wxid: 名片的 wxidcard_nickname: 名片昵称
示例：
await client.send_card("wxid_xxx", "wxid_yyy", "张三")
send_location - 发送位置
await client.send_location(
to_wxid: str,
latitude: float,
longitude: float,
title: str,
address: str
) -> bool
参数：
to_wxid: 接收者 wxidlatitude: 纬度longitude: 经度title: 位置标题address: 详细地址
示例：
await client.send_location(
"wxid_xxx",
39.9042,
116.4074,
"天安门",
"北京市东城区"
)
send_link - 发送链接
await client.send_link(
to_wxid: str,
title: str,
desc: str,
url: str,
thumb_url: str = ""
) -> bool
参数：
to_wxid: 接收者 wxidtitle: 链接标题desc: 链接描述url: 链接地址thumb_url: 缩略图 URL（可选）
示例：
await client.send_link(
"wxid_xxx",
"新闻标题",
"新闻摘要",
"https://example.com/news",
"https://example.com/thumb.jpg"
)
send_miniapp - 发送小程序
await client.send_miniapp(
to_wxid: str,
appid: str,
title: str,
page_path: str,
thumb_url: str = ""
) -> bool
参数：
to_wxid: 接收者 wxidappid: 小程序 appidtitle: 小程序标题page_path: 小程序页面路径thumb_url: 缩略图 URL（可选）
示例：
await client.send_miniapp(
"wxid_xxx",
"wx1234567890",
"小程序标题",
"pages/index/index"
)
send_at_message - 发送群聊@消息
await client.send_at_message(
chatroom_id: str,
content: str,
at_list: list[str]
) -> bool
参数：
chatroom_id: 群聊 IDcontent: 消息内容at_list: 要@的 wxid 列表
示例：
# @指定用户
await client.send_at_message(
"123@chatroom",
"大家好",
["wxid_aaa", "wxid_bbb"]
)
# @所有人
await client.send_at_message(
"123@chatroom",
"重要通知",
["notify@all"]
)
revoke_message - 撤回消息
await client.revoke_message(msg_id: str) -> bool
参数：
msg_id: 消息 ID
示例：
await client.revoke_message("1234567890")
好友管理
get_friend_list - 获取好友列表
await client.get_friend_list() -> list[dict]
返回： 好友列表
示例：
friends = await client.get_friend_list()
for friend in friends:
print(friend["wxid"], friend["nickname"])
get_friend_info - 获取好友信息
await client.get_friend_info(wxid: str) -> dict
参数：
wxid: 好友 wxid
返回： 好友详细信息
示例：
info = await client.get_friend_info("wxid_xxx")
print(info["nickname"], info["remark"])
search_user - 搜索用户
await client.search_user(keyword: str) -> dict
参数：
keyword: 搜索关键词（wxid、手机号、微信号）
返回： 用户信息
示例：
result = await client.search_user("wxid_xxx")
if result:
print(result["nickname"])
add_friend - 添加好友
await client.add_friend(
wxid: str,
verify_msg: str = "",
scene: int = 3
) -> bool
参数：
wxid: 要添加的 wxidverify_msg: 验证消息scene: 添加场景（3=搜索，15=名片）
示例：
await client.add_friend("wxid_xxx", "你好，我是...")
accept_friend - 同意好友请求
await client.accept_friend(v3: str, v4: str, scene: int) -> bool
参数：
v3: 好友请求的 v3 参数v4: 好友请求的 v4 参数scene: 场景值
示例：
# 从好友请求消息中获取参数
await client.accept_friend(v3, v4, scene)
delete_friend - 删除好友
await client.delete_friend(wxid: str) -> bool
参数：
wxid: 要删除的好友 wxid
示例：
await client.delete_friend("wxid_xxx")
set_friend_remark - 修改好友备注
await client.set_friend_remark(wxid: str, remark: str) -> bool
参数：
wxid: 好友 wxidremark: 新备注
示例：
await client.set_friend_remark("wxid_xxx", "张三")
check_friend_status - 检测好友状态
await client.check_friend_status(wxid: str) -> dict
参数：
wxid: 好友 wxid
返回： 好友状态信息
示例：
status = await client.check_friend_status("wxid_xxx")
print(status["is_friend"]) # 是否是好友
群聊管理
get_chatroom_list - 获取群聊列表
await client.get_chatroom_list() -> list[dict]
返回： 群聊列表
示例：
chatrooms = await client.get_chatroom_list()
for room in chatrooms:
print(room["chatroom_id"], room["name"])
get_chatroom_members - 获取群成员
await client.get_chatroom_members(chatroom_id: str) -> list[dict]
参数：
chatroom_id: 群聊 ID
返回： 群成员列表
示例：
members = await client.get_chatroom_members("123@chatroom")
for member in members:
print(member["wxid"], member["nickname"])
get_chatroom_info - 获取群信息
await client.get_chatroom_info(chatroom_id: str) -> dict
参数：
chatroom_id: 群聊 ID
返回： 群聊详细信息
示例：
info = await client.get_chatroom_info("123@chatroom")
print(info["name"], info["member_count"])
create_chatroom - 创建群聊
await client.create_chatroom(member_list: list[str]) -> str
参数：
member_list: 成员 wxid 列表（至少2人）
返回： 新群聊的 chatroom_id
示例：
chatroom_id = await client.create_chatroom(["wxid_aaa", "wxid_bbb"])
invite_to_chatroom - 邀请进群
await client.invite_to_chatroom(
chatroom_id: str,
wxid_list: list[str]
) -> bool
参数：
chatroom_id: 群聊 IDwxid_list: 要邀请的 wxid 列表
示例：
await client.invite_to_chatroom("123@chatroom", ["wxid_xxx", "wxid_yyy"])
remove_chatroom_member - 踢出群成员
await client.remove_chatroom_member(
chatroom_id: str,
wxid_list: list[str]
) -> bool
参数：
chatroom_id: 群聊 IDwxid_list: 要踢出的 wxid 列表
示例：
await client.remove_chatroom_member("123@chatroom", ["wxid_xxx"])
quit_chatroom - 退出群聊
await client.quit_chatroom(chatroom_id: str) -> bool
参数：
chatroom_id: 群聊 ID
示例：
await client.quit_chatroom("123@chatroom")
set_chatroom_name - 修改群名称
await client.set_chatroom_name(chatroom_id: str, name: str) -> bool
参数：
chatroom_id: 群聊 IDname: 新群名称
示例：
await client.set_chatroom_name("123@chatroom", "新群名")
set_chatroom_announcement - 修改群公告
await client.set_chatroom_announcement(
chatroom_id: str,
announcement: str
) -> bool
参数：
chatroom_id: 群聊 IDannouncement: 群公告内容
示例：
await client.set_chatroom_announcement("123@chatroom", "群公告内容")
set_my_chatroom_nickname - 修改我的群昵称
await client.set_my_chatroom_nickname(
chatroom_id: str,
nickname: str
) -> bool
参数：
chatroom_id: 群聊 IDnickname: 新昵称
示例：
await client.set_my_chatroom_nickname("123@chatroom", "我的群昵称")
登录信息
get_login_info - 获取当前登录信息
await client.get_login_info() -> dict
返回： 登录账号信息
示例：
info = await client.get_login_info()
print(info["wxid"], info["nickname"])
CDN 功能
cdn_upload - CDN 上传
await client.cdn_upload(file_path: str) -> dict
参数：
file_path: 文件路径
返回： CDN 信息（包含 aes_key, file_id 等）
示例：
cdn_info = await client.cdn_upload("D:/files/image.jpg")
cdn_download - CDN 下载
await client.cdn_download(
aes_key: str,
file_id: str,
save_path: str
) -> bool
参数：
aes_key: AES 密钥file_id: 文件 IDsave_path: 保存路径
示例：
await client.cdn_download(aes_key, file_id, "D:/downloads/file.jpg")
企业微信
get_work_chatroom_list - 获取企业群列表
await client.get_work_chatroom_list() -> list[dict]
get_work_friend_list - 获取企业好友列表
await client.get_work_friend_list() -> list[dict]
get_work_chatroom_members - 获取企业群成员
await client.get_work_chatroom_members(chatroom_id: str) -> list[dict]
错误处理
所有 API 调用失败时会抛出异常或返回 False/None，建议使用 try-except 处理：
try:
result = await client.send_text("wxid_xxx", "消息")
if result:
logger.info("发送成功")
else:
logger.error("发送失败")
except Exception as e:
logger.error(f"发送异常: {e}")
注意事项
- 所有 API 都是异步函数，必须使用
await调用 - wxid 格式：个人为
wxid_xxx，群聊为xxx@chatroom - 文件路径建议使用绝对路径
- 部分 API 需要特定权限（如群主才能踢人）
- API 调用频率不宜过高，避免风控