笙亿网络策划

如何在 Java 项目中集成企业微信 SDK 发送文本卡片消息

约 6 分钟读完 1 阅
文章导读
在 Java 项目中集成企业微信 SDK 发送文本卡片消息，最推荐直接调用企业微信官方提供的 Java SDK 或通过 HTTP 客户端请求发送消息 API。适用场景包括内部通知、告警推送，风险边界在于 Access Token 的有效缓存和应用权限配置。
📋 目录
  1. A 快速处理思路
  2. B 为什么会这样
  3. C 分步处理
  4. D 怎么验证是否生效
  5. E 常见坑
  6. F 常见问题
  7. G 参考来源
A A

在 Java 项目中集成企业微信 SDK 发送文本卡片消息，最推荐直接调用企业微信官方提供的 Java SDK 或通过 HTTP 客户端请求发送消息 API。适用场景包括内部通知、告警推送，风险边界在于 Access Token 的有效缓存和应用权限配置。

先说结论：集成企业微信发送文本卡片消息需先完成企业应用创建，通过 Maven 引入官方 SDK 依赖，重点处理 Access Token 获取与消息体构造。

  • 适合：Java 后端服务需要向企业微信用户或群组推送结构化通知的场景。
  • 先看：企业微信管理后台的 AgentID、Secret 配置及 IP 白名单设置。
  • 建议：自行维护 Access Token 缓存机制，避免每次发送消息都重复请求接口触发频率限制。

快速处理思路

Java 项目集成无需复杂编译操作，核心是通过构建工具引入依赖并配置认证信息。

<!-- Maven 依赖示例，具体版本号请查阅 Maven Central -->
<dependency>
    <groupId>com.tencent.wecom</groupId>
    <artifactId>wecom-java-sdk</artifactId>
    <version>latest.version</version>
</dependency>

若不使用 SDK，可直接使用 HttpClient 请求企业微信 API 接口，URL 通常为 https://qyapi.weixin.qq.com/cgi-bin/message/send。

为什么会这样

企业微信消息发送依赖_access_token_鉴权，文本卡片消息是特定的消息类型，需符合 API 定义的 JSON 结构。

企业微信开放平台采用 OAuth2.0 类似机制，服务端应用需凭 CorpID 和 Secret 换取临时凭证 Access Token。文本卡片消息（msgtype: textcard）不同于普通文本，包含标题、描述、链接和按钮，API 对字段长度和格式有严格校验，直接构造 HTTP 请求容易出错，官方 SDK 封装了签名和参数校验逻辑，能降低格式错误概率。

分步处理

按顺序完成应用配置、依赖引入、代码实现和权限检查，每步需确认对应状态。

步骤 1：获取应用凭证
操作动作：登录企业微信管理后台，进入“应用管理”，创建或选择现有应用。
验证结果：记录 CorpID、AgentID 和 Secret，确认应用可见范围包含接收消息的成员。
风险边界：Secret 泄露会导致应用权限被滥用，需存储在环境变量或配置中心，严禁硬编码在代码库。

步骤 2：引入 SDK 依赖
操作动作：在 pom.xml 或 build.gradle 中添加企业微信官方 SDK 依赖。
验证结果：执行 Maven 构建无报错，本地仓库能下载对应 jar 包。
风险边界：公开资料中没有看到可靠的量化数据表明特定版本稳定性，建议查阅 Maven Central 选择较新的稳定版本。

如何在 Java 项目中集成企业微信 SDK 发送文本卡片消息

步骤 3：获取 Access Token
操作动作：调用 SDK 的 Token 接口或请求 cgi-bin/gettoken。
验证结果：返回 JSON 中包含 errcode 0 和有效的 access_token 字符串。
风险边界：Token 有效期通常为 2 小时，频繁请求会导致接口被封禁，必须实现本地缓存。

步骤 4：构造并发送文本卡片
操作动作：实例化 TextCard 对象，设置标题、描述、链接，调用 message/send 接口。
验证结果：API 返回 errcode 0，errmsg 为 ok。
风险边界：卡片链接必须是域名备案过的 URL，否则用户在微信内无法打开。

怎么验证是否生效

通过企业微信客户端接收情况和后台日志双重确认消息送达状态。

1. 查看接收者企业微信客户端“工作台”或“消息”列表，确认是否收到卡片消息，点击卡片是否能正确跳转。
2. 检查 Java 应用日志，确认 HTTP 响应状态码为 200 且业务错误码为 0。
3. 登录企业微信管理后台，查看“应用管理”中的“发送消息”统计，确认发送量有增加。

常见坑

集成过程中容易在权限、缓存和消息格式上遇到问题，需提前规避。

  • Token 缓存失效：未处理 Token 过期逻辑，导致发送接口持续返回 40014 错误，需增加过期判断和自动刷新。
  • 用户 ID 错误：发送对象 userid 填写的是手机号或微信 openid 而非企业微信 userid，导致接收失败，需在通讯录中核对准确 ID。
  • IP 白名单限制：未在管理后台将服务器出口 IP 加入应用可信 IP 列表，导致接口返回 40164 错误。
  • 卡片内容超限：标题或描述内容超过 API 限制长度（通常标题 128 字，描述 512 字），导致发送被拒。

常见问题

发送消息返回 40003 错误怎么办

secret 错误或应用配置不匹配，需核对管理后台的 Secret 是否复制完整，确认 CorpID 与 AgentID 对应关系。

如何发送消息给整个部门

将接收者参数设置为 partyid 而非 userid，填入部门 ID 即可，但需确保应用可见范围包含该部门。

SDK 和直接 HTTP 请求有什么区别

SDK 封装了签名和对象构造，代码更简洁，HTTP 请求更灵活但需手动处理 JSON 序列化和异常。

参考来源

  • 企业微信开发者文档：发送消息 - 文本卡片消息，URL：https://developer.work.weixin.qq.com/document/path/90236
  • 企业微信开发者文档：获取 access_token，URL：https://developer.work.weixin.qq.com/document/path/91039