go-workwx (v2)

本项目需要您的帮助！

import (
    "github.com/xen0n/go-workwx/v2" // package workwx
)

A Work Weixin (a.k.a. Wechat Work) client SDK for Golang, that happens to be battle-tested and pretty serious about its types.

In production since late 2018, pushing all kinds of notifications and alerts in at least 2 of Qiniu's internal systems.

一个 Golang 企业微信客户端 SDK；碰巧在生产环境试炼过，还对类型很严肃。

自 2018 年末以来，在七牛至少 2 个内部系统运转至今，推送各种通知、告警。

English translation TODO for now, as the service covered here is not available outside of China (AFAIK).

Warning

本库的 v2 版本仍可能发生不兼容的 API 变更，如字段名、方法名调整等等，请注意。在我们处理完成所有已知的边边角角之前，不会有 v2 版本的 tag。

如果您依赖本库，请在 v2 版本的跟踪工单回复或作出表情反应，以表明态度！作者现在完全以业余时间维护本项目了，非常需要您的反馈。

Why another wheel?

工作中需要用 Go 实现一个简单的消息推送，想着找个开源库算了，然而现有唯一的开源企业微信 Golang SDK 代码质量不佳。只好自己写一个。

Update: 自从这个库写出来，已经过了很久；现在（2019.08）已经有三四个同类项目了。 不过看了看这些“竞品”，发现自己这个库的类型设计、公开接口、access token 处理等方面还不赖。 为什么人们总是喜欢写死请求 Host、用全局量、为拆包而拆包甚至不惜公开内部方法呢？

Supported Go versions

本库的 v2.x 分支最低支持到 Go 的上一个稳定版本，当前为 go1.19。 如果您需要搭配更低版本的 Go 使用，请移步 v1.x 版本，那边的代码仍然最低支持到 go1.17。

CI 会在 Go 的当前稳定版本、上一个稳定版本上跑测试，只有测试全部通过才可能合并 PR。

注意：由于 Go 上游的持续发展，我们需要能够确保相对低成本地追上节奏。 如果 go.mod 指定 Go 版本相对较低，以至于会阻碍本项目自身的功能迭代或重构了，我们不会特别考虑锁定 Go 版本的下游用户而放缓十分必要的升级。 如果您确实仍然有此类需求，请提 issue 沟通。

Features

• 包名短
• 支持覆盖 API Host，用于自己拦一层网关、临时调试等等奇葩需求
• 支持使用自定义 http.Client
• access token 处理靠谱
  • 你可以直接就做 API 调用，会自动请求 access token
  • 你也可以一行代码起一个后台 access token 刷新 goroutine
  • 自带指数退避重试
• 严肃对待类型、公开接口
  • 公开暴露接口最小化，两步构造出 WorkwxApp 对象，然后直接用
  • 刻意不暴露企业微信原始接口请求、响应类型
  • 后续可能会做一个 lowlevel 包暴露裸的 API 接口，但很可能不做
  • 不为多态而多态，宁可 SDK 内部重复代码，也保证一个接口一类动作，下游用户 static dispatch
  • 个别数据模型做了调整甚至重做（如 UserInfo、Recipient），以鼓励 idiomatic Go 风格
  • 几乎不会越俎代庖，一言不合 panic。现存的少数一些情况都是要修掉的。
• 自带一个 workwxctl 命令行小工具帮助调试
  • 用起来不爽提 issue 让我知道你在想啥

详情看 godoc 文档，还提供 Examples 小段代码可以参考。

Supported APIs

• 通讯录管理 (部分支持，见下)
• 客户联系 (大部分支持，见下)
• 微信客服 (部分支持，见下)
• 应用管理
• 消息发送 (全部支持)
• 消息接收
• 素材管理 (支持上传, 见下)
• OA (大部分支持，见下)
• 会话内容存档 (大部分支持，见下)
• 企业微信登录接口 (code2Session)
• 获取访问用户身份 (code2UserInfo)

通讯录管理 API

• 成员管理
  • 创建成员
  • 读取成员 NOTE: 成员对外信息暂未实现
  • 更新成员
  • 删除成员
  • 批量删除成员
  • 获取部门成员
  • 获取部门成员详情
  • userid与openid互换
  • 二次验证
  • 邀请成员
  • 获取加入企业二维码
  • 手机号获取userid
  • 邮箱获取userid
  • 获取成员ID列表
• 部门管理
  • 创建部门
  • 更新部门
  • 删除部门
  • 获取部门列表
  • 获取子部门ID列表
• 标签管理
  • 创建标签
  • 更新标签名字
  • 删除标签
  • 获取标签成员
  • 增加标签成员
  • 删除标签成员
  • 获取标签列表
• 异步批量接口
  • 增量更新成员
  • 全量覆盖成员
  • 全量覆盖部门
  • 获取异步任务结果
• 通讯录回调通知
  • 成员变更通知
  • 部门变更通知
  • 标签变更通知
  • 异步任务完成通知

客户联系 API

• 成员对外信息
• 企业服务人员管理
  • 获取配置了客户联系功能的成员列表
  • 客户联系「联系我」管理
  • 客户群「加入群聊」管理
• 客户管理
  • 获取客户列表
  • 获取客户详情
  • 批量获取客户详情
  • 修改客户备注信息
• 客户群管理
  • 获取客户群列表
  • 获取客户群详情
  • 客户群opengid转换
• 在职继承
  • 分配在职成员的客户
  • 查询客户接替状态
  • 分配在职成员的客户群
• 离职继承
  • 获取待分配的离职成员列表
  • 分配离职成员的客户
  • 查询客户接替状态
  • 分配离职成员的客户群
• 客户标签管理
  • 管理企业标签
  • 编辑客户企业标签
• 客户分配
  • 获取离职成员列表
  • 分配在职或离职成员的客户
  • 查询客户接替结果
  • 分配离职成员的客户群
• 变更回调通知
  • 添加企业客户事件
  • 编辑企业客户事件
  • 外部联系人免验证添加成员事件
  • 删除企业客户事件
  • 删除跟进成员事件
  • 客户接替失败事件
  • 客户群变更事件
• 消息推送
  • 创建企业群发
  • 获取企业的全部群发记录
  • 发送新客户欢迎语
  • 入群欢迎语素材管理

微信客服 API

• 客服账号管理
  • 添加客服账号
  • 删除客服账号
  • 修改客服账号
  • 获取客服账号列表
  • 获取客服账号链接
• 接待人员管理
  • 添加接待人员
  • 删除接待人员
  • 获取接待人员列表
• 会话分配与消息收发
  • 分配客服会话
  • 接收消息和事件
  • 发送消息
  • 发送欢迎语等事件响应消息
• 「升级服务」配置
• 其他基础信息获取
  • 获取客户基础信息
• 统计管理
  • 获取「客户数据统计」企业汇总数据
  • 获取「客户数据统计」接待人员明细数据
• 机器人管理
  • 知识库分组管理
  • 知识库问答管理

身份验证 API

• 获取访问用户身份

应用管理 API

• 获取应用
• 设置应用
• 自定义菜单
  • 创建菜单
  • 获取菜单
  • 删除菜单

消息发送 API

• 发送应用消息
• 接收消息
• 发送消息到群聊会话
  • 创建群聊会话
  • 修改群聊会话
  • 获取群聊会话
  • 应用推送消息

消息类型

• 文本消息
• 图片消息
• 语音消息
• 视频消息
• 文件消息
• 文本卡片消息
• 图文消息
• 图文消息（mpnews）
• markdown消息
• 任务卡片消息

素材管理 API

• 上传临时素材
• 上传永久图片
• 获取临时素材
• 获取高清语音素材

OA API

• 审批
  • 获取审批模板详情
  • 提交审批申请
  • 审批申请状态变化回调通知
  • 批量获取审批单号
  • 获取审批申请详情
  • 获取企业假期管理配置
  • 修改成员假期余额

会话内容存档 API

• 获取会话内容存档开启成员列表
• 获取会话同意情况
• 客户同意进行聊天内容存档事件回调
• 获取会话内容存档内部群信息

Notes

关于保密消息发送

Markdown 等类型消息目前不支持作为保密消息发送，强行发送会报错。 那么为何发送消息的方法还全部带着 isSafe 参数呢？

一方面，企业微信服务方完全可能在未来支持更多消息类型的保密发送，到时候不希望客户端代码重新编译； 另一方面，反正响应会报错，你也不会留着这种逻辑。因此不改了。

License

• MIT

Stargazers over time