基于WeChatBot框架 API 封装的 Python SDK，提供简洁易用的接口调用方式

支持Go，java，node.js

bash 复制代码

https://github.com/oocsoo/wechatbot-node-sdk
https://github.com/oocsoo/wechatbot-java-sdk
https://github.com/oocsoo/wechatbot-go-sdk

安装

bash 复制代码

pip install wechatbot-py-sdk

快速开始

python 复制代码

from wechatbot import WeChatBotClient

client = WeChatBotClient()
token = "your_token"

# 发送文本消息
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)`	检查微信是否在线

python 复制代码

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)`	转发小程序

python 复制代码

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)`	确认进群申请

python 复制代码

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)`	检测好友关系

python 复制代码

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 - 添加我的方式：名片

python 复制代码

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)`	删除收藏夹

python 复制代码

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)`	修改好友标签

python 复制代码

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 文件

python 复制代码

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 天后再使用。

python 复制代码

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 收藏

python 复制代码

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