（JAVA）自建应用调用企业微信API接口，实现消息推送

建议先简单了解企业微信开发者中心文档：开发前必读 - 文档 - 企业微信开发者中心

了解一下企业微信调用接口的基础参数：基本概念介绍 - 文档 - 企业微信开发者中心

本篇每个步骤都会跟着官网文档走，都会贴上相关链接，看完本篇文章，可以获得技能：

1、学会查看各应用的开发文档

2、学会调用接口，对接口的处理

3、学会redis和redisson的使用

4、学会封装数据传输对象（DTO）来调用接口和获取返回值

5、学会使用Spring WebFlux的非阻塞HTTP客户端的使用

实现所需以下步骤：

1、获取企业的ID和SecretID

2、根据ID和SecretID从而获取access_token

3、对access_token进行缓存

4、调用接口发送信息

1、获取企业的ID和SecretID

操作：先注册好你的企业 -> 点击头像 -> 管理企业

进入管理企业页面后

操作：应用管理 - > 创建应用

进入创建应用后

填写你的企业信息，点击创建应用

创建应用完成后

操作：返回应用管理 - > 点击你新创建的应用

1.1、获取到企业的SecretID

操作：点击查看就能获取SecretID（会发送到你的企业微信）

1.2、获取到企业的ID

操作：我的企业 - > 企业信息 - > 拉到最底下能看到企业ID

2、根据ID和SecretID从而获取access_token

文档对应位置：获取access_token - 文档 - 企业微信开发者中心

注意点：

请求方式： GET（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET

参数	必须	说明
corpid	是	企业ID，获取方式参考：术语说明-corpid
corpsecret	是	应用的凭证密钥，注意应用需要是启用状态，获取方式参考：术语说明-secret

2.1、获取access_token

1、使用postman获取

返回结果：

{ "errcode": 0, "errmsg": "ok", "access_token": "accesstoken000001", "expires_in": 7200 }

翻译：

errcode	出错返回码，为0表示成功，非0表示调用失败
errmsg	返回码提示语
access_token	获取到的凭证，最长为512字节
expires_in	凭证的有效时间（秒）

注意事项：（在文中第3点会贴出代码，来实现如何通过redis来对access_token进行缓存）
开发者需要缓存access_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access_token失效或过期时，需要重新获取。

access_token的有效期通过返回的expires_in来传达，正常情况下为7200秒（2小时）。
由于企业微信每个应用的access_token是彼此独立的，所以进行缓存时需要区分应用来进行存储。
access_token至少保留512字节的存储空间。
企业微信可能会出于运营需要，提前使access_token失效，开发者应实现access_token失效时重新获取的逻辑。

2、springboot单元测试获取

wxService代码在后面讲到redis缓存access_token时会贴上

2.2、获取失败解决 - 新版本需要加入企业可信IP

意思是不允许你当前的ip进行访问（你的ip不可信）

新版本企业微信需要配置企业可信IP才能使用

配置IP地址：

如果出现以下情况：配置企业可信IP前，请先设置可信域名或设置接收消息服务器URL

详情解决办法请看我另外一篇文章：

（JAVA）自建应用调用企业微信API接口，设置企业可信IP-CSDN博客

3、对access_token进行缓存

使用redis+redisson分布式锁，对access_token进行相关缓存操作。

代码实现：（思路逻辑都已经备注在代码里）

public String getAccessTokenByRedis() {//从redis中获取wx_access_tokenObject cacheObject = redisCache.getCacheObject("wx_access_token");//如果存在，直接返回access_tokenif(cacheObject != null){return cacheObject.toString();}//如果不存在，获取分布式锁RLock lock = redissonClient.getLock("wx_access_token_lock");//默认未上锁boolean locked = false;try {//尝试获取锁，最多等待3秒，上锁后10秒自动释放locked = lock.tryLock(3,10, TimeUnit.SECONDS);//如果获取到锁，再次从redis中获取access_token,防止在上锁期间，其他线程已经获取到锁并更新了access_token。if (locked) {cacheObject = redisCache.getCacheObject("wx_access_token");if(cacheObject != null){return cacheObject.toString();}String accessToken = getAccessTokenByApi();//企业微信接口的返回值access_token有效期为7200秒，这里存入redis设置为7000秒，防止临界值过期问题。redisCache.setCacheObject("wx_access_token", accessToken,7000, TimeUnit.SECONDS);return accessToken;}else{//未取到锁throw new RuntimeException("获取 access_token 超时，请稍后再试");}}catch (Exception e){throw new RuntimeException("Redisson 锁被中断", e);}finally {if(locked && lock.isHeldByCurrentThread()){lock.unlock();}}}

代码中的：redisCache是ruoyi框架封装好的redis工具类，调用的是redis的redisTemplate，可自行封装。

getCacheObject：

setCacheObject:

4、调用接口发送信息

了解调用消息推送的传输过程：概述 - 文档 - 企业微信开发者中心

4.1、查看发送应用消息接口文档

发送应用消息 - 文档 - 企业微信开发者中心

4.2、接口地址与请求方式

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN

参数	是否必须	说明
access_token	是	调用接口凭证

4.3、返回示例

{
"errcode" : 0,
"errmsg" : "ok",
"invaliduser" : "userid1|userid2",
"invalidparty" : "partyid1|partyid2",
"invalidtag": "tagid1|tagid2",
"unlicenseduser" : "userid3|userid4",
"msgid": "xxxx",
"response_code": "xyzxyz"
}

返回结果说明：

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
invaliduser	不合法的userid，不区分大小写，统一转为小写
invalidparty	不合法的partyid
invalidtag	不合法的标签id
unlicenseduser	没有基础接口许可(包含已过期)的userid
msgid	消息id，用于撤回应用消息
response_code	仅消息类型为“按钮交互型”，“投票选择型”和“多项选择型”的模板卡片消息返回，应用可使用response_code调用更新模版卡片消息接口，72小时内有效，且只能使用一次/4、

4.4、请求示例

4.4.1请求消息类型（文本）

{
"touser" : "UserID1|UserID2|UserID3",
"toparty" : "PartyID1|PartyID2",
"totag" : "TagID1 | TagID2",
"msgtype" : "text",
"agentid" : 1,
"text" : {
"content" : "你的快递已到，请携带工卡前往邮件中心领取。\n出发前可查看<a href=\"https://work.weixin.qq.com\">邮件中心视频实况</a>，聪明避开排队。"
},
"safe":0,
"enable_id_trans": 0,
"enable_duplicate_check": 0,
"duplicate_check_interval": 1800
}

参数说明：

参数	是否必须	说明
touser	否	指定接收消息的成员，成员ID列表（多个接收者用‘\|’分隔，最多支持1000个）。特殊情况：指定为"@all"，则向该企业应用的全部成员发送
toparty	否	指定接收消息的部门，部门ID列表，多个接收者用‘\|’分隔，最多支持100个。当touser为"@all"时忽略本参数
totag	否	指定接收消息的标签，标签ID列表，多个接收者用‘\|’分隔，最多支持100个。当touser为"@all"时忽略本参数
msgtype	是	消息类型，此时固定为：text
agentid	是	企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口获取企业授权信息获取该参数值
content	是	消息内容，最长不超过2048个字节，超过将截断（支持id转译）
safe	否	表示是否是保密消息，0表示可对外分享，1表示不能分享且内容显示水印，默认为0
enable_id_trans	否	表示是否开启id转译，0表示否，1表示是，默认0。
enable_duplicate_check	否	表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval	否	表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时

注意：touser、toparty、totag不能同时为空，后面不再强调。

注意：成员ID是企业微信的唯一标识，查看方式如下：

注意：可以进行编辑修改，只有一次机会

修改建议：企业微信成员的企业邮箱作为账号成员ID

样式如下：

4.4.2请求消息类型（文本卡片）

{
"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":"更多"
},
"enable_id_trans": 0,
"enable_duplicate_check": 0,
"duplicate_check_interval": 1800
}

参数	是否必须	说明
touser	否	成员ID列表（消息接收者，多个接收者用‘\|’分隔，最多支持1000个）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty	否	部门ID列表，多个接收者用‘\|’分隔，最多支持100个。当touser为@all时忽略本参数
totag	否	标签ID列表，多个接收者用‘\|’分隔，最多支持100个。当touser为@all时忽略本参数
msgtype	是	消息类型，此时固定为：textcard
agentid	是	企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口获取企业授权信息获取该参数值
title	是	标题，不超过128个字符，超过会自动截断（支持id转译）
description	是	描述，不超过512个字符，超过会自动截断（支持id转译）
url	是	点击后跳转的链接。最长2048字节，请确保包含了协议头(http/https)
btntxt	否	按钮文字。默认为“详情”，不超过4个文字，超过自动截断。
enable_id_trans	否	表示是否开启id转译，0表示否，1表示是，默认0
enable_duplicate_check	否	表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval	否	表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时

样式如下：

4.5接口工具测试（postman）

4.5.1、带上请求参数param

4.5.2、带上请求体

4.5.3、结果

5、使用springboot整合Spring-WebFlux开发发送消息接口

5.1、maven导入Spring-WebFlux

        <!-- webflux--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webflux</artifactId></dependency>

5.2、配置WebClient（我们只需要用到webflux的http客户端）

@Configuration
public class WebClientConfig {@Beanpublic WebClient webClient() {return WebClient.builder().defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE).build();}
}

5.3、新增数据传输对象（DTO）

根据第4节的请求示例新建DTO

5.3.1 WeChatMessageDTO

@Data
public class WeChatMessageDTO {/*** 指定接收消息的成员，成员ID列表（多个接收者用‘|’分隔，最多支持1000个）。* 特殊情况：指定为"@all"，则向该企业应用的全部成员发送*/private String touser;/*** 指定接收消息的部门，部门ID列表，多个接收者用‘|’分隔，最多支持100个。* 当touser为"@all"时忽略本参数*/private String toparty;/*** 指定接收消息的标签，标签ID列表，多个接收者用‘|’分隔，最多支持100个。* 当touser为"@all"时忽略本参数*/private String totag;/*** 消息类型,text为返回的文本*/private String msgtype;/*** 企业应用的id，整型。企业内部开发，可在应用的设置页面查看；第三方服务商，可通过接口 获取企业授权信息 获取该参数值*/private Integer agentid;/*** 	消息内容，最长不超过2048个字节，超过将截断（支持id转译）*/private WeChatTextDTO text;/*** 	卡片消息的展现形式非常灵活，支持使用br标签或者空格来进行换行处理，也支持使用div标签来使用不同的字体颜色，目前内置了3种文字颜色：灰色(gray)、高亮(highlight)、默认黑色(normal)，将其作为div标签的class属性即可，具体用法请参考上面的示例。*/private WeChatTextDTO textcard;/*** 表示是否是保密消息，0表示可对外分享，1表示不能分享且内容显示水印，默认为0*/private Integer safe;/*** 表示是否开启id转译，0表示否，1表示是，默认0。*/private Integer enable_id_trans;/*** 表示是否开启重复消息检查，0表示否，1表示是，默认0*/private Integer enable_duplicate_check;/*** 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时*/private Integer duplicate_check_interval;//touser、toparty、totag不能同时为空，后面不再强调。
}

5.3.2 WeChatTextDTO

@Data
public class WeChatTextDTO {//text专用private String content;//消息内容，最长不超过2048个字节，超过将截断（支持id转译）//textcard专用private String title;//标题，不超过128个字符，超过会自动截断（支持id转译）private String description;//描述，不超过512个字符，超过会自动截断（支持id转译）private String url;//点击后跳转的链接。最长2048字节，请确保包含了协议头(http/https)private String btntxt;//按钮文字。 默认为“详情”， 不超过4个文字，超过自动截断。//图文、语音、视频等...}

5.4 WxService

@Service
public class WxService {@Autowiredprivate WebClient webClient;@Autowiredprivate RedisCache redisCache;@Autowiredprivate RedissonClient redissonClient;private static final Logger logger = LoggerFactory.getLogger(WxService.class);//企业微信所需凭证private static final String corpid = "在第一节的1.2获取到的企业ID";private static final String corpsecret = "在一节的1.1获取到的企业SecretID";private String getAccessTokenByApi(){String url = "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=" + corpid + "&corpsecret=" + corpsecret;Map<String, Object> response = webClient.get().uri(url).retrieve().bodyToMono(new ParameterizedTypeReference<Map<String, Object>>() {}).block();if (response == null || !response.containsKey("access_token")) {throw new RuntimeException("获取 access_token 失败：" + response);}return response.get("access_token").toString();}public String getAccessTokenByRedis() {//从redis中获取wx_access_tokenObject cacheObject = redisCache.getCacheObject("wx_access_token");//如果存在，直接返回access_tokenif(cacheObject != null){return cacheObject.toString();}//如果不存在，获取分布式锁RLock lock = redissonClient.getLock("wx_access_token_lock");//默认未上锁boolean locked = false;try {//尝试获取锁，最多等待3秒，上锁后10秒自动释放locked = lock.tryLock(3,10, TimeUnit.SECONDS);//如果获取到锁，再次从redis中获取access_token,防止在上锁期间，其他线程已经获取到锁并更新了access_token。if (locked) {cacheObject = redisCache.getCacheObject("wx_access_token");if(cacheObject != null){return cacheObject.toString();}String accessToken = getAccessTokenByApi();//企业微信接口的返回值access_token有效期为7200秒，这里设置为7000秒，防止临界值过期问题。//将access_token存入redis，有效期7000秒。redisCache.setCacheObject("wx_access_token", accessToken,7000, TimeUnit.SECONDS);return accessToken;}else{//未取到锁throw new RuntimeException("获取 access_token 超时，请稍后再试");}}catch (Exception e){throw new RuntimeException("Redisson 锁被中断", e);}finally {if(locked && lock.isHeldByCurrentThread()){lock.unlock();}}}public Map<String,Object> pushMessage(WeChatMessageDTO weChatMessageDTO){String accessToken = getAccessTokenByRedis();String url = "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token="+accessToken;return webClient.post().uri(url).contentType(MediaType.APPLICATION_JSON).bodyValue(weChatMessageDTO).retrieve().bodyToMono(new ParameterizedTypeReference<Map<String, Object>>() {}).block(); // 阻塞获取响应（适用于同步调用场景）}/*** 推送企业微信通知*/public void sendWeChatNotification(String title, String content, String receiverWxId) {try {WeChatTextDTO textDTO = new WeChatTextDTO();textDTO.setTitle(title);textDTO.setDescription(content);textDTO.setUrl("填写你要跳转的URL");textDTO.setBtntxt("点击查看");WeChatMessageDTO messageDTO = new WeChatMessageDTO();messageDTO.setTouser(receiverWxId);messageDTO.setMsgtype("textcard");messageDTO.setAgentid(1000002);messageDTO.setTextcard(textDTO);Map<String, Object> result = pushMessage(messageDTO);logger.info("企业微信推送结果: {}", result);} catch (Exception e) {logger.error("企业微信推送失败", e);}}}

5.5 WxTest

使用springboot的单元测试来测试。

@SpringBootTest
@DisplayName("单元测试案例")
public class WxTest {@Autowiredprivate WxService wxService;@DisplayName("获取accessToken")@Testpublic void test1(){//获取accessTokenString accessToken = wxService.getAccessTokenByRedis();System.out.println("accessToken:"+accessToken);}@DisplayName("推送信息-文本")@Testpublic void test2(){WeChatTextDTO weChatTextDTO = new WeChatTextDTO();weChatTextDTO.setContent("私聊测试");WeChatMessageDTO weChatMessageDTO = new WeChatMessageDTO();weChatMessageDTO.setTouser("ChenPengWei");//填入企业ID则是私聊weChatMessageDTO.setMsgtype("text");weChatMessageDTO.setAgentid(1000002);weChatMessageDTO.setText(weChatTextDTO);Map<String,Object> map = wxService.pushMessage(weChatMessageDTO);System.out.println(map);}@DisplayName("推送信息-文本卡片")@Testpublic void test3(){WeChatTextDTO weChatTextDTO = new WeChatTextDTO();weChatTextDTO.setTitle("CRM系统通知");weChatTextDTO.setDescription("<div class=\"gray\">2025年07月01日</div> <div class=\"normal\">天气不错</div><div class=\"highlight\">在一个阳光明媚的下午....</div>");weChatTextDTO.setUrl("https://www.baidu.com");weChatTextDTO.setBtntxt("点击查看");WeChatMessageDTO weChatMessageDTO = new WeChatMessageDTO();weChatMessageDTO.setTouser("@all");//@all是公告，群广播weChatMessageDTO.setMsgtype("textcard");weChatMessageDTO.setAgentid(1000002);weChatMessageDTO.setTextcard(weChatTextDTO);//textcardMap<String,Object> map = wxService.pushMessage(weChatMessageDTO);System.out.println(map);}}

效果图：

小弹窗：