企业微信主动调用接口

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

WeChatClient

class wechatpy.work.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.work 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.work.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.work.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_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.work.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 数据包

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.work.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.work.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.work.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 数据包

OA数据接口

class wechatpy.work.client.api.WeChatOA(client=None)[源代码]

OA管理

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

apply_event(creator_userid, template_id, use_template_approver, approver, apply_data, summary_list, notifyer=None, notify_type=None)[源代码]

提交审批申请,这个函数的参数比较复杂,具体请查看官方文档 https://work.weixin.qq.com/api/doc/90000/90135/91853

参数:
  • creator_userid – 申请人userid,此审批申请将以此员工身份提交,申请人需在应用可见范围内
  • template_id – 模板id。可在“获取审批申请详情”、“审批状态变化回调通知”中获得,也可在审批模板的模板编辑页面链接中获得。暂不支持通过接口提交[打卡补卡][调班]模板审批单。
  • use_template_approver – 审批人模式:0-通过接口指定审批人、抄送人(此时approver、notifyer等参数可用); 1-使用此模板在管理后台设置的审批流程,支持条件审批。
  • approver – 具体参数查看官方文档,审批流程信息,用于指定审批申请的审批流程,支持单人审批、多人会签、多人或签,可能有多个审批节点,仅use_template_approver为0时生效。
  • apply_data – 具体参数查看官方文档,审批申请数据,可定义审批申请中各个控件的值,其中必填项必须有值,选填项可为空,数据结构同“获取审批申请详情”接口返回值中同名参数“apply_data”
  • summary_list – 具体参数查看官方文档,摘要信息,用于显示在审批通知卡片、审批列表的摘要信息,最多3行
  • notifyer – 抄送人节点userid列表,仅use_template_approver为0时生效。
  • notify_type – 抄送方式:1-提单时抄送(默认值); 2-单据通过后抄送;3-提单和单据通过后抄送。仅use_template_approver为0时生效。
返回:

get_approval_detail(sp_no)[源代码]

获取审批申请详情 https://work.weixin.qq.com/api/doc/90000/90135/91983

参数:sp_no – 审批单编号
返回:
get_approval_info(start_time, end_time, cursor, size=100, filters=None)[源代码]

批量获取审批单号 https://work.weixin.qq.com/api/doc/90000/90135/91816

参数:
  • start_time – 开始时间戳
  • end_time – 结束时间戳,请求的参数endtime需要大于startime, 起始时间跨度不能超过31天;
  • cursor – 分页查询游标,默认为0,后续使用返回的next_cursor进行分页拉取
  • size – 一次请求拉取审批单数量,默认值为100,上限值为100
  • filters – 请自行查看文档
返回:

get_checkin_data(data_type: int, start_time: int, end_time: int, userid_list: List[str]) → dict[源代码]

获取打卡数据 https://work.weixin.qq.com/api/doc/90000/90135/90262

  • 获取记录时间跨度不超过30天
  • 用户列表不超过100个。若用户超过100个,请分批获取
  • 有打卡记录即可获取打卡数据,与当前”打卡应用”是否开启无关
参数:
  • data_type – 打卡类型。1:上下班打卡;2:外出打卡;3:全部打卡
  • start_time – 获取打卡记录的开始时间。Unix时间戳
  • end_time – 获取打卡记录的结束时间。Unix时间戳
  • userid_list – 需要获取打卡记录的用户列表
返回:

打卡数据

get_checkin_option(datetime: int, userid_list: List[str]) → dict[源代码]

获取打卡规则 https://work.weixin.qq.com/api/doc/90000/90135/90263

  • 用户列表不超过100个,若用户超过100个,请分批获取。
  • 用户在不同日期的规则不一定相同,请按天获取。
参数:
  • datetime – 需要获取规则的日期当天0点的Unix时间戳
  • userid_list – 需要获取打卡规则的用户列表
返回:

打卡规则

get_dial_record(start_time: Optional[int] = None, end_time: Optional[int] = None, offset: int = 0, limit: int = 100) → dict[源代码]

获取公费电话拨打记录 https://work.weixin.qq.com/api/doc/90000/90135/90267

企业可通过此接口,按时间范围拉取成功接通的公费电话拨打记录。

请注意,查询的时间范围为[start_time,end_time],即前后均为闭区间。在两个参数都 指定了的情况下,结束时间不得小于开始时间,开始时间也不得早于当前时间,否则会返回 600018错误码(无效的起止时间)。

受限于网络传输,起止时间的最大跨度为30天,如超过30天,则以结束时间为基准向前取 30天进行查询。

如果未指定起止时间,则默认查询最近30天范围内数据。

参数:
  • start_time – 查询的起始时间戳
  • end_time – 查询的结束时间戳
  • offset – 分页查询的偏移量
  • limit – 分页查询的每页大小,默认为100条,如该参数大于100则按100处理
返回:

公费电话拨打记录

get_open_approval_data(third_no: str) → dict[源代码]

查询自建应用审批单当前状态 https://work.weixin.qq.com/api/doc/90000/90135/90269

参数:third_no – 开发者发起申请时定义的审批单号
返回:审批单的当前审批状态
get_template_detail(template_id)[源代码]

查询审批模板的详情 https://work.weixin.qq.com/api/doc/90000/90135/91982

参数:template_id – 模板Id
返回:

日程管理

class wechatpy.work.client.api.WeChatCalendar(client=None)[源代码]

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

add(organizer, summary, color, description='', shares=())[源代码]

创建日历 https://work.weixin.qq.com/api/doc/90000/90135/92618

参数:
  • organizer – 指定的组织者userid。注意该字段指定后不可更新
  • summary – 日历标题。1 ~ 128 字符
  • color – 日历在终端上显示的颜色,RGB颜色编码16进制表示,例如:”#0000FF” 表示纯蓝色
  • description – 日历描述。0 ~ 512 字符
  • shares (list[str]) – 日历共享成员列表。最多2000人
返回:

日历ID

返回类型:

str

delete(calendar_id)[源代码]

删除日历 https://work.weixin.qq.com/api/doc/90000/90135/92620

参数:calendar_id – 日历ID
get(calendar_ids)[源代码]

获取日历 https://work.weixin.qq.com/api/doc/90000/90135/92621

参数:calendar_ids (list[str]) – 日历ID列表。一次最多可获取1000条
返回:日历列表
返回类型:list[dict]
update(calendar_id, summary, color, description='', shares=())[源代码]

更新日历 https://work.weixin.qq.com/api/doc/90000/90135/92619

参数:
  • calendar_id – 日历ID
  • summary – 日历标题。1 ~ 128 字符
  • color – 日历在终端上显示的颜色,RGB颜色编码16进制表示,例如:”#0000FF” 表示纯蓝色
  • description – 日历描述。0 ~ 512 字符
  • shares (list[str]) – 日历共享成员列表。最多2000人

日历管理

class wechatpy.work.client.api.WeChatSchedule(client=None)[源代码]

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

add(organizer, start_time, end_time, attendees=(), summary='', description='', is_remind=True, remind_before_event_secs=3600, is_repeat=False, repeat_type=0, location='', calendar_id='')[源代码]

创建日程 https://work.weixin.qq.com/api/doc/90000/90135/92622

参数:
  • organizer (str) – 组织者
  • start_time (int) – 日程开始时间,Unix时间戳
  • end_time (int) – 日程结束时间,Unix时间戳
  • attendees (list[str]) – 日程参与者列表。最多支持2000人
  • summary (str) – 日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
  • description (str) – 日程描述。0 ~ 512 字符
  • is_remind (bool) – 是否需要提醒
  • remind_before_event_secs (int) – 日程开始(start_time)前多少秒提醒,当is_remind为1时有效
  • is_repeat (bool) – 是否重复日程
  • repeat_type (int) – 重复类型,当is_repeat为1时有效。目前支持如下类型: 0 - 每日 1 - 每周 2 - 每月 5 - 每年 7 - 工作日
  • location (str) – 日程地址。0 ~ 128 字符
  • calendar_id (str) – 日程所属日历ID。注意,这个日历必须是属于组织者(organizer)的日历;如果不填,那么插入到组织者的默认日历上
返回:

日程ID

返回类型:

str

delete(schedule_id)[源代码]

取消日程(删除日程) https://work.weixin.qq.com/api/doc/90000/90135/92625

参数:schedule_id – 日程ID
get(schedule_ids)[源代码]

获取日程 https://work.weixin.qq.com/api/doc/90000/90135/92624

参数:schedule_ids (list[str]) – 日程ID列表。一次最多可获取1000条
返回:日程列表
返回类型:list[dict]
get_by_calendar(calendar_id, offset=0, limit=500)[源代码]

获取日历下的日程列表 https://work.weixin.qq.com/api/doc/90000/90135/92626 (注意,被取消的日程也可以拉取详情,调用者需要检查status)

参数:
  • calendar_id – 日历ID
  • offset – 分页,偏移量, 默认为0
  • limit – 分页,预期请求的数据量,默认为500,取值范围 1 ~ 1000
返回:

日程列表

返回类型:

list[dict]

update(organizer, schedule_id, start_time, end_time, attendees=(), summary='', description='', is_remind=True, remind_before_event_secs=3600, is_repeat=False, repeat_type=0, location='', calendar_id='')[源代码]

更新日程 https://work.weixin.qq.com/api/doc/90000/90135/92623

参数:
  • organizer (str) – 组织者
  • schedule_id (str) – 日程ID
  • start_time (int) – 日程开始时间,Unix时间戳
  • end_time (int) – 日程结束时间,Unix时间戳
  • attendees (list[str]) – 日程参与者列表。最多支持2000人
  • summary (str) – 日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
  • description (str) – 日程描述。0 ~ 512 字符
  • is_remind (bool) – 是否需要提醒
  • remind_before_event_secs (int) – 日程开始(start_time)前多少秒提醒,当is_remind为1时有效
  • is_repeat (bool) – 是否重复日程
  • repeat_type (int) – 重复类型,当is_repeat为1时有效。目前支持如下类型: 0 - 每日 1 - 每周 2 - 每月 5 - 每年 7 - 工作日
  • location (str) – 日程地址。0 ~ 128 字符
  • calendar_id (str) – 日程所属日历ID。注意,这个日历必须是属于组织者(organizer)的日历;如果不填,那么插入到组织者的默认日历上

电子发票

class wechatpy.work.client.api.WeChatInvoice(client=None)[源代码]

企业微信电子发票API

get_info(card_id: str, encrypt_code: str) → dict[源代码]

查询电子发票

参考:https://work.weixin.qq.com/api/doc/90000/90135/90284

接口说明:报销方在获得用户选择的电子发票标识参数后,可以通过该接口查询电子发票的 结构化信息,并获取发票PDF文件。

权限说明:仅认证的企业微信账号有接口权限

返回结果参数说明请查看官方文档。

参数:
  • card_id – 发票id
  • encrypt_code – 加密code
返回:

发票信息

get_info_batch(item_list: List[Dict[str, str]]) → dict[源代码]

批量查询电子发票

参考:https://work.weixin.qq.com/api/doc/90000/90135/90287

报销方在获得用户选择的电子发票标识参数后,可以通过该接口批量查询电子发票的结构化信息。

权限说明: 仅认证的企业微信账号并且企业激活人数超过200的企业才有接口权限,如果认证的企业 激活人数不超过200人请联系企业微信客服咨询。

返回结果参数说明请查看官方文档。

参数:item_list – 发票列表,示例: [{‘card_id’: ‘id’, ‘encrypt_code’: ‘code’}…]
返回:电子发票信息
update_status(card_id: str, encrypt_code: str, reimburse_status: str) → dict[源代码]

更新发票状态

参考:https://work.weixin.qq.com/api/doc/90000/90135/90285

接口说明:报销企业和报销服务商可以通过该接口对某一张发票进行锁定、解锁和报销操作。

权限说明:仅认证的企业微信账号有接口权限

发报销状态如下:

  • 锁定:电子发票进入了企业的报销流程时应该执行锁定操作,执行锁定操作后的电子 发票仍然会存在于用户卡包内,但无法重复提交报销。
  • 解锁:当电子发票由于各种原因,无法完成报销流程时,应执行解锁操作。执行锁定 操作后的电子发票将恢复可以被提交的状态。
  • 报销:当电子发票报销完成后,应该使用本接口执行报销操作。执行报销操作后的 电子发票将从用户的卡包中移除,用户可以在卡包的消息中查看到电子发票的核销信息。 注意,报销为不可逆操作,请开发者慎重调用。

参数 reimburse_status 选项如下:

  • INVOICE_REIMBURSE_INIT 表示发票初始状态,未锁定;
  • INVOICE_REIMBURSE_LOCK 表示发票已锁定,无法重复提交报销;
  • INVOICE_REIMBURSE_CLOSURE 表示发票已核销,从用户卡包中移除。
参数:
  • card_id – 发票id
  • encrypt_code – 加密code
  • reimburse_status – 发报销状态
返回:

更新结果

update_status_batch(openid: str, reimburse_status: str, invoice_list: List[Dict[str, str]]) → dict[源代码]

批量更新发票状态

参考:https://work.weixin.qq.com/api/doc/90000/90135/90286

接口说明:发票平台可以通过该接口对某个成员的一批发票进行锁定、解锁和报销操作。 注意,报销状态为不可逆状态,请开发者慎重调用。

权限说明:仅认证的企业微信账号有接口权限

注意

  • 报销方须保证在报销、锁定、解锁后及时将状态同步至微信侧,保证用户发票可以正常使用
  • 批量更新发票状态接口为事务性操作,如果其中一张发票更新失败,列表中的其它发票状态 更新也会无法执行,恢复到接口调用前的状态

参数 reimburse_status 选项如下:

  • INVOICE_REIMBURSE_INIT 表示发票初始状态,未锁定;
  • INVOICE_REIMBURSE_LOCK 表示发票已锁定,无法重复提交报销;
  • INVOICE_REIMBURSE_CLOSURE 表示发票已核销,从用户卡包中移除。
参数:
  • openid – 用户openid,可用“userid与openid互换接口”获取
  • reimburse_status – 发票报销状态
  • invoice_list – 发票列表,必须全部属于同一个openid,示例: [{‘card_id’: ‘id’, ‘encrypt_code’: ‘code’}…]
返回:

更新结果

自定义菜单

class wechatpy.work.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.work.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.work.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.work.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.work.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://work.weixin.qq.com/api/doc/90001/90143/91125

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

返回的 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.work.client.api.WeChatTag(client=None)[源代码]

标签管理

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

add_users(tag_id: int, user_ids: Optional[List[str]] = None, department_ids: Optional[List[int]] = None) → dict[源代码]

增加标签成员

参考:https://work.weixin.qq.com/api/doc/90000/90135/90214

权限说明: 调用的应用必须是指定标签的创建者;成员属于应用的可见范围。

注意:每个标签下部门、人员总数不能超过3万个。

返回结果示例:

  1. 正确时返回

    {
       "errcode": 0,
       "errmsg": "ok"
    }
    
  2. 若部分userid、partylist非法,则返回

    {
       "errcode": 0,
       "errmsg": "ok",
       "invalidlist":"usr1|usr2|usr",
       "invalidparty":[2,4]
    }
    
  3. 当包含userid、partylist全部非法时返回

    {
       "errcode": 40070,
       "errmsg": "all list invalid "
    }
    

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
invalidlist 非法的成员帐号列表
invalidparty 非法的部门id列表
参数:
  • tag_id – 标签ID,非负整型
  • user_ids – 企业成员ID列表,注意:user_ids和department_ids不能同时为空, 单次请求个数不超过1000
  • department_ids – 企业部门ID列表,注意:user_ids和department_ids不能 同时为空,单次请求个数不超过100
返回:

请求结果

create(name: str, tag_id: Optional[int] = None) → dict[源代码]

创建标签

参考:https://work.weixin.qq.com/api/doc/90000/90135/90210

权限说明: 创建的标签属于该应用,只有该应用才可以增删成员。

注意: 标签总数不能超过3000个。

返回结果示例:

{
   "errcode": 0,
   "errmsg": "created"
   "tagid": 12
}

返回结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
tagid 标签id
参数:
  • name – 标签名称,长度限制为32个字以内(汉字或英文字母),标签名不可与 其他标签重名。
  • tag_id – 标签id,非负整型,指定此参数时新增的标签会生成对应的标签id,不指 定时则以目前最大的id自增。
返回:

创建结果

delete(tag_id: int) → dict[源代码]

删除标签

参考:https://work.weixin.qq.com/api/doc/90000/90135/90212

权限说明:调用的应用必须是指定标签的创建者。

返回结果示例:

{
   "errcode": 0,
   "errmsg": "deleted"
}

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
参数:tag_id – 标签ID,非负整型
返回:删除结果
delete_users(tag_id: int, user_ids: Optional[List[str]] = None, department_ids: Optional[List[int]] = None) → dict[源代码]

删除标签成员

参考:https://work.weixin.qq.com/api/doc/90000/90135/90215

权限说明: 调用的应用必须是指定标签的创建者;成员属于应用的可见范围。

返回结果示例:

  1. 正确时返回

    {
       "errcode": 0,
       "errmsg": "deleted"
    }
    
  2. 若部分userid、partylist非法,则返回

    {
       "errcode": 0,
       "errmsg": "deleted",
       "invalidlist":"usr1|usr2|usr",
       "invalidparty": [2,4]
    }
    
  3. 当包含的userid、partylist全部非法时返回

    {
       "errcode": 40031,
       "errmsg": "all list invalid"
    }
    

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
invalidlist 非法的成员帐号列表
invalidparty 非法的部门id列表
参数:
  • tag_id – 标签ID,非负整型
  • user_ids – 企业成员ID列表,注意:user_ids和department_ids不能同时为空, 单次请求长度不超过1000
  • department_ids – 企业部门ID列表,注意:user_ids和department_ids不能 同时为空,单次请求长度不超过100
返回:

处理结果

get_users(tag_id: int) → dict[源代码]

获取标签成员

参考:https://work.weixin.qq.com/api/doc/90000/90135/90213

权限说明: 无限制,但返回列表仅包含应用可见范围的成员;第三方可获取自己创建的标签及应用可见 范围内的标签详情。

返回结果示例:

{
   "errcode": 0,
   "errmsg": "ok",
   "tagname": "乒乓球协会",
   "userlist": [
         {
             "userid": "zhangsan",
             "name": "李四"
         }
     ],
   "partylist": [2]
}

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
tagname 标签名
userlist 标签中包含的成员列表
userid 成员帐号
name 成员名称,此字段从2019年12月30日起,对新创建第三方应用不再返回, 2020年6月30日起,对所有历史第三方应用不再返回,后续第三方仅通讯录应用可获取, 第三方页面需要通过通讯录展示组件来展示名字
partylist 标签中包含的部门id列表
参数:tag_id – 标签ID,非负整型
返回:成员用户信息
list() → List[dict][源代码]

获取标签列表

参考:https://work.weixin.qq.com/api/doc/90000/90135/90216

权限说明: 自建应用或通讯同步助手可以获取所有标签列表;第三方应用仅可获取自己创建的标签。

返回结果示例:

{
   "errcode": 0,
   "errmsg": "ok",
   "taglist":[
      {"tagid":1,"tagname":"a"},
      {"tagid":2,"tagname":"b"}
   ]
}

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
taglist 标签列表
tagid 标签id
tagname 标签名
返回:标签信息列表,不包含errcode等信息
update(tag_id: int, name: str) → dict[源代码]

更新标签名字

参考:https://work.weixin.qq.com/api/doc/90000/90135/90211

权限说明:调用的应用必须是指定标签的创建者。

返回结果示例:

{
   "errcode": 0,
   "errmsg": "updated"
}

结果参数说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
参数:
  • tag_id – 标签ID
  • name – 标签名称,长度限制为32个字(汉字或英文字母),标签不可与其他标签重名。
返回:

更新结果

用户管理

class wechatpy.work.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, **kwargs)[源代码]

创建成员

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

get_active_stat(date: str) → int[源代码]

获取企业活跃成员数

该接口用于获取指定日期的企业的成员活跃数量,详细接口细节请查看 接口文档

参数:date – 具体某天的活跃人数,最长支持获取30天前数据。格式为: YYYY-MM-DD
返回:成员活跃数量

警告

仅通讯录同步助手可调用。

get_join_qrcode(size_type: Optional[int] = None) → str[源代码]

获取加入企业二维码

该接口用于获取企业用户实时成员加入的二维码。详细接口细节请查看 接口文档

需要注意的是获取到的二维码链接,有效期为7天

参数:size_type – 图片尺寸类型。可用尺寸有: 1: 171 x 171; 2: 399 x 399; 3: 741 x 741(默认); 4: 2052 x 2052
返回:二维码链接

警告

使用本接口请确保开启了 通讯录同步 的API接口同步,并使用 通讯录同步secret,否则调用接口时会出现错误。

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, **kwargs)[源代码]

更新成员

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。对应管理端的帐号

外部联系人管理

class wechatpy.work.client.api.WeChatExternalContact(client=None)[源代码]

外部联系人管理

详细说明请查阅企业微信有关 外部联系人管理 的文档。

add_contact_way(type: int, scene: int, style: Optional[int] = None, remark: Optional[str] = None, skip_verify: bool = True, state: Optional[str] = None, user: List[str] = None, party: List[int] = None, is_temp: bool = False, expires_in: Optional[int] = None, chat_expires_in: Optional[int] = None, unionid: Optional[str] = None, conclusions: Optional[dict] = None) → dict[源代码]

配置客户联系「联系我」方式

详细请查阅企业微信官方文档 配置客户联系「联系我」方式 章节。

注意:

  • 每个联系方式最多配置100个使用成员(包含部门展开后的成员)
  • 当设置为临时会话模式时(即 is_tempTrue ),联系人仅支持配置为单人, 暂不支持多人
  • 使用 unionid 需要调用方(企业或服务商)的企业微信“客户联系”中已绑定微信开 发者账户

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 调用接口
result = client.external_contact.add_contact_way(
    type=1,
    scene=1,
    style=1,
    remark="渠道用户",
    skip_verify=True,
    state="teststate",
    user=["zhansan", "lisi"],
    party=[2,3],
    is_temp=True,
    expires_in=86400,
    chat_expires_in=86400,
    unionid="oxTWIuGaIt6gTKsQRLau2M0AAAA",
    conclusions={
        "text": {"content": "文本消息内容"},
        "image": {"media_id": "MEDIA_ID"},
        "link": {
            "title": "消息标题",
            "picurl": "https://example.pic.com/path",
            "desc": "消息描述",
            "url": "https://example.link.com/path",
        },
        "miniprogram": {
            "title": "消息标题",
            "pic_media_id": "MEDIA_ID",
            "appid": "wx8bd80126147dfAAA",
            "page": "/path/index.html",
        },
    },
)
# 新增联系方式的配置id
config_id = result["config_id"]
# 联系我二维码链接,仅在scene为2时返回
qr_code = result.get("qr_code")
参数:
  • type – 联系方式类型,1-单人, 2-多人
  • scene – 场景,1-在小程序中联系,2-通过二维码联系
  • style – 在小程序中联系时使用的控件样式,详见附表
  • remark – 联系方式的备注信息,用于助记,不超过30个字符
  • skip_verify – 外部客户添加时是否无需验证,默认为true
  • state – 企业自定义的state参数,用于区分不同的添加渠道,在调用 获取外部联系人详情 时会返回该参数值
  • user – 使用该联系方式的用户userID列表,在type为1时为必填,且只能有一个
  • party – 使用该联系方式的部门id列表,只在type为2时有效
  • is_temp – 是否临时会话模式,True 表示使用临时会话模式,默认为 False
  • expires_in – 临时会话二维码有效期,以秒为单位。该参数仅在 is_tempTrue 时有效,默认7天
  • chat_expires_in – 临时会话有效期,以秒为单位。该参数仅在 is_tempTrue 时有效,默认为添加好友后24小时
  • unionid – 可进行临时会话的客户unionid,该参数仅在 is_temp``True``时有效,如不指定则不进行限制
  • conclusions – 结束语,会话结束时自动发送给客户,可参考 结束语定义, 仅在 is_tempTrue 时有效
返回:

返回的 JSON 数据包

注解

调用接口应满足如下的权限要求:

  • 需要使用 客户联系secret 或配置到 可调用应用 列表中的自建应用secret 来初始化 wechatpy.work.client.WeChatClient 类。
  • 使用人员需要配置了 客户联系功能
  • 第三方调用时,应用需具有 企业客户权限
  • 第三方/自建应用调用时,传入的userid和partyid需要在此应用的可见范围内。
  • 配置的使用成员必须在企业微信激活且已经过实名认证。
  • 临时会话的二维码具有有效期,添加企业成员后仅能在指定有效期内进行会话, 仅支持医疗行业企业创建。 临时会话模式可以配置会话结束时自动发送给用户的结束语。
add_corp_tag(group_id: Optional[str], group_name: Optional[str], order: Optional[int], tags: dict) → dict[源代码]

添加企业客户标签

企业客户标签 是针对企业的外部联系人进行标记和分类的标签,由企业统一配置后,企业 成员可使用此标签对客户进行标记。

企业可通过此接口向客户标签库中添加新的标签组和标签,每个企业最多可配置3000个企业标签

详细请查阅企业微信官方文档 添加企业客户标签 章节。

参数注意事项:

  • 如果要向指定的标签组下添加标签,需要提供 group_id 参数;如果要创建一个全新的 标签组以及标签,则需要通过 group_name 参数指定新标签组名称,如果填写的 group_name 已经存在,则会在此标签组下新建标签。
  • 如果提供了 group_id 参数,则 group_name 和标签组的 order 参数 会被忽略。
  • 不支持创建空标签组。
  • 标签组内的标签不可同名,如果传入多个同名标签,则只会创建一个。

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 创建标签
result = client.external_contact.add_corp_tag(
    group_id="GROUP_ID",
    group_name="GROUP_NAME",
    order=1,
    tags=[
        {"name": "TAG_NAME_1", "order": 1},
        {"name": "TAG_NAME_2", "order": 2},
    ],
)
# 创建成功后的标签组信息
tag_group = result["tag_group"]  # type: dict
参数:
  • group_id – 标签组id
  • group_name – 标签组名称,最长为30个字符
  • order – 标签组次序值。order值大的排序靠前。有效的值范围是[0, 2^32)
  • tags – 需要添加的标签列表,标签信息是包含 name (必须)和 order (可选)两个字段的字典类型数据,比如: [{"name": 'tag_name", "order": 1}] ,或者 [{"name": "tag_name"}]
返回:

标签创建结果(字典类型,字段请参考 添加企业客户标签

注解

权限说明:

警告

暂不支持第三方调用。

add_group_welcome_template(template: dict, agentid: Optional[int] = None) → dict[源代码]

添加群欢迎语素材

企业可通过此API向企业的入群欢迎语素材库中添加素材。每个企业的入群欢迎语素材库中, 最多容纳100个素材。

详细请查阅企业微信官方文档 添加群欢迎语素材 章节。

参数:
  • template – 群欢迎语素材内容,详细字段请参考微信文档
  • agentid – 授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数
返回:

响应数据

注解

权限说明:

add_msg_template(template: dict) → dict[源代码]

添加企业群发消息模板

企业可通过此接口添加企业群发消息的任务并通知客服人员发送给相关客户或客户群。 (注:企业微信终端需升级到2.7.5版本及以上)

注意:调用该接口并不会直接发送消息给客户/客户群,需要相关的客服人员操作以后才会 实际发送(客服人员的企业微信需要升级到2.7.5及以上版本)

同一个企业每个自然月内仅可针对一个客户/客户群发送4条消息,超过限制的用户将会被忽略。

详细请查阅企业微信官方文档 添加企业群发消息任务 章节。

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
template = {
    "chat_type":"single",
    "external_userid":[
        "woAJ2GCAAAXtWyujaWJHDDGi0mACAAAA",
        "wmqfasd1e1927831123109rBAAAA"
    ],
    "sender":"zhangsan",
    "text":{
        "content":"文本消息内容"
    },
    "image":{
        "media_id":"MEDIA_ID",
        "pic_url":"http://p.qpic.cn/pic_wework/3474110808/7a6344sdadfwehe42060/0"
    },
    "link":{
        "title":"消息标题",
        "picurl":"https://example.pic.com/path",
        "desc":"消息描述",
        "url":"https://example.link.com/path"
    },
    "miniprogram":{
        "title":"消息标题",
        "pic_media_id":"MEDIA_ID",
        "appid":"wx8bd80126147dfAAA",
        "page":"/path/index.html"
    }
}
try:
    result = client.external_contact.add_msg_template(template=template)
    # 无效或无法发送的external_userid列表
    fail_list = result["fail_list"]
    # 企业群发消息的id,可用于获取群发消息发送结果
    msgid = result["msgid]
except WeChatClientException as err:
    # 接口调用失败
    ...
参数:template – 参考官方文档和使用示例
返回:请求结果(字典类型)
batch_get_by_user(userid: str, cursor: str = '', limit: int = 50) → dict[源代码]

批量获取客户详情

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 批量获取该企业员工添加的客户(外部联系人)的详情
external_contact_list = client.external_contact.batch_get_by_user("user_id", "cursor", 10)["external_contact_list"]
参数:
  • userid – 企业成员的userid
  • cursor – 用于分页查询的游标,字符串类型,由上一次调用返回,首次调用可不填
  • limit – 返回的最大记录数,整型,最大值100,默认值50,超过最大值时取最大值
返回:

包含该企业员工添加的部分客户详情列表的字典类型数据

注解

权限说明:

del_contact_way(config_id: str) → dict[源代码]

删除企业已配置的「联系我」方式

删除一个已配置的「联系我」二维码或者「联系我」小程序按钮。

详细请查阅企业微信官方文档 删除企业已配置的「联系我」方式 章节。

参数:config_id – 企业联系方式的配置id
返回:返回的 JSON 数据包

注解

调用接口应满足如下的权限要求:

  • 需要使用 客户联系secret 或配置到 可调用应用 列表中的自建应用secret 来初始化 wechatpy.work.client.WeChatClient 类。
  • 使用人员需要配置了 客户联系功能
  • 第三方调用时,应用需具有 企业客户权限
  • 第三方/自建应用调用时,传入的userid和partyid需要在此应用的可见范围内。
  • 配置的使用成员必须在企业微信激活且已经过实名认证。
  • 临时会话的二维码具有有效期,添加企业成员后仅能在指定有效期内进行会话, 仅支持医疗行业企业创建。 临时会话模式可以配置会话结束时自动发送给用户的结束语。
del_corp_tag(tag_id: Optional[str] = None, group_id: Optional[str] = None) → dict[源代码]

删除企业客户标签

企业可通过此接口删除客户标签库中的标签,或删除整个标签组。

详细请查阅企业微信官方文档 删除企业客户标签 章节。

参数注意事项:

  • tag_idgroup_id 不可同时为空。
  • 如果一个标签组下所有的标签均被删除,则标签组会被自动删除。

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
try:
    client.external_contact.del_corp_tag(tag_id="TAG_ID")
except WeChatClientException as err:
    # 标签删除失败时的处理
    ...
参数:
  • tag_id – 标签的id列表
  • group_id – 标签组的id列表
返回:

删除结果(字典类型)

注解

权限说明:

警告

暂不支持第三方调用。

del_group_welcome_template(template_id: str, agentid: Optional[int] = None) → dict[源代码]

删除入群欢迎语素材

企业可通过此API删除入群欢迎语素材,且仅能删除调用方自己创建的入群欢迎语素材。

详细请查阅企业微信官方文档 删除入群欢迎语素材 章节。

参数:
  • template_id – 群欢迎语的素材id
  • agentid – 授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数
返回:

响应数据

注解

权限说明:

edit_corp_tag(id: str, name: Optional[str] = None, order: Optional[int] = None) → dict[源代码]

编辑企业客户标签

企业可通过此接口编辑客户标签/标签组的名称或次序值。

注意: 修改后的标签组不能和已有的标签组重名,标签也不能和同一标签组下的其他标签重名。

详细请查阅企业微信官方文档 编辑企业客户标签 章节。

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 修改标签
try:
    client.external_contact.edit_corp_tag(id="TAG_ID", name="NEW_TAG_NAME")
except WeChatClientException as err:
    # 标签修改失败时的处理
    ...
参数:
  • id – 标签或标签组的id列表
  • name – 新的标签或标签组名称,最长为30个字符
  • order – 标签/标签组的次序值。order值大的排序靠前。有效的值范围是[0, 2^32)
返回:

创建结果(字典类型)

注解

权限说明:

警告

暂不支持第三方调用。

gen_all_by_user(userid: str, limit: int = 50) → Iterator[dict][源代码]

获取企业员工添加的所有客户详情列表的生成器

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
#  获取企业员工添加的所有客户详情列表
for i in client.external_contact.gen_all_by_user("user_id", 10):
    print(i)
参数:
  • userid – 企业员工userid
  • limit – 每次需要请求微信接口时返回的最大记录数,整型,最大值100,默认值50,超过最大值时取最大值
返回:

企业员工添加的所有客户详情列表的生成器

注解

权限说明:

get(external_userid: str) → dict[源代码]

获取客户详情

企业可通过此接口,根据 外部联系人的userid(如何获取?),拉取客户详情。

详细请查阅企业微信官方文档 获取客户详情 章节。

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 接口数据
data = client.external_contact.get("external_userid")
# 外部联系人的自定义展示信息
external_profile = data["external_profile"]  # type: dict
# 部联系人的企业成员userid
follow_users = data["follow_user"]  # type: List[dict]
参数:external_userid – 外部联系人的userid,注意不是企业成员的帐号
返回:用户信息(字段内容请参考官方文档 获取客户详情 章节)

注解

权限说明:

get_contact_way(config_id: str) → dict[源代码]

获取企业已配置的「联系我」方式

批量获取企业配置的「联系我」二维码和「联系我」小程序按钮。

详细请查阅企业微信官方文档 获取企业已配置的「联系我」方式 章节。

参数:config_id – 联系方式的配置id, e.g.42b34949e138eb6e027c123cba77fad7
返回:返回的 JSON 数据包

注解

调用接口应满足如下的权限要求:

  • 需要使用 客户联系secret 或配置到 可调用应用 列表中的自建应用secret 来初始化 wechatpy.work.client.WeChatClient 类。
  • 使用人员需要配置了 客户联系功能
  • 第三方调用时,应用需具有 企业客户权限
  • 第三方/自建应用调用时,传入的userid和partyid需要在此应用的可见范围内。
  • 配置的使用成员必须在企业微信激活且已经过实名认证。
  • 临时会话的二维码具有有效期,添加企业成员后仅能在指定有效期内进行会话, 仅支持医疗行业企业创建。 临时会话模式可以配置会话结束时自动发送给用户的结束语。
get_corp_tag_list(tag_ids: Optional[List[str]] = None) → dict[源代码]

获取企业标签库

企业可通过此接口获取企业客户标签详情。

企业客户标签 是针对企业的外部联系人进行标记和分类的标签,由企业统一配置后,企业 成员可使用此标签对客户进行标记。

详细请查阅企业微信官方文档 获取企业标签库 章节。

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 接口数据
data = client.external_contact.get_corp_tag_list(["tag_id1", "tag_id2"])
# 标签组列表
tag_groups = data["tag_group"]  # type: List[dict]
参数:tag_ids – 需要查询的标签id,如果为 None 则获取该企业的所有客户标签, 目前暂不支持标签组id。
返回:包含标签信息的字典类型数据(详细字段请参考 获取企业标签库

注解

权限说明:

get_follow_user_list() → dict[源代码]

获取配置了客户联系功能的成员列表

企业和第三方服务商可获取配置了客户联系功能的成员列表。

详细请查阅企业微信官方文档 获取配置了客户联系功能的成员列表 章节。

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 获取成员用户userid列表数据
follow_users = client.external_contact.get_follow_user_list()["follow_user"]
返回:配置了客户联系功能的成员用户userid信息

注解

权限说明:

get_group_chat_info(chat_id: str) → dict[源代码]

获取客户群详情

通过客户群ID,获取详情。包括群名、群成员列表、群成员入群时间、入群方式。 (客户群是由具有客户群使用权限的成员创建的外部群)

需注意的是,如果发生群信息变动,会立即收到群变更事件,但是部分信息是异步处理, 可能需要等一段时间调此接口才能得到最新结果

详细请查阅企业微信官方文档 获取客户群详情 章节。

参数:chat_id – 客户群ID
返回:响应数据

注解

权限说明:

get_group_chat_list(limit: int, status_filter: int = 0, owner_filter: Optional[dict] = None, cursor: Optional[str] = None) → dict[源代码]

获取客户群列表

该接口用于获取配置过客户群管理的客户群列表。

详细请查阅企业微信官方文档 获取客户群列表 章节。

参数:
  • limit – 分页,预期请求的数据量,取值范围 1 ~ 1000
  • status_filter – 客户群跟进状态过滤(默认为0)。 0: 所有列表(即不过滤) 1: 离职待继承 2: 离职继承中 3: 离职继承完成
  • owner_filter – 群主过滤。 如果不填,表示获取应用可见范围内全部群主的数据 (但是不建议这么用,如果可见范围人数超过1000人,为了防止数据包过大,会报错 81017)
  • cursor – 用于分页查询的游标,字符串类型,由上一次调用返回,首次调用不填
返回:

响应数据

警告

如果不指定 owner_filter,会拉取应用可见范围内的所有群主的数据, 但是不建议这样使用。如果可见范围内人数超过1000人,为了防止数据包过大, 会报错 81017。此时,调用方需通过指定 owner_filter 来缩小拉取范围。

旧版接口以 offset+limit 分页,要求 offset+limit 不能超过50000, 该方案将废弃,请改用 cursor+limit 分页。

注解

权限说明:

get_group_msg_result(msgid)[源代码]

获取企业群发消息发送结果

企业和第三方可通过该接口获取到添加企业群发消息模板生成消息的群发发送结果。 https://work.weixin.qq.com/api/doc#90000/90135/91561

参数:msgid – 群发消息的id,通过添加企业群发消息模板接口返回
返回:返回的 JSON 数据包
get_group_welcome_template(template_id: str) → dict[源代码]

获取入群欢迎语素材

企业可通过此API获取入群欢迎语素材。

详细请查阅企业微信官方文档 `获取入群欢迎语素`_ 章节。

参数:template_id – 群欢迎语的素材id
返回:响应数据

注解

权限说明:

get_unassigned_list(page_id: int = 0, page_size: int = 1000, cursor: Optional[str] = None) → dict[源代码]

获取离职成员列表

企业和第三方可通过此接口,获取所有离职成员的客户列表,并可进一步调用 分配在职或离职成员的客户 接口将这些客户重新分配给其他企业成员。

详细请查阅企业微信官方文档 获取离职成员列表 章节。

参数:
  • page_id – 分页查询,要查询页号,从0开始
  • page_size – 每次返回的最大记录数,默认为1000,最大值为1000
  • cursor – 分页查询游标,字符串类型,适用于数据量较大的情况,如果使用该参数 则无需填写page_id,该参数由上一次调用返回
返回:

响应结果

注解

page_id 为1,page_size 为100时,表示取第101到第200条记录。 由于每个成员的客户数不超过5万,故 page_id * page_size 必须小于5万。

注解

权限说明:

get_user_behavior_data(userid: Optional[List[str]], start_time: int, end_time: int, partyid: Optional[List[str]] = None) → dict[源代码]

获取「联系客户统计」数据

企业可通过此接口获取成员联系客户的数据,包括发起申请数、新增客户数、聊天数、发送消息 数和删除/拉黑成员的客户数等指标。

详细请查阅企业微信官方文档 获取「联系客户统计」数据 章节。

参数:
  • userid – userid列表
  • partyid – 部门ID列表,最多100个
  • start_time – 数据起始时间
  • end_time – 数据结束时间
返回:

返回的 JSON 数据包

引发:

AssertionError – 当userid和partyid同时为空时抛出该移除

警告

  1. useridpartyid 不可同时为空;
  2. 此接口提供的数据以天为维度,查询的时间范围为 [START_TIME,END_TIME], 即前后均为闭区间,支持的最大查询跨度为30天;
  3. 用户最多可获取最近180天内的数据;
  4. 当传入的时间不为0点时间戳时,会向下取整,如传入 1554296400(wED aPR 3 21:00:00 cst 2019) 会被自动转换为 1554220800(wED aPR 3 00:00:00 cst 2019);
  5. 如传入多个 USERID,则表示获取这些成员总体的联系客户数据。

注解

权限说明:

  • 需要使用 客户联系secret 或配置到 可调用应用 列表中的自建应用secret 来初始化 wechatpy.work.client.WeChatClient 类。
  • 第三方应用使用,需具有“企业客户权限->客户联系->获取成员联系客户的数据统计”权限。
  • 第三方/自建应用调用时传入的userid和partyid要在应用的可见范围内;
list(userid: str) → dict[源代码]

获取客户列表

企业可通过此接口获取指定成员添加的客户列表。客户是指配置了客户联系功能的成员所添加的 外部联系人。没有配置客户联系功能的成员,所添加的外部联系人将不会作为客户返回。

详细请查阅企业微信官方文档 获取客户列表 章节。

使用示例:

from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
# 获取外部联系人的userid列表
follow_users = client.external_contact.list("user_id")["external_userid"]
参数:userid – 企业成员的userid
返回:包含外部联系人的userid列表的字典类型数据

注解

权限说明:

mark_tag(userid: str, external_userid: str, add_tag: Optional[List[str]] = None, remove_tag: Optional[List[str]] = None) → dict[源代码]

编辑客户企业标签

企业可通过此接口为指定成员的客户添加上由 企业统一配置的标签

详细请查阅企业微信官方文档 编辑客户企业标签 章节。

参数注意事项:

  • 请确保 external_useriduserid 的外部联系人。
  • add_tagremove_tag 不可同时为空。
  • 同一个标签组下现已支持多个标签

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
try:
    client.external_contact.mark_tag(
        userid="USER_ID",
        external_userid="EXT_ID",
        add_tag=["TAG_ID_1", "TAG_ID_2"],
    )
except WeChatClientException as err:
    # 编辑失败时的处理
    ...
参数:
  • userid – 添加外部联系人的userid
  • external_userid – 外部联系人userid
  • add_tag – 要标记的标签列表
  • remove_tag – 要移除的标签列表
返回:

处理结果(字典类型)

注解

权限说明:

send_welcome_msg(template: dict) → dict[源代码]

发送新客户欢迎语

企业微信在向企业推送 添加外部联系人事件 时,会额外返回一个welcome_code,企业以 此为凭据调用接口,即可通过成员向新添加的客户发送个性化的欢迎语。

为了保证用户体验以及避免滥用,企业仅可在收到相关事件后20秒内调用,且只可调用一次。如 果企业已经在管理端为相关成员配置了可用的欢迎语,则推送添加外部联系人事件时不会返回 welcome_code。

每次添加新客户时 可能有多个企业自建应用/第三方应用收到带有welcome_code的回调事件, 但仅有最先调用的可以发送成功。后续调用将返回 41051(externaluser has started chatting) 错误,请用户根据实际使用需求,合理设置应用可见范围,避免冲突。

详细请查阅企业微信官方文档 发送新客户欢迎语 章节。

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
template = {
    "chat_type":"single",
    "external_userid":[
        "woAJ2GCAAAXtWyujaWJHDDGi0mACAAAA",
        "wmqfasd1e1927831123109rBAAAA"
    ],
    "sender":"zhangsan",
    "text":{
        "content":"文本消息内容"
    },
    "image":{
        "media_id":"MEDIA_ID",
        "pic_url":"http://p.qpic.cn/pic_wework/3474110808/7a6344sdadfwehe42060/0"
    },
    "link":{
        "title":"消息标题",
        "picurl":"https://example.pic.com/path",
        "desc":"消息描述",
        "url":"https://example.link.com/path"
    },
    "miniprogram":{
        "title":"消息标题",
        "pic_media_id":"MEDIA_ID",
        "appid":"wx8bd80126147dfAAA",
        "page":"/path/index.html"
    }
}
try:
    client.external_contact.send_welcome_msg(template=template)
except WeChatClientException as err:
    # 消息发送失败时的处理
    ...
参数:template – 参考官方文档和使用示例
返回:消息推送结果(字典类型)

注解

权限说明:

transfer(external_userid: str, handover_userid: str, takeover_userid: str, transfer_success_msg: Optional[str] = None) → dict[源代码]

分配在职或离职成员的客户

企业可通过此接口,转接在职成员的客户或分配离职成员的客户给其他成员。

详细请查阅企业微信官方文档 分配在职或离职成员的客户 章节。

调用参数注意事项:

  • 在某些特殊情景下,可能存在已离职的成员和当前在职的企业成员具有相同userid的情况, 此时优先分配在职成员的客户.
  • external_userid 必须是 handover_userid 的客户 (即 配置了客户联系功能 的成员所添加的联系人)。
  • 在职成员的每位客户最多被分配2次。客户被转接成功后,将有90个自然日的服务关系保护期, 保护期内的客户无法再次被分配。

使用示例:

from wechatpy.exceptions import WeChatClientException
from wechatpy.work import WeChatClient

# 需要注意使用正确的secret,否则会导致在之后的接口调用中失败
client = WeChatClient("corp_id", "secret_key")
try:
    client.external_contact.transfer(
        external_userid="woAJ2GCAAAXtWyujaWJHDDGi0mACAAAA",
        handover_userid="zhangsan",
        takeover_userid="lisi",
        transfer_success_msg="您好!",您好
    )
except WeChatClientException as err:
    # 分配失败时的处理
    ...
参数:
  • external_userid – 外部联系人的userid,注意不是企业成员的帐号
  • handover_userid – 离职成员的userid
  • takeover_userid – 接替成员的userid
  • transfer_success_msg – 转移成功后发给客户的消息,最多200个字符,不填则 使用默认文案,目前只对在职成员分配客户的情况生效
返回:

分配结果(字典类型)

注解

权限说明:

update_contact_way(config_id, remark, skip_verify=True, style=None, state=None, user=None, party=None) → dict[源代码]

更新企业已配置的「联系我」方式

更新企业配置的「联系我」二维码和「联系我」小程序按钮中的信息,如使用人员和备注等。

详细请查阅企业微信官方文档 更新企业已配置的「联系我」方式 章节。

参数:
  • config_id – 企业联系方式的配置id
  • remark – 联系方式的备注信息,不超过30个字符,将覆盖之前的备注
  • skip_verify – 外部客户添加时是否无需验证
  • style – 样式,只针对“在小程序中联系”的配置生效
  • state – 企业自定义的state参数,用于区分不同的添加渠道,在调用“获取外部联系 人详情”时会返回该参数值
  • user – 使用该联系方式的用户列表,将覆盖原有用户列表
  • party – 使用该联系方式的部门列表,将覆盖原有部门列表,只在配置的type为2时有效
返回:

返回的 JSON 数据包

注解

调用接口应满足如下的权限要求:

  • 需要使用 客户联系secret 或配置到 可调用应用 列表中的自建应用secret 来初始化 wechatpy.work.client.WeChatClient 类。
  • 使用人员需要配置了 客户联系功能
  • 第三方调用时,应用需具有 企业客户权限
  • 第三方/自建应用调用时,传入的userid和partyid需要在此应用的可见范围内。
  • 配置的使用成员必须在企业微信激活且已经过实名认证。
  • 临时会话的二维码具有有效期,添加企业成员后仅能在指定有效期内进行会话, 仅支持医疗行业企业创建。 临时会话模式可以配置会话结束时自动发送给用户的结束语。
update_group_welcome_template(template: dict, template_id: str, agentid: Optional[int] = None) → dict[源代码]

编辑群欢迎语素材

企业可通过此API编辑入群欢迎语素材库中的素材,且仅能够编辑调用方自己创建的入群欢迎语素材。

详细请查阅企业微信官方文档 `编辑群欢迎语素材`_ 章节。

参数:
  • template – 群欢迎语素材内容,详细字段请参考微信文档
  • template_id – 欢迎语素材id
  • agentid – 授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数
返回:

响应数据

注解

权限说明: