Client¶

微信 API 操作类，有部分接口暂未实现，可自行调用微信接口。

开始开发¶

获取 access token¶

详细请参考微信开放文档

Client.grant_token()¶

获取 Access Token。

返回:

返回的 JSON 数据包

正常时返回 {"access_token":"ACCESS_TOKEN", "expires_in":7200}

错误时返回 {"errcode":40013,"errmsg":"invalid appid"}

Client.get_access_token() → str¶

判断现有的token是否过期。用户需要多进程或者多机部署可以手动重写这个函数来自定义token的存储，刷新策略。

返回:: 返回 token

备注

Client 的操作都会自动进行 access token 的获取和过期刷新操作，如果有特殊需求（如多进程部署）可重写 get_access_token。

获取微信服务器IP地址¶

详细请参考微信开放文档

Client.get_ip_list()¶

获取微信服务器IP地址。

返回:

返回的 JSON 数据包

正常时返回 {"ip_list": ["127.0.0.1", "127.0.0.2", "101.226.103.0/25"]}

错误时返回 {"errcode":40013,"errmsg":"invalid appid"}

自定义菜单¶

自定义菜单创建接口¶

详细请参考微信开放文档

Client.create_menu(menu_data)¶

创建自定义菜单:

client.create_menu({
    "button":[
        {
            "type":"click",
            "name":"今日歌曲",
            "key":"V1001_TODAY_MUSIC"
        },
        {
            "type":"click",
            "name":"歌手简介",
            "key":"V1001_TODAY_SINGER"
        },
        {
            "name":"菜单",
            "sub_button":[
                {
                    "type":"view",
                    "name":"搜索",
                    "url":"http://www.soso.com/"
                },
                {
                    "type":"view",
                    "name":"视频",
                    "url":"http://v.qq.com/"
                },
                {
                    "type":"click",
                    "name":"赞一下我们",
                    "key":"V1001_GOOD"
                }
            ]
        }
    ]})

参数:

menu_data -- Python 字典

返回:

返回的 JSON 数据包

正确时返回 {"errcode":0,"errmsg":"ok"}

错误时返回 {"errcode":40018,"errmsg":"invalid button name size"}

自定义菜单获取自定义菜单配置¶

详细请参考微信开放文档

Client.get_menu()¶

查询自定义菜单。

返回:: 返回的 JSON 数据包

自定义菜单删除接口¶

详细请参考微信开放文档

Client.delete_menu()¶

删除自定义菜单。

返回:

返回的 JSON 数据包

正确时返回 {"errcode":0,"errmsg":"ok"}

自定义菜单个性化菜单接口¶

详细请参考微信开放文档

Client.create_custom_menu(menu_data, matchrule)¶

创建个性化菜单:

button = [
    {
        "type":"click",
        "name":"今日歌曲",
        "key":"V1001_TODAY_MUSIC"
    },
    {
        "name":"菜单",
        "sub_button":[
        {
            "type":"view",
            "name":"搜索",
            "url":"http://www.soso.com/"
        },
        {
            "type":"view",
            "name":"视频",
            "url":"http://v.qq.com/"
        },
        {
            "type":"click",
            "name":"赞一下我们",
            "key":"V1001_GOOD"
        }]
 }]
 matchrule = {
    "group_id":"2",
    "sex":"1",
    "country":"中国",
    "province":"广东",
    "city":"广州",
    "client_platform_type":"2",
    "language":"zh_CN"
}
client.create_custom_menu(button, matchrule)

参数:

menu_data -- 如上所示的 Python 字典
matchrule -- 如上所示的匹配规则

返回:

返回的 JSON 数据包

正确时返回 {"menuid":"208379533"}

错误时的返回码请见接口返回码说明.

Client.delete_custom_menu(menu_id)¶

删除个性化菜单。

参数:

menu_id -- 菜单的 ID

返回:

返回的 JSON 数据包

正确时返回 {"errcode":0,"errmsg":"ok"}

错误时的返回码请见接口返回码说明。

Client.match_custom_menu(user_id)¶

测试个性化菜单匹配结果。

参数:: user_id -- 要测试匹配的用户 ID，也可以是用户的微信号
返回:: 返回的 JSON 数据包

获取自定义菜单配置接口¶

详细请参考微信开放文档

Client.get_custom_menu_config()¶

获取自定义菜单配置接口。

返回:: 返回的 JSON 数据包

消息管理¶

客服接口¶

详细请参考微信开放文档

发送卡券接口暂时未支持。可自行实现。

Client.add_custom_service_account(account, nickname)¶

添加客服帐号。

参数:

account -- 客服账号的用户名
nickname -- 客服账号的昵称

返回:

返回的 JSON 数据包

Client.update_custom_service_account(account, nickname, password)¶

修改客服帐号。

参数:

account -- 客服账号的用户名
nickname -- 客服账号的昵称
password -- 客服账号的密码

返回:

返回的 JSON 数据包

Client.delete_custom_service_account(account, nickname, password)¶

删除客服帐号。

参数:

account -- 客服账号的用户名
nickname -- 客服账号的昵称
password -- 客服账号的密码

返回:

返回的 JSON 数据包

Client.upload_custom_service_account_avatar(account, avatar)¶

设置客服帐号的头像。

参数:

account -- 客服账号的用户名
avatar -- 头像文件，必须是 jpg 格式

返回:

返回的 JSON 数据包

Client.get_custom_service_account_list()¶

获取所有客服账号。

返回:: 返回的 JSON 数据包

Client.get_online_custom_service_account_list()¶

获取状态为"在线"的客服账号列表。

返回:: 返回的 JSON 数据包

Client.send_text_message(user_id, content, kf_account=None)¶

发送文本消息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
content -- 消息正文
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_image_message(user_id, media_id, kf_account=None)¶

发送图片消息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
media_id -- 图片的媒体ID。可以通过 upload_media() 上传。
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_voice_message(user_id, media_id, kf_account=None)¶

发送语音消息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
media_id -- 发送的语音的媒体ID。可以通过 upload_media() 上传。
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_video_message(user_id, media_id, title=None, description=None, kf_account=None)¶

发送视频消息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
media_id -- 发送的视频的媒体ID。可以通过 upload_media() 上传。
title -- 视频消息的标题
description -- 视频消息的描述
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_music_message(user_id, url, hq_url, thumb_media_id, title=None, description=None, kf_account=None)¶

发送音乐消息。注意如果你遇到了缩略图不能正常显示的问题，不要慌张；目前来看是微信服务器端的问题。对此我们也无能为力 ( #197 )

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
url -- 音乐链接
hq_url -- 高品质音乐链接，wifi环境优先使用该链接播放音乐
thumb_media_id -- 缩略图的媒体ID。可以通过 upload_media() 上传。
title -- 音乐标题
description -- 音乐描述
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_article_message(user_id, articles, kf_account=None)¶

发送图文消息:

articles = [
    {
        "title":"Happy Day",
        "description":"Is Really A Happy Day",
        "url":"URL",
        "picurl":"PIC_URL"
    },
    {
        "title":"Happy Day",
        "description":"Is Really A Happy Day",
        "url":"URL",
        "picurl":"PIC_URL"
    }
]
client.send_acticle_message("user_id", acticles)

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
articles -- 一个包含至多8个 article 字典或 Article 对象的数组
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_news_message(user_id, media_id, kf_account=None)¶

发送永久素材中的图文消息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
media_id -- 媒体文件 ID
kf_account -- 发送消息的客服账户，默认值为 None，None 为不指定

返回:

返回的 JSON 数据包

Client.send_miniprogrampage_message(user_id, title, appid, pagepath, thumb_media_id, kf_account=None)¶

发送小程序卡片（要求小程序与公众号已关联）

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
title -- 小程序卡片的标题
appid -- 小程序的 appid，要求小程序的 appid 需要与公众号有关联关系
pagepath -- 小程序的页面路径，跟 app.json 对齐，支持参数，比如 pages/index/index?foo=bar
thumb_media_id -- 小程序卡片图片的媒体 ID，小程序卡片图片建议大小为 520*416
kf_account -- 需要以某个客服帐号来发消息时指定的客服账户

返回:

返回的 JSON 数据包

群发接口¶

Client.send_mass_msg(msg_type, content, user_list=None, send_ignore_reprint=False, client_msg_id=None)¶

向指定对象群发信息。

参数:

msg_type -- 群发类型，图文消息为 mpnews，文本消息为 text，语音为 voice，音乐为 music，图片为 image，视频为 video，卡券为 wxcard。
content -- 群发内容。
user_list -- 发送对象，整型代表用户组，列表代表指定用户，如果为 None 则代表全部发送。
send_ignore_reprint -- 图文消息被判定为转载时，是否继续群发。 True 为继续群发（转载），False 为停止群发。该参数默认为 False。
client_msg_id -- 群发时，微信后台将对 24 小时内的群发记录进行检查，如果该 clientmsgid 已经存在一条群发记录，则会拒绝本次群发请求，返回已存在的群发 msgid, 控制再 64 个字符内。

返回:

返回的 JSON 数据包。

Client.delete_mass_msg(msg_id, article_idx=0)¶

群发之后，随时可以通过该接口删除群发。

参数:

msg_id -- 发送出去的消息 ID。
article_idx -- 要删除的文章在图文消息中的位置，第一篇编号为 1，该字段不填或填 0 会删除全部文章。

返回:

微信返回的 json 数据。

Client.send_mass_preview_to_user(msg_type, content, user, user_type='openid')¶

开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求，在保留对 openID 预览能力的同时，增加了对指定微信号发送预览的能力，但该能力每日调用次数有限制（100 次），请勿滥用。

参数:

user_type -- 预览对象，openid 代表以 openid 发送，wxname 代表以微信号发送。
msg_type -- 发送类型，图文消息为 mpnews，文本消息为 text，语音为 voice，音乐为 music，图片为 image，视频为 video，卡券为 wxcard。
content -- 预览内容。
user -- 预览用户。

返回:

返回的 json。

Client.get_mass_msg_status(msg_id)¶

查询群发消息发送状态。

参数:: msg_id -- 群发消息后返回的消息 id。
返回:: 返回的 json。

Client.get_mass_msg_speed()¶

获取群发速度。

返回:: 返回的 json。

用户管理¶

用户分组管理¶

详细请参考微信开放文档

Client.create_group(name)¶

创建分组。

参数:: name -- 分组名字（30个字符以内）
返回:: 返回的 JSON 数据包

Client.get_groups()¶

查询所有分组。

返回:: 返回的 JSON 数据包

Client.get_group_by_id(openid)¶

查询用户所在分组。

参数:: openid -- 用户的OpenID
返回:: 返回的 JSON 数据包

Client.update_group(group_id, name)¶

修改分组名。

参数:

group_id -- 分组 ID，由微信分配
name -- 分组名字（30个字符以内）

返回:

返回的 JSON 数据包

Client.move_user(user_id, group_id)¶

移动用户分组。

参数:

user_id -- 用户 ID，即收到的 Message 的 source
group_id -- 分组 ID

返回:

返回的 JSON 数据包

Client.move_users(user_id_list, group_id)¶

批量移动用户分组。

参数:

user_id_list -- 用户 ID 的列表（长度不能超过50）
group_id -- 分组 ID

返回:

返回的 JSON 数据包

Client.delete_group(group_id)¶

删除分组。

参数:: group_id -- 要删除的分组的 ID
返回:: 返回的 JSON 数据包

设置备注名¶

详细请参考微信开放文档

Client.remark_user(user_id, remark)¶

设置备注名。

参数:

user_id -- 设置备注名的用户 ID
remark -- 新的备注名，长度必须小于30字符

返回:

返回的 JSON 数据包

获取用户基本信息¶

详细请参考微信开放文档

Client.get_user_info(user_id, lang='zh_CN')¶

获取用户基本信息。

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
lang -- 返回国家地区语言版本，zh_CN 简体，zh_TW 繁体，en 英语

返回:

返回的 JSON 数据包

Client.get_users_info(user_id_list, lang='zh_CN')¶

批量获取用户基本信息。

参数:

user_id_list -- 用户 ID 的列表
lang -- 返回国家地区语言版本，zh_CN 简体，zh_TW 繁体，en 英语

返回:

返回的 JSON 数据包

账户管理¶

长链接转短链接接口和微信认证事件推送暂未添加，可自行实现。

生成带参数的二维码¶

详细请参考微信开放文档

Client.create_qrcode(data)¶

创建二维码。

参数:: data -- 你要发送的参数 dict
返回:: 返回的 JSON 数据包

Client.show_qrcode(ticket)¶

通过ticket换取二维码。

参数:: ticket -- 二维码 ticket 。可以通过 create_qrcode() 获取到
返回:: 返回的 Request 对象

获取用户列表¶

详细请参考微信开放文档

Client.get_followers(first_user_id=None)¶

获取关注者列表详情请参考 https://developers.weixin.qq.com/doc/offiaccount/User_Management/Getting_a_User_List.html

参数:: first_user_id -- 可选。第一个拉取的OPENID，不填默认从头开始拉取
返回:: 返回的 JSON 数据包

素材管理¶

新增临时素材¶

详细请参考微信开放文档

Client.upload_media(media_type, media_file)¶

上传临时多媒体文件。

参数:

media_type -- 媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb）
media_file -- 要上传的文件，一个 File-object: open('xxx', 'rb')

返回:

返回的 JSON 数据包

获取临时素材¶

详细请参考微信开放文档

Client.download_media(media_id)¶

下载临时多媒体文件。

参数:: media_id -- 媒体文件 ID
返回:: requests 的 Response 实例

新增永久素材¶

详细请参考微信开放文档

Client.add_news(articles)¶

新增永久图文素材:

articles = [{
   "title": TITLE,
   "thumb_media_id": THUMB_MEDIA_ID,
   "author": AUTHOR,
   "digest": DIGEST,
   "show_cover_pic": SHOW_COVER_PIC(0 / 1),
   "content": CONTENT,
   "content_source_url": CONTENT_SOURCE_URL
}
# 若新增的是多图文素材，则此处应有几段articles结构，最多8段
]
client.add_news(articles)

参数:: articles -- 如示例中的数组
返回:: 返回的 JSON 数据包

Client.upload_news_picture(file)¶

上传图文消息内的图片。

参数:: file -- 要上传的图片文件，类型仅支持 jpg/png 格式，大小限制为 <10Mb，如：open('xxx', 'rb')
返回:: 返回的 JSON 数据包

Client.upload_permanent_media(media_type, media_file)¶

上传其他类型永久素材。

参数:

media_type -- 媒体文件类型，分别有图片（image）、语音（voice）和缩略图（thumb）
media_file -- 要上传的文件，一个 File-object: open('xxx', 'rb')

返回:

返回的 JSON 数据包

Client.upload_permanent_video(title, introduction, video)¶

上传永久视频。

参数:

title -- 视频素材的标题
introduction -- 视频素材的描述
video -- 要上传的视频，一个 File-object: open('xxx', 'rb')，大小限制 <10Mb

返回:

requests 的 Response 实例

获取永久素材¶

详细请参考微信开放文档

Client.download_permanent_media(media_id)¶

获取永久素材。

参数:: media_id -- 媒体文件 ID
返回:: requests 的 Response 实例

删除永久素材¶

详细请参考微信开放文档

Client.delete_permanent_media(media_id)¶

删除永久素材。

参数:: media_id -- 媒体文件 ID
返回:: 返回的 JSON 数据包

上传图文消息素材¶

Client.upload_news(articles)¶

上传图文消息素材

articles = [{
    "thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelOXCFZiq2OsIU-p",
    "author":"xxx",
    "title":"Happy Day",
    "content_source_url":"www.qq.com",
    "content":"content",
    "digest":"digest",
    "show_cover_pic":1,
    "need_open_comment":1,
    "only_fans_can_comment":1
}]

具体请参考: https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#1

参数:: articles -- 上传的图文消息数据。
返回:: 返回的 JSON 数据包。

修改永久图文素材¶

详细请参考微信开放文档

Client.update_news(update_data)¶

修改永久图文素材:

update_data = {
    "media_id":MEDIA_ID,
    "index":INDEX,
    "articles": {
        "title": TITLE,
        "thumb_media_id": THUMB_MEDIA_ID,
        "author": AUTHOR,
        "digest": DIGEST,
        "show_cover_pic": SHOW_COVER_PIC(0 / 1),
        "content": CONTENT,
        "content_source_url": CONTENT_SOURCE_URL
    }
}
client.update_news(update_data)

参数:: update_data -- 更新的数据，要包含 media_id（图文素材的 ID），index（要更新的文章在图文消息中的位置），articles（新的图文素材数据）
返回:: 返回的 JSON 数据包

获取素材总数¶

详细请参考微信开放文档

Client.get_media_count()¶

获取素材总数。

返回:: 返回的 JSON 数据包

获取素材列表¶

详细请参考微信开放文档

Client.get_media_list(media_type, offset, count)¶

获取素材列表。

参数:

media_type -- 素材的类型，图片（image）、视频（video）、语音（voice）、图文（news）
offset -- 从全部素材的该偏移位置开始返回，0表示从第一个素材返回
count -- 返回素材的数量，取值在1到20之间

返回:

返回的 JSON 数据包

用户标签管理¶

详细请参考微信开放文档

创建标签¶

Client.create_tag(tag_name)¶

创建一个新标签

参数:: tag_name -- 标签名
返回:: 返回的 JSON 数据包

获取公众号已创建的标签¶

Client.get_tags()¶

获取已经存在的标签

返回:: 返回的 JSON 数据包

编辑标签¶

Client.update_tag(tag_id, tag_name)¶

修改标签

参数:

tag_id -- 标签 ID
tag_name -- 新的标签名

返回:

返回的 JSON 数据包

删除标签¶

Client.delete_tag(tag_id)¶

删除标签

参数:: tag_id -- 标签 ID
返回:: 返回的 JSON 数据包

获取标签下粉丝列表¶

Client.get_users_by_tag(tag_id, next_open_id='')¶

获取标签下粉丝列表

参数:

tag_id -- 标签 ID
next_open_id -- 第一个拉取用户的 OPENID，默认从头开始拉取

返回:

返回的 JSON 数据包

批量为用户打标签¶

Client.tag_users(tag_id, open_id_list)¶

批量为用户打标签

参数:

tag_id -- 标签 ID
open_id_list -- 包含一个或多个用户的 OPENID 的列表

返回:

返回的 JSON 数据包

批量为用户取消标签¶

Client.untag_users(tag_id, open_id_list)¶

批量为用户取消标签

参数:

tag_id -- 标签 ID
open_id_list -- 包含一个或多个用户的 OPENID 的列表

返回:

返回的 JSON 数据包

获取用户身上的标签列表¶

Client.get_tags_by_user(open_id)¶

获取用户身上的标签列表

参数:: open_id -- 用户的 OPENID
返回:: 返回的 JSON 数据包

模板消息¶

Client.send_template_message(user_id, template_id, data, url='', miniprogram=None)¶

发送模板消息详情请参考 https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html

参数:

user_id -- 用户 ID 。就是你收到的 Message 的 source
template_id -- 模板 ID。
data -- 用于渲染模板的数据。
url -- 模板消息的可选链接。
miniprogram -- 跳小程序所需数据的可选数据。

返回:

返回的 JSON 数据包

返回码都是什么意思？¶

详细请参考微信开放文档

48001 -- API Unauthorized¶

如果你遇到了这个错误，请检查你的微信公众号是否有调用该接口的权限。详细请参考微信开放文档