wechatbot-py-sdk 0.2.0

基于微信机器人 API 封装的 Python SDK

wechatbot-py-sdk

基于微信机器人 API 封装的 Python SDK，提供简洁易用的接口调用方式。

安装

pip install wechatbot-py-sdk

本地开发测试：

pip install -e .

快速开始

from wechatbot import WeChatBotClient

client = WeChatBotClient()
token = "your_token"

# 获取登录二维码
response = client.auth.get_qrcode(token=token)
print(response)

# 发送文本消息
response = client.message.send_text(
    to_wxid="wxid_xxxxx",
    content="Hello!",
    token=token
)
print(response)

功能模块总览

模块	属性	说明
AuthModule	client.auth	登录认证
MessageModule	client.message	消息收发
GroupModule	client.group	群聊管理
ContactModule	client.contact	联系人管理
PersonalModule	client.personal	个人信息
FavoriteModule	client.favorite	收藏夹
LabelModule	client.label	标签管理
DownModule	client.download	资源下载
SnsModule	client.sns	朋友圈
FinderModule	client.finder	视频号

Token 获取

请访问官网 www.wechatbot.online 获取 Token。

---

详细接口文档

AuthModule - 登录认证模块

client.auth

方法	说明
get_qrcode(device_type, aid, token)	获取登录二维码
refresh_status(uuid, token, cap_code)	刷新并判断登录状态
dialog_login(token)	已登录过的微信二次弹窗登录
reconnection(token)	断线重连
logout(token)	退出登录
check_status(token)	检查微信是否在线

token = "your_token"

# 1. 获取登录二维码
qr = client.auth.get_qrcode(token=token)
print(qr)  # 返回二维码信息

# 2. 轮询登录状态（用户扫码后调用）
status = client.auth.refresh_status(uuid=qr["data"]["uuid"], token=token)
print(status)

# 3. 检查是否在线
online = client.auth.check_status(token=token)
print(online)

# 4. 断线重连
client.auth.reconnection(token=token)

# 5. 退出登录
client.auth.logout(token=token)

---

MessageModule - 消息模块

client.message

方法	说明
send_text(to_wxid, content, token, at_list)	发送文本消息
send_image(to_wxid, image_url, token)	发送图片消息
send_voice(to_wxid, silk_url, voice_duration, token)	发送语音消息
send_audio(to_wxid, audio_url, thumb_url, video_duration, token)	发送视频消息
send_file(to_wxid, file_name, file_url, token)	发送文件消息
send_link(to_wxid, title, desc, link, thumb_url, token)	发送链接消息
send_card(to_wxid, nickname, target_wxid, token)	发送名片消息
send_emoji(to_wxid, md5, size, token)	发送表情消息
send_app(to_wxid, app_msg, token)	发送APP消息
send_miniapp(to_wxid, mini_appid, username, title, img_url, page_url, dis_title, token)	发送小程序消息
send_location(to_wxid, content, token)	发送位置消息
revoke_msg(to_wxid, msg_id, new_msgid, create_time, token)	撤回消息
forward_file(to_wxid, xml, token)	转发文件
forward_image(to_wxid, xml, token)	转发图片
forward_video(to_wxid, xml, token)	转发视频
forward_link(to_wxid, xml, token)	转发链接
forward_miniapp(to_wxid, xml, cover_img_url, token)	转发小程序

token = "your_token"
to = "wxid_xxxxx"

# 发送文本（群聊中@某人）
client.message.send_text(to, "大家好", token, at_list=["wxid_aaa"])

# 发送图片
client.message.send_image(to, "https://example.com/pic.jpg", token)

# 发送语音（silk格式）
client.message.send_voice(to, "https://example.com/voice.silk", 5000, token)

# 发送视频
client.message.send_audio(to, "https://example.com/video.mp4", "https://example.com/thumb.jpg", 15, token)

# 发送文件
client.message.send_file(to, "report.pdf", "https://example.com/report.pdf", token)

# 发送链接卡片
client.message.send_link(to, "文章标题", "文章描述", "https://example.com/article", "https://example.com/thumb.jpg", token)

# 发送名片
client.message.send_card(to, "张三", "wxid_zhangsan", token)

# 撤回消息（需要发送接口返回的msgId、newMsgId、createTime）
client.message.revoke_msg(to, "msg_id", "new_msg_id", 1700000000, token)

# 转发文件（xml从回调消息中获取）
client.message.forward_file(to, "<xml>...</xml>", token)

---

GroupModule - 群聊管理模块

client.group

方法	说明
create_group(ids_list, token)	创建群聊
modify_group_name(room_name, room_id, token)	修改群名
modify_group_remark(room_remark, room_id, token)	修改群备注
modify_self_nickname_in_group(nickname, room_id, token)	修改我在群内的昵称
invite_group_member(ids, room_id, reason, token)	邀请/添加进群
remove_group(ids, room_id, token)	移出群聊
quit_group(room_id, token)	退出群聊
disband_group(room_id, token)	解散群聊
group_info(room_id, token)	获取群信息
group_member(room_id, token)	获取群成员列表
group_member_detail(room_id, member_list, token)	获取群成员详情
get_announcement(room_id, token)	获取群公告
set_announcement(room_id, announcement, token)	设置群公告
agree_join_group(url, token)	同意进群
add_group_member_as_friend(room_id, content, member_wxid, token)	添加群成员为好友
get_group_qr(room_id, token)	获取群二维码
save_contract_list(room_id, opertype, token)	群保存到通讯录
admin_operate(room_id, opertype, ids_list, token)	管理员操作
pinned_chat(room_id, bool_type, token)	聊天置顶
set_msg_silence(room_id, bool_type, token)	设置消息免打扰
us_qr_join_group(qr_url, token)	扫码进群
apply_group_approve(room_id, content, msg_id, token)	确认进群申请

token = "your_token"
room_id = "xxxxx@chatroom"

# 创建群聊（至少3人）
client.group.create_group(["wxid_aaa", "wxid_bbb", "wxid_ccc"], token)

# 修改群名
client.group.modify_group_name("新群名", room_id, token)

# 邀请好友进群（多个wxid用逗号隔开）
client.group.invite_group_member("wxid_ddd,wxid_eee", room_id, "欢迎加入", token)

# 移出群成员
client.group.remove_group("wxid_ddd", room_id, token)

# 获取群信息
info = client.group.group_info(room_id, token)

# 获取群成员详情
detail = client.group.group_member_detail(room_id, ["wxid_aaa", "wxid_bbb"], token)

# 设置群公告
client.group.set_announcement(room_id, "本群规则：...", token)

# 管理员操作（1:添加管理 2:删除管理 3:转让群主）
client.group.admin_operate(room_id, 1, ["wxid_aaa"], token)

# 聊天置顶 / 消息免打扰
client.group.pinned_chat(room_id, True, token)
client.group.set_msg_silence(room_id, True, token)

# 群保存到通讯录（3:保存 2:移除）
client.group.save_contract_list(room_id, 3, token)

---

ContactModule - 联系人模块

client.contact

方法	说明
contacts_list(token)	获取通讯录列表（长耗时）
contacts_list_cache(token)	获取通讯录列表缓存
brief_info(ids, token)	获取群/好友简要信息（最大20个）
detail_info(ids, token)	获取群/好友详细信息（最大20个）
search_friend(contacts_info, token)	搜索好友
add_contacts(scene, content, v4, v3, option, token)	添加联系人/同意添加好友
delete_friend(wx_id, token)	删除好友
set_friend_permissions(wx_id, only_chat, token)	设置好友仅聊天
set_friend_remark(wx_id, remark, token)	设置好友备注
get_phone_list(token, p_list)	获取手机通讯录
upload_phone_list(p_list, op_type, token)	上传手机通讯录
im_search(scene, content, token)	搜索企微
add_im_friends(v3, v4, token)	添加企微好友
sync_im_friends(token)	同步企微好友
detail_im_friends(to_username, token)	获取企微好友详情
check_relation(ids, token)	检测好友关系

token = "your_token"

# 获取通讯录（使用缓存版本更快）
contacts = client.contact.contacts_list_cache(token)

# 获取好友详细信息
detail = client.contact.detail_info(["wxid_aaa", "wxid_bbb"], token)

# 搜索好友（微信号、手机号）
result = client.contact.search_friend("13800138000", token)

# 添加好友（scene: 3微信号 4QQ 8群聊 15手机号；option: 2添加 3同意 4拒绝）
client.contact.add_contacts(
    scene=3, content="你好，我是xxx",
    v4="v4_value", v3="v3_value", option=2, token=token
)

# 设置好友备注
client.contact.set_friend_remark("wxid_aaa", "张三-同事", token)

# 检测好友关系（最多20个）
client.contact.check_relation(["wxid_aaa", "wxid_bbb"], token)

# 删除好友
client.contact.delete_friend("wxid_aaa", token)

---

PersonalModule - 个人信息模块

client.personal

方法	说明
get_info(token)	获取个人资料
get_qrcode(token)	获取自己的二维码
get_device_record(token)	获取使用设备记录
privacy_settings(boolean_style, option, token)	隐私设置
update_info(city, country, nickname, province, sex, signature, token)	修改个人资料
update_head_img(img_url, token)	修改头像

隐私设置 option 说明：

• 4 - 加我为朋友时需要验证
• 7 - 向我推荐通讯录朋友
• 8 - 添加我的方式：手机号
• 25 - 添加我的方式：微信号
• 38 - 添加我的方式：群聊
• 39 - 添加我的方式：我的二维码
• 40 - 添加我的方式：名片

token = "your_token"

# 获取个人资料
info = client.personal.get_info(token)

# 获取自己的二维码
qr = client.personal.get_qrcode(token)

# 修改个人资料
client.personal.update_info(
    city="Shanghai", country="CN", nickname="新昵称",
    province="Shanghai", sex=1, signature="个性签名", token=token
)

# 修改头像
client.personal.update_head_img("https://example.com/avatar.jpg", token)

# 隐私设置（开启加我为朋友时需要验证）
client.personal.privacy_settings(True, 4, token)

---

FavoriteModule - 收藏夹模块

client.favorite

方法	说明
sync_favorite(sync_key, token)	同步收藏夹（翻页key，首次传空）
get_favorite(fav_id, token)	获取收藏夹内容
delete_favorite(fav_id, token)	删除收藏夹

token = "your_token"

# 同步收藏夹（首次传空，翻页传返回的syncKey）
favs = client.favorite.sync_favorite("", token)

# 获取某条收藏内容
content = client.favorite.get_favorite(12345, token)

# 删除收藏
client.favorite.delete_favorite(12345, token)

---

LabelModule - 标签管理模块

client.label

方法	说明
add_label(label_name, token)	添加标签
list_label(token)	获取标签列表
delete_label(label_ids, token)	删除标签（多个ID逗号分隔）
modify_friend_label(label_ids, wx_ids, token)	修改好友标签

token = "your_token"

# 添加标签
client.label.add_label("同事", token)

# 获取标签列表
labels = client.label.list_label(token)

# 给好友打标签（多个标签ID逗号分隔）
client.label.modify_friend_label("1,2", ["wxid_aaa", "wxid_bbb"], token)

# 删除标签
client.label.delete_label("1,2", token)

---

DownModule - 资源下载模块

client.download

方法	说明
down_load_silk_base64(img_buf_base64, save_path)	下载语音文件（Base64解码保存本地）
down_load_silk_request(msg_id, xml, token)	下载语音文件（接口请求）
down_load_files(xml, token)	下载文件
down_load_images(img_type, xml, token)	下载图片
down_load_audio(xml, token)	下载视频
down_load_emoji(emoji_md5, token)	下载表情
down_load_cdn(aes_key, total_size, file_type, file_id, suffix, token)	CDN下载

图片类型 img_type：1 高清图片 / 2 常规图片 / 3 缩略图

CDN文件类型 file_type：1 高清图片 / 2 常规图片 / 3 缩略图 / 4 视频 / 5 文件

token = "your_token"

# 下载图片（xml从回调消息获取）
result = client.download.down_load_images(1, "<xml>...</xml>", token)

# 下载视频
result = client.download.down_load_audio("<xml>...</xml>", token)

# 下载文件
result = client.download.down_load_files("<xml>...</xml>", token)

# 下载表情
result = client.download.down_load_emoji("emoji_md5_value", token)

# CDN下载
result = client.download.down_load_cdn("aes_key", "1024000", "4", "file_id", "mp4", token)

# 语音Base64解码保存到本地
client.download.down_load_silk_base64("base64_string", "./voice.silk")

---

SnsModule - 朋友圈模块

client.sns

方法	说明
sns_list(max_id, decrypt, first_page_md5, token)	我的朋友圈列表
friends_sns_list(max_id, decrypt, wx_id, first_page_md5, token)	指定好友的朋友圈列表
sns_details(sns_id, token)	某条朋友圈详情
sns_like(sns_id, ope_type, wx_id, token)	点赞/取消点赞
sns_comment(sns_id, ope_type, wx_id, comment_id, content, token)	评论/删除评论
sns_delete(sns_id, token)	删除朋友圈
sns_scope(option, token)	设置朋友圈可见范围
sns_visibility_enable(enabled, token)	是否允许陌生人查看朋友圈
sns_set_status(sns_id, open_s, token)	设置某条朋友圈为隐私/公开
sns_download_video(sns_xml, token)	下载朋友圈视频
sns_send_text(allow_ids, at_ids, disable_ids, content, privacy, allow_tag_ids, disable_tag_ids, token)	发送文字朋友圈
sns_send_img(...)	发送图片朋友圈
sns_upload_image(urls, token)	上传朋友圈图片（1-9张）
sns_send_video(...)	发送视频朋友圈
sns_upload_video(thumb_url, video_url, token)	上传朋友圈视频
sns_send_url(...)	发送链接朋友圈
sns_forward(...)	转发朋友圈

朋友圈可见范围 option：1 全部 / 2 最近半年 / 3 最近一个月 / 4 最近三天

注意：发送朋友圈相关接口建议上号 1-3 天后再使用。

token = "your_token"

# 获取我的朋友圈（首次max_id=0，翻页传返回的maxId）
sns = client.sns.sns_list(0, True, "", token)

# 获取指定好友的朋友圈
friend_sns = client.sns.friends_sns_list(0, True, "wxid_aaa", "", token)

# 发送文字朋友圈
client.sns.sns_send_text(
    allow_ids=[],       # 允许谁看，空=所有人
    at_ids=[],          # 提醒谁看
    disable_ids=[],     # 不给谁看
    content="今天天气真好！",
    privacy=False,      # 是否私密
    allow_tag_ids=[],   # 允许谁看（标签id）
    disable_tag_ids=[], # 不给谁看（标签id）
    token=token
)

# 发送图片朋友圈（先上传图片获取信息）
upload = client.sns.sns_upload_image(["https://example.com/photo.jpg"], token)
# 然后用返回的信息发布
client.sns.sns_send_img(
    allow_ids=[], at_ids=[], disable_ids=[],
    content="分享一张照片",
    file_url="uploaded_file_url",
    thumb_url="uploaded_thumb_url",
    file_md5="md5_value",
    length=102400, width=1080, height=1920,
    privacy=False,
    allow_tag_ids=[], disable_tag_ids=[],
    token=token
)

# 发送视频朋友圈（先上传视频）
upload = client.sns.sns_upload_video("https://example.com/thumb.jpg", "https://example.com/video.mp4", token)
client.sns.sns_send_video(
    allow_ids=[], at_ids=[], disable_ids=[],
    content="分享一个视频",
    file_url="uploaded_video_url",
    thumb_url="uploaded_thumb_url",
    file_md5="md5_value",
    length=5242880,
    privacy=False,
    allow_tag_ids=[], disable_tag_ids=[],
    token=token
)

# 发送链接朋友圈
client.sns.sns_send_url(
    allow_ids=[], at_ids=[], disable_ids=[],
    content="推荐一篇文章",
    description="文章描述",
    title="文章标题",
    link_url="https://example.com/article",
    thumb_url="https://example.com/thumb.jpg",
    privacy=False,
    allow_tag_ids=[], disable_tag_ids=[],
    token=token
)

# 点赞（ope_type: 1点赞 2取消）
client.sns.sns_like(123456, 1, "wxid_aaa", token)

# 评论（ope_type: 1评论 2删除评论）
client.sns.sns_comment(123456, 1, "wxid_aaa", 0, "写得真好！", token)

# 设置朋友圈可见范围
client.sns.sns_scope(1, token)

# 是否允许陌生人查看朋友圈
client.sns.sns_visibility_enable(False, token)

---

FinderModule - 视频号模块

client.finder

方法	说明
create_finder(proxy_ip, signature, head_img, nick_name, sex, token)	创建视频号
get_profile(token, proxy_ip)	获取我的视频号信息
update_profile(my_username, my_role_type, token, ...)	修改我的视频号信息
get_qr_code(my_username, my_role_type, token, proxy_ip)	获取我的视频号二维码
finder_search(content, token, ...)	搜索视频号
follow(my_username, my_role_type, op_type, to_username, token, ...)	关注/取消关注
follow_list(my_username, my_role_type, token, ...)	关注列表
search_follow(my_username, my_role_type, to_username, keyword, token)	搜索并关注
scan_follow(my_username, my_role_type, qr_content, token, ...)	扫码关注
user_page(to_username, token, ...)	用户主页
comment(my_username, op_type, object_nonce_id, session_buffer, object_id, my_role_type, content, comment_id, token, ...)	评论/删除评论
comment_list(session_buffer, object_id, token, ...)	评论列表
browse(my_username, object_nonce_id, session_buffer, object_id, my_role_type, token, ...)	浏览视频
publish_finder_web(title, video_url, thumb_url, description, token)	发布视频（新）
upload_finder_video(video_url, cover_img_url, token, proxy_ip)	上传CDN视频
publish_finder_cdn(my_username, my_role_type, description, video_cdn, token, ...)	发布CDN视频
mention_list(my_username, my_role_type, req_scene, token, ...)	消息列表
like_fav_list(my_username, my_role_type, flag, token, ...)	获取赞与收藏的视频列表
id_fav(my_username, op_type, ..., token)	根据id点赞
id_like(my_username, op_type, ..., token)	根据id点小红心
finder_opt(my_username, my_role_type, to_username, op_type, vid_id, remain, token)	延迟点赞/小红心
send_finder_msg(to_wxid, vid_id, username, ..., token)	发送视频号消息
send_finder_sns(allow_wx_ids, at_wx_ids, disable_wx_ids, ..., token)	发送视频号朋友圈
sync_private_letter_msg(token, proxy_ip, key_buff)	同步私信消息
contact_list(my_username, query_info, my_role_type, token, ...)	获取私信人信息
post_private_letter(content, msg_session_id, my_username, to_username, token, ...)	发私信文本消息
post_private_letter_img(img_url, msg_session_id, my_username, to_username, token, ...)	发私信图片消息
scan_browse(my_username, my_role_type, qr_content, object_id, token, ...)	扫码浏览
scan_comment(my_username, my_role_type, qr_content, object_id, comment_content, token, ...)	扫码评论
scan_fav(my_username, my_role_type, qr_content, object_id, token, ...)	扫码点赞
scan_like(my_username, my_role_type, qr_content, object_id, token, ...)	扫码点小红心
scan_login_channels(qr_content, token, proxy_ip)	扫码登录视频号助手
scan_qr_code(my_username, my_role_type, qr_content, token, ...)	扫码获取视频详情

消息列表 req_scene：3 点赞 / 4 评论 / 5 关注

赞与收藏 flag：7 全部 / 1 红心 / 2 大拇指 / 4 收藏

token = "your_token"

# 获取我的视频号信息
profile = client.finder.get_profile(token)
my_username = profile["data"]["mainFinderUsername"]

# 获取我的视频号二维码
qr = client.finder.get_qr_code(my_username, 3, token)

# 搜索视频号
results = client.finder.finder_search("人民日报", token, category=1)

# 获取用户主页
page = client.finder.user_page("v2_xxx@finder", token)

# 关注（op_type: 1关注 2取消关注）
client.finder.follow(my_username, 3, 1, "v2_target@finder", token)

# 获取关注列表
follows = client.finder.follow_list(my_username, 3, token)

# 浏览视频
client.finder.browse(my_username, "nonce_id", "session_buffer", 14195037502970006000, 3, token)

# 评论（op_type: 0评论 1删除评论）
client.finder.comment(
    my_username, 0, "nonce_id", "session_buffer",
    14195037502970006000, 3, "评论内容", "", token
)

# 根据id点赞（op_type: 1点赞 2取消）
client.finder.id_fav(my_username, 1, "nonce_id", "session_buffer", 14195037502970006000, "v2_target@finder", 3, token)

# 根据id点小红心（op_type: 3喜欢 4不喜欢）
client.finder.id_like(my_username, 3, "nonce_id", "session_buffer", 14195037502970006000, "v2_target@finder", 3, token)

# 发布视频（新接口，需ipad协议）
client.finder.publish_finder_web("视频标题", "https://video_url", "https://thumb_url", "#话题", token)

# 上传CDN视频 + 发布CDN视频（适合多号批量发布）
cdn_info = client.finder.upload_finder_video("https://video_url", "https://cover_url", token)
client.finder.publish_finder_cdn(
    my_username, 3, "视频描述",
    video_cdn=cdn_info["data"],  # 上传接口返回的cdn信息
    token=token,
    topic=["#话题1", "#话题2"]
)

# 扫码操作（qr_content从视频号助手获取）
client.finder.scan_browse(my_username, 3, "https://weixin.qq.com/sph/xxx", 14195037502970006000, token)
client.finder.scan_fav(my_username, 3, "https://weixin.qq.com/sph/xxx", 14195037502970006000, token)
client.finder.scan_comment(my_username, 3, "https://weixin.qq.com/sph/xxx", 14195037502970006000, "好看！", token)

# 私信功能
contact = client.finder.contact_list(my_username, "v2_target@finder", 3, token)
session_id = contact["data"]["msgInfo"]["sessionId"]
client.finder.post_private_letter("你好", session_id, my_username, "v2_target@finder", token)
client.finder.post_private_letter_img("https://img_url", session_id, my_username, "v2_target@finder", token)

# 获取消息列表（req_scene: 3点赞 4评论 5关注）
mentions = client.finder.mention_list(my_username, 3, 4, token)

# 获取赞与收藏的视频列表（flag: 7全部 1红心 2大拇指 4收藏）
liked = client.finder.like_fav_list(my_username, 3, 7, token)

---

环境要求

• Python >= 3.6
• requests >= 2.25.1

许可证

MIT License