Java集成企业微信API实现高效消息推送实战指南

一、场景概述

企业微信作为企业级协同办公平台，其消息通知能力可无缝集成到内部系统中。本文将通过Java代码示例，详细讲解如何快速对接企业微信API，实现自动化消息推送功能，适用于告警通知、审批提醒等业务场景。

二、前置条件准备

1. 企业微信管理后台配置

   • 登录企业微信管理后台

   • 进入「应用管理」→ 创建/选择自建应用

   • 记录关键参数：

     • AgentId（应用ID）

     • Secret（应用密钥）

     • CorpId（企业ID，位于「我的企业」页面）

   • 如下图：这里创建了一个用来消息提醒的应用，拿到id和密钥即可。

2. 核心代码实现（发送文本消息）

   1、配置企业id，应用id和密钥
   
   2、编写配置类用来读取

   @Configuration
   public class WeChatConfig {
   
       @Value("${wechat.corpId}")
       private String corpId;
   
       @Value("${wechat.secret}")
       private String secret;
   
       @Value("${wechat.tokenUrl}")
       private String tokenUrl;
   
       @Value("${wechat.agentId}")
       private String agentId;
   
       // 获取 AccessToken 的 URL
       public String getAccessTokenUrl() {
           return tokenUrl + "?corpid=" + corpId + "&corpsecret=" + secret;
       }
   
       /**
        * 其他配置，如 AgentId 等
        */
       public String getAgentId() {
           return agentId;
       }
   }

   3、编写获取企微签名相关代码
     注意：这里签名缓存自行设置，不需要每次就去调用企微api，签名失效时间2小时，可自行设置缓存过期时间，我这里利用的redis

   @Service
   public class WeChatService {
       private static final Logger logger = LoggerFactory.getLogger(WeChatService.class);
   
       @Autowired
       private WeChatConfig weChatConfig;
   
       /**
        * Redis 缓存 access_token 的 key
        */
       private static final String QW_ACCESS_TOKEN_CACHE_KEY = "shxd:dekt:qw:access:token";
   
       public String getAccessToken() {
           Object redisResult = NHRedisUtils.getRedisResult(QW_ACCESS_TOKEN_CACHE_KEY);
           if (redisResult == null) {
               String newToken = refreshAccessToken();
               if (newToken == null) {
                   throw new RuntimeException("无法获取企业微信 AccessToken");
               }
               return newToken;
           }
           return String.valueOf(redisResult);
       }
   
       private String refreshAccessToken() {
           try {
               String url = weChatConfig.getAccessTokenUrl();
               RestTemplate restTemplate = new RestTemplate();
               String response = restTemplate.getForObject(url, String.class);
               JSONObject jsonObject = new JSONObject(response);
               logger.error("获取企业微信 token 成功：{}", jsonObject);
   
               String accessToken = jsonObject.getString("access_token");
               if (accessToken == null || accessToken.isEmpty()) {
                   logger.error("获取企业微信 AccessToken 失败，返回为空");
                   return null;
               }
               // 加入 Redis，缓存 110 分钟（提前 10 分钟刷新）
               NHRedisUtils.addRedis(QW_ACCESS_TOKEN_CACHE_KEY, 110, accessToken);
               return accessToken;
           } catch (Exception e) {
               logger.error("获取企业微信 AccessToken 失败", e);
               return null;
           }
       }
   }

   4、发送消息
    

   @Service
   public class WeChatMessageService {
       private static final Logger logger = LoggerFactory.getLogger(WeChatMessageService.class);
   
       @Autowired
       private WeChatService weChatService;
       @Autowired
       private WeChatConfig weChatConfig;
   
       private static final String SEND_MESSAGE_URL = "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=";
   
       public boolean sendTextMessage(String userId, String content) {
           // 获取 AccessToken
           String accessToken = weChatService.getAccessToken();
           String url = SEND_MESSAGE_URL + accessToken;
   
           // 构造请求体
           JSONObject message = new JSONObject();
           message.put("touser", userId);
           message.put("msgtype", "text");
           message.put("agentid", weChatConfig.getAgentId());
           JSONObject text = new JSONObject();
           text.put("content", content);
           message.put("text", text);
   
           try {
               RestTemplate restTemplate = new RestTemplate();
               // 移除默认的StringHttpMessageConverter（这里防止中文乱码）
               restTemplate.getMessageConverters().removeIf(converter ->
                       converter instanceof StringHttpMessageConverter);
               // 添加支持UTF-8的StringHttpMessageConverter
               StringHttpMessageConverter converter = new StringHttpMessageConverter(StandardCharsets.UTF_8);
               converter.setWriteAcceptCharset(false); // 重要！关闭默认字符集
               restTemplate.getMessageConverters().add(0, converter);
   
               // 设置请求头，确保 Content-Type 是 UTF-8
               HttpHeaders headers = new HttpHeaders();
               headers.setContentType(MediaType.APPLICATION_JSON);
               headers.setAcceptCharset(Collections.singletonList(StandardCharsets.UTF_8));
               HttpEntity<String> request = new HttpEntity<>(message.toJSONString(), headers);
               String response = restTemplate.postForObject(url, request, String.class);
               logger.error("发送企业微信消息返回数据：{}", response);
               // 解析返回结果
               JSONObject jsonResponse = JSONObject.parseObject(response);
               int errcode = jsonResponse.getIntValue("errcode");
               if (errcode == 0) {
                   return true;
               } else {
                   logger.error("发送企业微信消息失败，错误码：{}，错误信息：{}", errcode, jsonResponse.getString("errmsg"));
                   return false;
               }
           } catch (Exception e) {
               logger.error("发送企业微信消息请求失败", e);
               return false;
           }
       }
   }

   5、编写controller进行测试
   第一个参数为企微用户名，第二个为发送内容。
   
   结果如下：
   

3. 发送图文消息
   只需改变消息体即可，如下
    

           // 构造请求体
           JSONObject message = new JSONObject();
           message.put("touser", userId);
           message.put("msgtype", "news");
           message.put("agentid", weChatConfig.getAgentId());
           // 创建 articles 数组
           JSONArray articles = new JSONArray();
           JSONObject article = new JSONObject();
           article.put("title", "标题");         // 图文标题（必填）
           article.put("description", "我是描述"); // 图文描述
           article.put("url", "https://xf.xdsisu.edu.cn/ydxg");             // 点击后跳转链接
           article.put("picurl", "https://img0.baidu.com/it/u=1077282731,2234353719&fm=253&fmt=auto&app=120&f=JPEG?w=800&h=800");       // 图文封面的图片链接（可选）
   
           articles.add(article);
   
           JSONObject news = new JSONObject();
           news.put("articles", articles);
           message.put("news", news);
           message.put("safe", 0);

   效果如下：
   
   注意：一定要在应用里面配置可信域名，不然会出现{"errcode":60020,"errmsg":"not allow to access from your ip  ip不被允许访问的错误信息

4. 扩展
   如果是本地图片，没有地址的话，可以调用企微的上传图片接口，会返回给你一个url，这个url在企微内部永久有效。上传图片文档地址
   
   代码如下：
    

       public String uploadImage(byte[] bytes, String accessToken) {
           if (bytes == null || bytes.length == 0) {
               return null;
           }
           try {
               // 构建请求
               String uploadUrl = "https://qyapi.weixin.qq.com/cgi-bin/media/uploadimg?access_token="+accessToken;
               HttpEntity<MultiValueMap<String, Object>> requestEntity = buildRequestEntity(bytes);
               logger.error("开始上传图片，数据大小：{} bytes", bytes.length);
               // 发送请求
               ResponseEntity<String> response = restTemplate.postForEntity(uploadUrl, requestEntity, String.class);
               // 响应处理
               // 解析JSON响应
               String responseBody = response.getBody();
               if (StringUtils.isBlank(responseBody)) {
                   logger.error("图片上传返回空响应");
                   return null;
               }
               com.alibaba.fastjson.JSONObject json = com.alibaba.fastjson.JSON.parseObject(responseBody);
               int errcode = json.getIntValue("errcode");
               if (errcode != 0) {
                   String errmsg = json.getString("errmsg");
                   logger.error("图片上传失败，错误码：{}，错误信息：{}", errcode, errmsg);
                   return null;
               }
               String url = json.getString("url");
               if (StringUtils.isBlank(url)) {
                   logger.error("图片上传成功但未返回url");
                   return null;
               }
               logger.error("图片上传成功，url：{}", url);
               return url;
           } catch (RestClientException e) {
               logger.error("图片上传请求失败，accessToken：{}", accessToken, e);
           } catch (JSONException e) {
               logger.error("响应数据解析失败", e);
           }
           return null;
       }