企业微信主动调用接口

企业微信有 企业内部开发第三方应用开发智慧硬件开发 三种接入场景。 同一个接口根据场景不容,掺入参数的含义可能不一样。开发过程中,请根据实际场景,按照文档传入正确的参数。 部分“微信企业号”文档存在,企业微信 API 文档不存在的接口,名称后面会标注 (旧接口,建议更换) 。建议更换成企业微信提供的新接口。

WeChatClient

class wechatpy.enterprise.client.WeChatClient(corp_id, secret, access_token=None, session=None, timeout=None, auto_retry=True)[源代码]
access_token

WeChat access token

fetch_access_token()[源代码]

Fetch access token

WeChatClient 基本使用方法:

from wechatpy.enterprise import WeChatClient

client = WeChatClient('corp_id', 'secret')
user = client.user.get('user id')
menu = client.menu.get()
client.message.send_text('agent id', 'user id', 'content')
# 以此类推,参见下面的 API 说明
# client.media.xxx()
# client.tag.xxx()

如果不提供 session 参数,默认使用 wechatpy.session.memorystorage.MemoryStorage session 类型, 注意该类型不是线程安全的,不推荐生产环境使用。

应用管理

class wechatpy.enterprise.client.api.WeChatAgent(client=None)[源代码]

https://work.weixin.qq.com/api/doc#90000/90135/90226

get(agent_id)[源代码]

获取指定的应用详情 https://work.weixin.qq.com/api/doc#90000/90135/90227/获取指定的应用详情/

参数:agent_id – 应用id
返回:返回的 JSON 数据包
list()[源代码]

获取access_token对应的应用列表 https://work.weixin.qq.com/api/doc#90000/90135/90227/获取access_token对应的应用列表/

返回:应用概况列表
set(agent_id, name=None, description=None, redirect_domain=None, logo_media_id=None, report_location_flag=0, is_report_user=True, is_report_enter=True)[源代码]

设置应用 https://work.weixin.qq.com/api/doc#90000/90135/90228

参数:
  • agent_id – 企业应用的id
  • name – 企业应用名称,长度不超过32个utf8字符
  • description – 企业应用详情,长度为4至120个utf8字符
  • redirect_domain – 企业应用可信域名。注意:域名需通过所有权校验,否则jssdk功能将受限,此时返回错误码85005
  • logo_media_id – 企业应用头像的mediaid,通过素材管理接口上传图片获得mediaid,上传后会自动裁剪成方形和圆形两个头像
  • report_location_flag – 企业应用是否打开地理位置上报 0:不上报;1:进入会话上报;
  • is_report_enter – 是否上报用户进入应用事件。0:不接收;1:接收。
  • is_report_user – 是否接收用户变更通知。0:不接收;1:接收。
返回:

返回的 JSON 数据包

群聊会话

class wechatpy.enterprise.client.api.WeChatAppChat(client=None)[源代码]

https://work.weixin.qq.com/api/doc#90000/90135/90244

create(chat_id=None, name=None, owner=None, user_list=None)[源代码]

创建群聊会话

详情请参考 https://work.weixin.qq.com/api/doc#90000/90135/90245

限制说明: 只允许企业自建应用调用,且应用的可见范围必须是根部门; 群成员人数不可超过管理端配置的“群成员人数上限”,且最大不可超过500人; 每企业创建群数不可超过1000/天;

参数:
  • chat_id – 群聊的唯一标志,不能与已有的群重复;字符串类型,最长32个字符。只允许字符0-9及字母a-zA-Z。如果不填,系统会随机生成群id
  • name – 群聊名,最多50个utf8字符,超过将截断
  • owner – 指定群主的id。如果不指定,系统会随机从userlist中选一人作为群主
  • user_list – 会话成员列表,成员用userid来标识。至少2人,至多500人
返回:

返回的 JSON 数据包

get(chat_id)[源代码]

获取群聊会话

详情请参考 https://work.weixin.qq.com/api/doc#90000/90135/90247

参数:chat_id – 群聊id
返回:会话信息
send(chat_id, msg_type, **kwargs)[源代码]

应用推送消息

详情请参考:https://work.weixin.qq.com/api/doc#90000/90135/90248 :param chat_id: 群聊id :param msg_type: 消息类型,可以为text/image/voice/video/file/textcard/news/mpnews/markdown :param kwargs: 具体消息类型的扩展参数 :return:

send_msg(chat_id, msg_type, **kwargs)[源代码]

deprecated, use send instead

send_text(chat_id, content, safe=0)[源代码]

发送文本消息

详情请参考:https://work.weixin.qq.com/api/doc#90000/90135/90248/文本消息/

参数:
  • chat_id – 群聊id
  • content – 消息内容
  • safe – 表示是否是保密消息,0表示否,1表示是,默认0
返回:

update(chat_id, name=None, owner=None, add_user_list=None, del_user_list=None)[源代码]

修改群聊会话

详情请参考 https://work.weixin.qq.com/api/doc#90000/90135/90246

参数:
  • chat_id – 群聊id
  • name – 新的群聊名。若不需更新,请忽略此参数。最多50个utf8字符,超过将截断
  • owner – 新群主的id。若不需更新,请忽略此参数
  • add_user_list – 会话新增成员列表,成员用userid来标识
  • del_user_list – 会话退出成员列表,成员用userid来标识
返回:

返回的 JSON 数据包

异步任务

class wechatpy.enterprise.client.api.WeChatBatch(client=None)[源代码]

https://work.weixin.qq.com/api/doc#90000/90135/90979

异步批量接口用于大批量数据的处理,提交后接口即返回,企业微信会在后台继续执行任务。 执行完成后,企业微信后台会通过任务事件通知企业获取结果。事件的内容是加密的,解密过程请参考 [消息的加解密处理][signure],任务事件请参考异步任务完成事件推送。 目前,仅为通讯录更新提供了异步批量接口

get_result(job_id)[源代码]

获取异步任务结果

https://work.weixin.qq.com/api/doc#90000/90135/90983

参数:job_id – 异步任务id,最大长度为64字符
返回:返回的 JSON 数据包
invite(user=None, party=None, tag=None)[源代码]

邀请成员

https://work.weixin.qq.com/api/doc#90000/90135/90975

企业可通过接口批量邀请成员使用企业微信,邀请后将通过短信或邮件下发通知。

参数:
  • user – 成员ID列表, 最多支持1000个。
  • party – 成员ID列表, 最多支持100个。
  • tag – 成员ID列表, 最多支持100个。
返回:

返回的 JSON 数据包

invite_user(url, token, encoding_aes_key, user_ids=None, party_ids=None, tag_ids=None, invite_tips=None)[源代码]

邀请成员关注(deprecated) https://qydev.weixin.qq.com/wiki/index.php?title=异步任务接口

参数:
  • url – 企业应用接收企业微信推送请求的访问协议和地址,支持http或https协议
  • token – 用于生成签名
  • encoding_aes_key – 用于消息体的加密,是AES密钥的Base64编码
  • user_ids – 可选,成员ID列表,多个接收者用‘|’分隔,最多支持1000个。
  • party_ids – 可选,部门ID列表,多个接收者用‘|’分隔,最多支持100个。
  • tag_ids – 可选,标签ID列表,多个接收者用‘|’分隔。
  • invite_tips – 可选,推送到微信上的提示语
返回:

返回的 JSON 数据包

replace_party(url, token, encoding_aes_key, media_id)[源代码]

全量覆盖部门

https://work.weixin.qq.com/api/doc#90000/90135/90982

参数:
  • url – 企业应用接收企业微信推送请求的访问协议和地址,支持http或https协议
  • token – 用于生成签名
  • encoding_aes_key – 用于消息体的加密,是AES密钥的Base64编码
  • media_id – 上传的csv文件的media_id
返回:

返回的 JSON 数据包

replace_user(url, token, encoding_aes_key, media_id, to_invite=True)[源代码]

全量覆盖成员

https://work.weixin.qq.com/api/doc#90000/90135/90981

参数:
  • url – 企业应用接收企业微信推送请求的访问协议和地址,支持http或https协议
  • token – 用于生成签名
  • encoding_aes_key – 用于消息体的加密,是AES密钥的Base64编码
  • media_id – 上传的csv文件的media_id
  • to_invite – 是否邀请新建的成员使用企业微信(将通过微信服务通知或短信或邮件下发邀请,每天自动下发一次,最多持续3个工作日),默认值为true。
返回:

返回的 JSON 数据包

sync_user(url, token, encoding_aes_key, media_id, to_invite=True)[源代码]

增量更新成员

https://work.weixin.qq.com/api/doc#90000/90135/90980

参数:
  • url – 企业应用接收企业微信推送请求的访问协议和地址,支持http或https协议
  • token – 用于生成签名
  • encoding_aes_key – 用于消息体的加密,是AES密钥的Base64编码
  • media_id – 上传的csv文件的media_id
  • to_invite – 是否邀请新建的成员使用企业微信(将通过微信服务通知或短信或邮件下发邀请,每天自动下发一次,最多持续3个工作日),默认值为true。
返回:

返回的 JSON 数据包

企业会话(旧接口,建议更换)

class wechatpy.enterprise.client.api.WeChatChat(client=None)[源代码]

“微信企业号”旧接口,企业微信请使用 appchat。

clear_notify(op_user, type, id)[源代码]

清除会话未读状态

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • op_user – 会话所有者的userid
  • type – 会话类型:single|group,分别表示:单聊|群聊
  • id – 会话值,为userid|chatid,分别表示:成员id|会话id
返回:

返回的 JSON 数据包

create(chat_id, name, owner, user_list)[源代码]

创建会话

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • chat_id – 会话id。字符串类型,最长32个字符。只允许字符0-9及字母a-zA-Z, 如果值内容为64bit无符号整型:要求值范围在[1, 2^63)之间, [2^63, 2^64)为系统分配会话id区间
  • name – 会话标题
  • owner – 管理员userid,必须是该会话userlist的成员之一
  • user_list – 会话成员列表,成员用userid来标识。会话成员必须在3人或以上,1000人以下
返回:

返回的 JSON 数据包

get(chat_id)[源代码]

获取会话

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:chat_id – 会话 ID
返回:会话信息
quit(chat_id, op_user)[源代码]

退出会话

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • chat_id – 会话 ID
  • op_user – 操作人 userid
返回:

返回的 JSON 数据包

send_file(sender, receiver_type, receiver_id, media_id)[源代码]

发送文件消息

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • sender – 发送人
  • receiver_type – 接收人类型:single|group,分别表示:单聊|群聊
  • receiver_id – 接收人的值,为userid|chatid,分别表示:成员id|会话id
  • media_id – 文件id,可以调用上传素材文件接口获取, 文件须大于4字节
返回:

返回的 JSON 数据包

send_group_file(sender, receiver, media_id)[源代码]

发送群聊文件消息

参数:
  • sender – 发送人
  • receiver – 会话 ID
  • media_id – 文件id,可以调用上传素材文件接口获取, 文件须大于4字节
返回:

返回的 JSON 数据包

send_group_image(sender, receiver, media_id)[源代码]

发送群聊图片消息

参数:
  • sender – 发送人
  • receiver – 会话 ID
  • media_id – 图片媒体文件id,可以调用上传素材文件接口获取
返回:

返回的 JSON 数据包

send_group_text(sender, receiver, content)[源代码]

发送群聊文本消息

参数:
  • sender – 发送人
  • receiver – 会话 ID
  • content – 消息内容
返回:

返回的 JSON 数据包

send_image(sender, receiver_type, receiver_id, media_id)[源代码]

发送图片消息

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • sender – 发送人
  • receiver_type – 接收人类型:single|group,分别表示:单聊|群聊
  • receiver_id – 接收人的值,为userid|chatid,分别表示:成员id|会话id
  • media_id – 图片媒体文件id,可以调用上传素材文件接口获取
返回:

返回的 JSON 数据包

send_single_file(sender, receiver, media_id)[源代码]

发送单聊文件消息

参数:
  • sender – 发送人
  • receiver – 接收人成员 ID
  • media_id – 文件id,可以调用上传素材文件接口获取, 文件须大于4字节
返回:

返回的 JSON 数据包

send_single_image(sender, receiver, media_id)[源代码]

发送单聊图片消息

参数:
  • sender – 发送人
  • receiver – 接收人成员 ID
  • media_id – 图片媒体文件id,可以调用上传素材文件接口获取
返回:

返回的 JSON 数据包

send_single_text(sender, receiver, content)[源代码]

发送单聊文本消息

参数:
  • sender – 发送人
  • receiver – 接收人成员 ID
  • content – 消息内容
返回:

返回的 JSON 数据包

send_text(sender, receiver_type, receiver_id, content)[源代码]

发送文本消息

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • sender – 发送人
  • receiver_type – 接收人类型:single|group,分别表示:单聊|群聊
  • receiver_id – 接收人的值,为userid|chatid,分别表示:成员id|会话id
  • content – 消息内容
返回:

返回的 JSON 数据包

set_mute(user_mute_list)[源代码]

设置成员新消息免打扰

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:user_mute_list – 成员新消息免打扰参数,数组,最大支持10000个成员
返回:返回的 JSON 数据包
update(chat_id, op_user, name=None, owner=None, add_user_list=None, del_user_list=None)[源代码]

修改会话

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=企业会话接口说明

参数:
  • chat_id – 会话 ID
  • op_user – 操作人 userid
  • name – 会话标题
  • owner – 管理员userid,必须是该会话userlist的成员之一
  • add_user_list – 会话新增成员列表,成员用userid来标识
  • del_user_list – 会话退出成员列表,成员用userid来标识
返回:

返回的 JSON 数据包

部门管理

class wechatpy.enterprise.client.api.WeChatDepartment(client=None)[源代码]

https://work.weixin.qq.com/api/doc#90000/90135/90204

create(name, parent_id=1, order=None, id=None)[源代码]

创建部门

https://work.weixin.qq.com/api/doc#90000/90135/90205

参数:
  • name – 部门名称。长度限制为1~32个字符,字符不能包括:?”<>|
  • parent_id – 父部门id,32位整型
  • order – 在父部门中的次序值。order值大的排序靠前。有效的值范围是[0, 2^32)
  • id – 部门id,32位整型,指定时必须大于1。若不填该参数,将自动生成id
返回:

返回的 JSON 数据包

delete(id)[源代码]

删除部门

https://work.weixin.qq.com/api/doc#90000/90135/90207

参数:id – 部门id。(注:不能删除根部门;不能删除含有子部门、成员的部门)
返回:返回的 JSON 数据包
get(id=None)[源代码]

获取指定部门列表

https://work.weixin.qq.com/api/doc#90000/90135/90208

权限说明: 只能拉取token对应的应用的权限范围内的部门列表

参数:id – 部门id。获取指定部门及其下的子部门。 如果不填,默认获取全量组织架构
返回:部门列表
get_map_users(id=None, key='name', status=0, fetch_child=0)[源代码]

映射员工某详细字段到 user_id

企业微信许多对员工操作依赖于 user_id ,但没有提供直接查询员工对应 user_id 的结构,

这里是一个变通的方法,常用于储存员工 user_id ,并用于后续查询或对单人操作(如发送指定消息)

参数:
  • id – 部门 id, 如果不填,默认获取有权限的所有部门
  • key – 员工详细信息字段 key,所指向的值必须唯一
  • status – 0 获取全部员工,1 获取已关注成员列表, 2 获取禁用成员列表,4 获取未关注成员列表。可叠加
  • fetch_child – 1/0:是否递归获取子部门下面的成员
返回:

dict - 部门成员指定字段到 user_id 的 map { key: user_id }

get_users(id, status=0, fetch_child=0, simple=True)[源代码]

获取部门成员:https://work.weixin.qq.com/api/doc#90000/90135/90200

获取部门成员详情:https://work.weixin.qq.com/api/doc#90000/90135/90201

参数:
  • id – 部门 id
  • status – 0 获取全部员工,1 获取已关注成员列表, 2 获取禁用成员列表,4 获取未关注成员列表。可叠加
  • fetch_child – 1/0:是否递归获取子部门下面的成员
  • simple – True 获取部门成员,False 获取部门成员详情
返回:

部门成员列表

update(id, name=None, parent_id=None, order=None)[源代码]

更新部门

https://work.weixin.qq.com/api/doc#90000/90135/90206

参数:
  • id – 部门 id
  • name – 部门名称。长度限制为1~32个字符,字符不能包括:?”<>|
  • parent_id – 父亲部门id
  • order – 在父部门中的次序值。order值大的排序靠前。有效的值范围是[0, 2^32)
返回:

返回的 JSON 数据包

JS-SDK 接口

class wechatpy.enterprise.client.api.WeChatJSAPI(client=None)[源代码]

https://work.weixin.qq.com/api/doc#90001/90144/90539

get_agent_jsapi_ticket()[源代码]

获取应用的jsapi_ticket

该方法会通过 session 对象自动缓存管理 ticket

返回:ticket
get_agent_ticket()[源代码]

获取应用的jsapi_ticket

https://work.weixin.qq.com/api/doc#90001/90144/90539/获取应用的jsapi_ticket/

返回:返回的 JSON 数据包
get_jsapi_signature(noncestr, ticket, timestamp, url)[源代码]

获取 JSAPI 签名

https://work.weixin.qq.com/api/doc#90001/90144/90539/签名算法/

参数:
  • noncestr – nonce string
  • ticket – JS-SDK ticket
  • timestamp – 时间戳
  • url – URL
返回:

签名

get_jsapi_ticket()[源代码]

获取微信 JS-SDK ticket

该方法会通过 session 对象自动缓存管理 ticket

返回:ticket
get_ticket()[源代码]

获取企业的jsapi_ticket

https://work.weixin.qq.com/api/doc#90001/90144/90539/获取企业的jsapi_ticket/

返回:返回的 JSON 数据包

素材接口(旧接口,建议更换)

class wechatpy.enterprise.client.api.WeChatMaterial(client=None)[源代码]
add(agent_id, media_type, media_file)[源代码]

新增其它类型永久素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E4%B8%8A%E4%BC%A0%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:
  • agent_id – 企业应用的id
  • media_type – 媒体文件类型,分别有图片(image)、语音(voice)、视频(video)普通文件(file)
  • media_file – 要上传的文件,一个 File-object
返回:

返回的 JSON 数据包

add_articles(articles)[源代码]

新增永久图文素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E4%B8%8A%E4%BC%A0%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:articles – 图文素材数组
返回:返回的 JSON 数据包
batchget(agent_id, media_type, offset=0, count=20)[源代码]

批量获取永久素材列表 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E7%B4%A0%E6%9D%90%E5%88%97%E8%A1%A8

参数:
  • agent_id – 企业应用的id
  • media_type – 媒体文件类型,分别有图文(mpnews)、图片(image)、 语音(voice)、视频(video)和文件(file)
  • offset – 从全部素材的该偏移位置开始返回,0 表示从第一个素材返回
  • count – 返回素材的数量,取值在1到20之间
返回:

返回的 JSON 数据包

delete(agent_id, media_id)[源代码]

删除永久素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E5%88%A0%E9%99%A4%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:
  • agent_id – 企业应用的id
  • media_id – 媒体文件 ID
返回:

返回的 JSON 数据包

get(agent_id, media_id)[源代码]

获取永久素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:
  • agent_id – 企业应用的id
  • media_id – 媒体文件 ID
返回:

requests 的 Response 实例

get_articles(agent_id, media_id)[源代码]

获取永久素材:图文消息素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:
  • agent_id – 企业应用的id
  • media_id – 媒体文件 ID
返回:

返回的 JSON 数据包

get_count(agent_id)[源代码]

获取素材总数 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E7%B4%A0%E6%9D%90%E6%80%BB%E6%95%B0

参数:agent_id – 企业应用的id
返回:返回的 JSON 数据包
get_url(agent_id, media_id)[源代码]

获取永久素材下载地址 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E6%B0%B8%E4%B9%85%E7%B4%A0%E6%9D%90

参数:
  • agent_id – 企业应用的id
  • media_id – 媒体文件 ID
返回:

临时素材下载地址

update_articles(agent_id, media_id, articles)[源代码]

修改永久图文素材 详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=%E4%BF%AE%E6%94%B9%E6%B0%B8%E4%B9%85%E5%9B%BE%E6%96%87%E7%B4%A0%E6%9D%90

参数:
  • media_id – 要修改的图文消息的 id
  • index – 要更新的文章在图文消息中的位置(多图文消息时,此字段才有意义),第一篇为 0
  • articles – 图文素材数组
返回:

返回的 JSON 数据包

素材管理

class wechatpy.enterprise.client.api.WeChatMedia(client=None)[源代码]

素材管理

https://work.weixin.qq.com/api/doc#90000/90135/91054

download(media_id)[源代码]

获取临时素材文件

https://work.weixin.qq.com/api/doc#90000/90135/90254

参数:media_id – 媒体文件id
返回:requests 的 Response 实例
get_jssdk_url(media_id)[源代码]

获取高清语音素材

https://work.weixin.qq.com/api/doc#90000/90135/90255

参数:media_id – 通过JSSDK的uploadVoice接口上传的语音文件id
返回:高清语音素材下载地址
get_url(media_id)[源代码]

获取临时素材

https://work.weixin.qq.com/api/doc#90000/90135/90254

参数:media_id – 媒体文件id
返回:临时素材下载地址
upload(media_type, media_file)[源代码]

上传临时素材

https://work.weixin.qq.com/api/doc#90000/90135/90253

参数:
  • media_type – 媒体文件类型,分别有图片(image)、语音(voice)、视频(video)和普通文件(file)
  • media_file – 要上传的文件,一个 File-object
返回:

返回的 JSON 数据包

upload_img(image_file)[源代码]

上传永久图片

https://work.weixin.qq.com/api/doc#90000/90135/90256

上传图片得到图片URL,该URL永久有效。 返回的图片URL,仅能用于图文消息(mpnews)正文中的图片展示;若用于非企业微信域名下的页面,图片将被屏蔽。 每个企业每天最多可上传100张图片。 图片文件大小应在 5B ~ 2MB 之间。

返回:返回的 JSON 数据包

自定义菜单

class wechatpy.enterprise.client.api.WeChatMenu(client=None)[源代码]

自定义菜单

https://work.weixin.qq.com/api/doc#90000/90135/90230

create(agent_id, menu_data)[源代码]

创建菜单

https://work.weixin.qq.com/api/doc#90000/90135/90231

参数:agent_id – 应用id
delete(agent_id)[源代码]

删除菜单

https://work.weixin.qq.com/api/doc#90000/90135/90233

参数:agent_id – 应用id
get(agent_id)[源代码]

获取菜单

https://work.weixin.qq.com/api/doc#90000/90135/90232

参数:agent_id – 应用id

应用消息

class wechatpy.enterprise.client.api.WeChatMessage(client=None)[源代码]

发送应用消息

https://work.weixin.qq.com/api/doc#90000/90135/90236

支持: * 文本消息 * 图片消息 * 语音消息 * 视频消息 * 文件消息 * 文本卡片消息 * 图文消息 * 图文消息(mpnews) * markdown消息 * 小程序通知消息

send(agent_id, user_ids, party_ids='', tag_ids='', msg=None)[源代码]

通用的消息发送接口。msg 内需要指定 msgtype 和对应类型消息必须的字段。 如果部分接收人无权限或不存在,发送仍然执行,但会返回无效的部分(即invaliduser或invalidparty或invalidtag),常见的原因是接收人不在应用的可见范围内。 user_ids、party_ids、tag_ids 不能同时为空,后面不再强调。

参数:
  • agent_id – 必填,企业应用的id,整型。可在应用的设置页面查看。
  • user_ids – 成员ID列表。
  • party_ids – 部门ID列表。
  • tag_ids – 标签ID列表。
  • msg (dict | None) – 发送消息的 dict 对象
返回:

接口调用结果

send_markdown(agent_id, user_ids, content, party_ids='', tag_ids='')[源代码]

markdown消息

https://work.weixin.qq.com/api/doc#90000/90135/90236/markdown%E6%B6%88%E6%81%AF

> 目前仅支持markdown语法的子集 > 微工作台(原企业号)不支持展示markdown消息

参数:
  • agent_id (string) – 企业应用的id,整型。可在应用的设置页面查看
  • content (string) – markdown内容,最长不超过2048个字节,必须是utf8编码
  • user_ids (list or tuple or string) – 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。 特殊情况:指定为@all,则向关注该企业应用的全部成员发送
  • party_ids (list or tuple or string) – 部门ID列表,最多支持100个。当touser为@all时忽略本参数
  • tag_ids (list or tuple or string) – 标签ID列表,最多支持100个。当touser为@all时忽略本参数
返回:

接口调用结果

返回类型:

dict

send_text_card(agent_id, user_ids, title, description, url, btntxt='详情', party_ids='', tag_ids='')[源代码]

文本卡片消息

https://work.weixin.qq.com/api/doc#90000/90135/90236/文本卡片消息

请求示例: {

“touser” : “UserID1|UserID2|UserID3”, “toparty” : “PartyID1 | PartyID2”, “totag” : “TagID1 | TagID2”, “msgtype” : “textcard”, “agentid” : 1, “textcard” : {

“title” : “领奖通知”, “description” : “<div class=”gray”>2016年9月26日</div> <div class=”normal”>恭喜你抽中iPhone 7一台,

领奖码:xxxx</div><div class=”highlight”>请于2016年10月10日前联系行政同事领取</div>”,

“url” : “URL”, “btntxt”:”更多”

}

}

特殊说明: 卡片消息的展现形式非常灵活,支持使用br标签或者空格来进行换行处理,也支持使用div标签来使用不同的字体颜色, 目前内置了3种文字颜色:灰色(gray)、高亮(highlight)、默认黑色(normal),将其作为div标签的class属性即可, 具体用法请参考上面的示例。

参数:
  • agent_id – 必填,企业应用的id,整型。可在应用的设置页面查看。
  • user_ids – 成员ID列表(消息接收者,多个接收者用‘|’分隔,最多支持1000个)。
  • title – 标题,不超过128个字节,超过会自动截断。
  • description – 必填,描述,不超过512个字节,超过会自动截断
  • url – 必填,点击后跳转的链接。
  • btntxt – 按钮文字。 默认为“详情”, 不超过4个文字,超过自动截断。
  • party_ids – 部门ID列表。
  • tag_ids – 标签ID列表。

工具类接口

class wechatpy.enterprise.client.api.WeChatMisc(client=None)[源代码]
get_wechat_ips()[源代码]

获取企业微信服务器的ip段

https://work.weixin.qq.com/api/doc#90000/90135/90238/%E8%8E%B7%E5%8F%96%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%9A%84ip%E6%AE%B5

返回:企业微信回调的IP段

身份验证(OAuth2)

class wechatpy.enterprise.client.api.WeChatOAuth(client=None)[源代码]
authorize_url(redirect_uri, state=None)[源代码]

构造网页授权链接 详情请参考 https://work.weixin.qq.com/api/doc#90000/90135/91022

参数:
  • redirect_uri – 授权后重定向的回调链接地址
  • state – 重定向后会带上 state 参数
返回:

返回的 JSON 数据包

get_user_info(code)[源代码]

获取访问用户身份 详情请参考 https://work.weixin.qq.com/api/doc#90000/90135/91023

参数:code – 通过成员授权获取到的code
返回:返回的 JSON 数据包

应用授权(服务商、第三方应用开发相关)

class wechatpy.enterprise.client.api.WeChatService(client=None)[源代码]

应用授权(服务商、第三方应用开发相关)

https://work.weixin.qq.com/api/doc#90001/90143/90597

新的授权体系有部分接口未实现,欢迎提交 PR。

get_login_info(auth_code, provider_access_token=None)[源代码]

获取企业号登录用户信息

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=获取企业号登录用户信息

参数:
  • provider_access_token – 服务提供商的 accesstoken
  • auth_code – OAuth 2.0 授权企业号管理员登录产生的 code
返回:

返回的 JSON 数据包

get_login_url(login_ticket, target, agentid=None, provider_access_token=None)[源代码]

获取登录企业号官网的url

详情请参考 https://qydev.weixin.qq.com/wiki/index.php?title=获取登录企业号官网的url

参数:
  • provider_access_token – 服务提供商的 accesstoken
  • login_ticket – 通过get_login_info得到的login_ticket, 10小时有效
  • target – 登录跳转到企业号后台的目标页面
  • agentid – 可选,授权方应用id
返回:

返回的 JSON 数据包

get_provider_token(provider_secret)[源代码]

获取服务商凭证

https://work.weixin.qq.com/api/doc#90001/90143/91200

参数:provider_secret – 服务商的secret,在服务商管理后台可见
返回:返回的 JSON 数据包
get_suite_token(suite_id, suite_secret, suite_ticket)[源代码]

获取第三方应用凭证

https://work.weixin.qq.com/api/doc#90001/90143/9060

参数:
  • suite_id – 以ww或wx开头应用id(对应于旧的以tj开头的套件id)
  • suite_secret – 应用secret
  • suite_ticket – 企业微信后台推送的ticket
返回:

返回的 JSON 数据包

摇一摇周边接口(旧接口,建议更换)

class wechatpy.enterprise.client.api.WeChatShakeAround(client=None)[源代码]
get_shake_info(ticket)[源代码]

获取摇周边的设备及用户信息

https://qydev.weixin.qq.com/wiki/index.php?title=获取设备及用户信息

参数:ticket – 摇周边业务的ticket,可在摇到的 URL 中得到,ticket 生效时间为30分钟
返回:设备及用户信息

标签管理

class wechatpy.enterprise.client.api.WeChatTag(client=None)[源代码]

标签管理

https://work.weixin.qq.com/api/doc#90000/90135/90209

用户管理

class wechatpy.enterprise.client.api.WeChatUser(client=None)[源代码]

成员管理

https://work.weixin.qq.com/api/doc#90000/90135/90194

邀请成员接口位于 WeChatBatch.invite

batch_delete(user_ids)[源代码]

批量删除成员

https://work.weixin.qq.com/api/doc#90000/90135/90199

convert_to_openid(user_id, agent_id=None)[源代码]

user_id 转成 openid

https://work.weixin.qq.com/api/doc#90000/90135/90202

参数:
  • user_id – 企业微信内的成员 ID
  • agent_id – 可选,需要发送红包的应用ID,若只是使用微信支付和企业转账,则无需该参数
返回:

返回的 JSON 数据包

convert_to_user_id(openid)[源代码]

openid 转成 user_id

https://work.weixin.qq.com/api/doc#90000/90135/90202

参数:openid – 在使用微信支付、微信红包和企业转账之后,返回结果的openid
返回:该 openid 在企业微信中对应的成员 user_id
create(user_id, name, department=None, position=None, mobile=None, gender=0, tel=None, email=None, weixin_id=None, extattr=None)[源代码]

创建成员

https://work.weixin.qq.com/api/doc#90000/90135/90195

delete(user_id)[源代码]

删除成员

https://work.weixin.qq.com/api/doc#90000/90135/90198

get(user_id)[源代码]

读取成员

https://work.weixin.qq.com/api/doc#90000/90135/90196

list(department_id, fetch_child=False, status=0, simple=False)[源代码]

批量获取部门成员 / 批量获取部门成员详情

https://work.weixin.qq.com/api/doc#90000/90135/90200 https://work.weixin.qq.com/api/doc#90000/90135/90201

此接口和 WeChatDepartment.get_users 是同一个接口,区别为 simple 的默认值不同。

update(user_id, name=None, department=None, position=None, mobile=None, gender=None, tel=None, email=None, weixin_id=None, enable=None, extattr=None)[源代码]

更新成员

https://work.weixin.qq.com/api/doc#90000/90135/90197

verify(user_id)[源代码]

二次验证

https://work.weixin.qq.com/api/doc#90000/90135/90203

参数:user_id – 成员UserID。对应管理端的帐号