简介这是一份面向C#开发者的微信企业号主动推送消息功能示例工程适合需要对接企业号API、实现文本、图片、语音、视频及图文消息发送的开发者也适用于希望在企业内部系统或业务平台中嵌入消息通知的团队。压缩包内共40个文件以22个C#源文件为核心覆盖配置类、消息实体、发送辅助类等模块另含3个工程文件、1个解决方案文件及配置文件可在Visual Studio中直接打开调试。资源整体仅35KB代码精简没有冗余依赖。目前已有874人学习下载。通过阅读源码可以理解AppID与AppSecret的配置方式、官方SDK的封装思路、五类消息对象的构建方法以及上传临时素材获取媒体ID、调用SendMessage接口发送并处理返回结果的完整流程同时还包括用户关注、菜单点击等事件监听的响应方式是一份便于迁移到实际企业号项目中的轻量参考实现。1. 微信企业号主动推送一份 C# 资源包解决通知到达率的老大难做企业内部系统时间长了你会发现一个共性痛点OA 待办、工单提醒、告警通知光靠邮件和短信根本不够——邮件没人及时看短信要花钱还有长度限制。微信企业号主动推送消息就成了最务实的方案员工微信里直接收应用消息点开即处理到达率远高于邮件。这份 C# 资源包就是干这个事的它把「企业号应用配置 → 获取 access_token → 组装消息体 → 调用发送接口 → 处理返回结果」整条链路封装好了拿到就能跑适合做企业内部管理系统、运维告警平台、工单系统的开发者。我拆这份资源时的第一印象是它没有把最核心的难点藏着掖着。企业号接口调用本身的坑不在 HTTP 请求而在 token 的过期缓存、消息类型的选择、可见范围与 agentid 的对应关系。下文先把原理讲透再给可直接抄的代码最后把我踩过的坑一条条列出来。2. 主动推送的核心链路从 access_token 到消息送达2.1 为什么需要 access_token以及它的缓存策略微信企业号现在叫企业微信但旧接口仍兼容的主动推送接口几乎所有操作都要求先拿 access_token。这个 token 是全局凭证有效期为 7200 秒但接口有调用频率限制。如果每次发消息都重新请求 token不仅浪费配额还可能因为频率超限被暂时封禁。所以正规做法是token 拿到后缓存起来快过期再去刷新。资源包里的 TokenManager 类做的是标准方案——首次启动时请求一次之后每次调用前检查本地时间戳与「过期时间」的差值剩余不足 5 分钟就主动刷新用锁防止并发请求时多个线程同时刷新 token。这比每次现取现用的写法严谨得多。2.2 消息体结构Text 与 TextCard 的选择企业号主动推送支持多种消息类型text、textcard、news、markdown 等。text 是最简单的纯文本适合简单提醒textcard 是卡片样式带标题、描述和跳转链接适合需要「点击详情去处理」的场景比如工单待办。textcard 的消息体格式如下{ touser: userid1|userid2, msgtype: textcard, agentid: 1000002, textcard: { title: 有新的待办工单, description: 工单 #2024001 等待处理\n请及时查看, url: https://oa.internal.example.com/todo/2024001, btntxt: 去处理 } }touser是企业成员的用户 ID不是手机号也不是姓名多个接收人用竖线分隔agentid是自建应用的 ID必须与消息所属应用一致。description里支持\n换行但需注意转义处理。资源包里封装了TextCardMessage构建方法传标题、描述、URL 进去即可避免手拼 JSON 出错。2.3 可见范围与 agentid一对最容易配错的参数有个概念容易绕晕agentid 是应用的唯一标识而应用的「可见范围」决定了哪些部门/成员能收到消息。如果发送时指定的 touser 不在应用的可见范围内接口会返回 60011 错误没有权限。这不是代码 bug而是企业号后台的配置问题。资源包的配置文件中预设了 agentid 参数但每个企业的 agentid 都不同。拿到资源后第一件事不是改代码而是去企业号后台找到自建应用的 agentid填写到配置里。3. 资源包落地把 C# 代码跑通并推送到你的微信3.1 项目结构与关键文件定位解压资源包后核心文件集中在三个位置文件/目录作用TokenManager.csaccess_token 的获取与缓存逻辑MessageSender.cs消息体构建与 HTTP 发送封装App.config企业号 CorpID、Secret、AgentId 配置Demo/一个控制台调用示例可直接运行先打开App.config把三个必填项填好企业号的 CorpID每个企业唯一、自建应用的 Secret、应用的 AgentId。这三项缺一不可且注意不要与「企业微信」的 Secret 混淆。3.2 发送一条文本消息的最小可运行代码以下是最小可运行的发送逻辑参考了资源包里 Demo 的调用方式using System; using EnterpriseWeChat.Push; class Program { static void Main(string[] args) { var config ConfigManager.LoadFromAppConfig(); var tokenManager new TokenManager(config.CorpId, config.Secret); var sender new MessageSender(tokenManager, config.AgentId); string userId zhangsan; // 企业号后台的 UserID不是微信号 string content 你的请假申请已通过审批请留意后续安排。; var result sender.SendText(userId, content); if (result.IsSuccess) { Console.WriteLine(消息发送成功); } else { Console.WriteLine($发送失败: {result.ErrorCode} {result.ErrorMessage}); } } }这里的关键点是Sender.SendText内部做了三件事先从 TokenManager 取当前可用的 token组装 text 消息体用 HttpClient 向企业号接口发 POST 请求。result.IsSuccess判断的是 HTTP 层面的返回码与业务返回码errcode 0同时成立不是只看网络通不通。我习惯在实际项目里把返回结果整体打日志包括errcode和errmsg这样排查问题能省一半时间。3.3 调试时的两个本地验证手段在没有真实企业号配置时可以用两个手段验证代码是否正确其一企业号接口支持touserall向应用可见范围内的所有人发送调试初期可以用它替代指定用户其二用 Postman 或 curl 手动请求一次发送接口排除 C# 代码层的问题。curl 示例如下curl -X POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_tokenYOUR_TOKEN \ -H Content-Type: application/json \ -d {touser:zhangsan,msgtype:text,agentid:1000002,text:{content:测试消息}}如果 curl 能发出去而 C# 代码失败问题基本在代码层的参数构造或 token 获取上。这个排查思路能帮你快速缩小范围。4. 避坑指南企业号推送开发中四个高频翻车点4.1 token 失效报错 40014现象程序运行一段时间后突然推送失败返回errcode: 40014, errmsg: invalid access_token。原因access_token 有效期是 7200 秒但如果你手动用 curl 或 Postman 请求过 token会生成新 token 并把旧的顶掉。你本地代码里缓存的还是旧 token自然失效。解决TokenManager 里要捕获 40014 错误遇到后强制清理本地缓存并重新获取 token。我一般会加一个「重试一次」的逻辑发送失败且错误码是 40014 时刷新 token 后重新发送。4.2 接口报 60011 没有权限现象明明用对了 UserID但提示 60011。原因该用户不在应用的可见范围内或者 UserID 写错——把登录名、手机号、姓名当成了 UserID。企业号后台的 UserID 在「通讯录-成员详情」里看。解决先在后台确认目标用户所属部门已添加到应用的可见范围再复制后台的 UserID 粘贴进代码不要手敲。如果确认无误仍报错检查代码里是否误用了touser之外的空格或竖线分隔错误。4.3 消息发出去了但部分人收不到现象同一部门里 A 能收到B 收不到或者发送时报成功但全员都没收到。原因最常见的是应用的可见范围只覆盖了部分部门而touser用了all或是批量用户组。其次是消息被微信折叠进「服务通知」里员工没注意看。解决发送前在后台核对可见范围发送后让收不到的人检查微信的「企业号」会话是否存在必要时在后台把应用的「消息接收方式」改为「实时接收」。这类问题不是代码能兜底的要在交付说明里讲清楚。4.4 多线程环境下 token 被并发刷新现象并发推送场景下日志里频繁出现「刷新 token」的提示且偶发 40014。原因多个线程同时发现 token 即将过期各自发起刷新请求导致旧 token 立即失效。解决TokenManager 内部加锁或用SemaphoreSlim控制刷新区间保证同一时间只有一个线程在刷新。资源包里已有基础锁实现但如果你在高并发环境使用建议把锁粒度放大到整个 token 检查 刷新过程。5. 进阶消息模板化与发送结果回执的定制5.1 把固定文案抽成模板匹配业务场景实际开发中不要每次硬编码消息内容建议把消息文案抽成模板。我一般这样做在配置库里存模板内容里保留占位符{name}、{orderId}、{status}运行时替换。string template 客户{name}的订单{orderId}已{status}请及时关注。; string content template .Replace({name}, customerName) .Replace({orderId}, orderId) .Replace({status}, statusText);这样做的好处是产品改文案时不用改代码重新发布运营可以直接维护模板。资源包里没有现成的模板引擎但这个替代方案几行就能实现比引入大型模板库更轻量。5.2 记录发送回执做失败重试机制企业号接口只保证「提交成功」不等于「送达成功」。如果成员取消关注或长时间不活跃消息可能一直处于「未读」状态。订单一类的关键通知需要补一条短信或站内信兜底。我的习惯是发送后把 taskid 和发送时间记录到数据库每 10 分钟跑一次任务查回执状态超过 30 分钟仍「未读」的转短信通道补发。回调接口的配置是个容易被忽略的坑企业号支持接收消息回执的「回调 URL」但需要你提供一个公网可达的地址且要完成 URL 验证。如果你在内网开发这段时间会被卡住——但这部分和推送功能本身解耦可以先不做。5.3 批量发送的正确姿势分批而非一次性企业号接口对批量发送有数量上限单次 touser 上限 1000 人超过会报错。如果你要推全员建议按部门分批发送每批 200 人左右中间 sleep 200 毫秒避免触发频率限制。常见做法是用一个简单的 for 循环分批foreach (var batch in userList.Chunk(200)) { string touser string.Join(|, batch); sender.SendText(touser, content); Thread.Sleep(200); }注意Chunk是 .NET 6 后才有的 API项目若是 .NET Framework 需要自己写分组逻辑。这个分批策略不仅能绕过上限还能在某一批失败时准确定位是哪批出了问题。5.4 从「发出去」到「有人处理」用回调数据倒逼闭环推送只是第一步真正要做的是「发了 → 看了 → 处理了」的闭环。资源包止步于发送成功但你在真实系统里还要关心回调接口——它会告诉你成员是否点击了卡片。把这些数据存起来才能做后续的「未读二次提醒」「超时升级到短信」策略。我的习惯是设计一张push_records表包含msg_id、userid、status、send_time、read_time五个字段。发送接口返回的msgid与回调里的MsgId对应上才能做状态流转。这套思路放进去后「推送功能」就从工具变成了业务闭环的一部分。我记得第一次做企业号推送时卡在 60011 上整整半天——最后发现是后台的可见范围没勾选新入职部门。代码没问题配置没到位那种无力感是导致我现在每次拿到这类资源都会先写「配置检查清单」的原因第一步核对 CorpID、Secret、AgentId第二步核对用户 UserID 与可见范围第三步用 curl 验证接口通不通第四步才跑代码。从那以后我每接手一个推送项目都强制走一遍这个流程没再翻过车。希望这篇拆解能帮你把这条链路走顺拿到资源后直接落地到你的系统里。本文还有配套的精品资源点击获取 
长河君 · 2026/10/21 2:43:26 · 阅读 1.2k 微信企业号主动推送C#资源包：从access_token到消息送达
简介这是一份面向C#开发者的微信企业号主动推送消息功能示例工程适合需要对接企业号API、实现文本、图片、语音、视频及图文消息发送的开发者也适用于希望在企业内部系统或业务平台中嵌入消息通知的团队。压缩包内共40个文件以22个C#源文件为核心覆盖配置类、消息实体、发送辅助类等模块另含3个工程文件、1个解决方案文件及配置文件可在Visual Studio中直接打开调试。资源整体仅35KB代码精简没有冗余依赖。目前已有874人学习下载。通过阅读源码可以理解AppID与AppSecret的配置方式、官方SDK的封装思路、五类消息对象的构建方法以及上传临时素材获取媒体ID、调用SendMessage接口发送并处理返回结果的完整流程同时还包括用户关注、菜单点击等事件监听的响应方式是一份便于迁移到实际企业号项目中的轻量参考实现。1. 微信企业号主动推送一份 C# 资源包解决通知到达率的老大难做企业内部系统时间长了你会发现一个共性痛点OA 待办、工单提醒、告警通知光靠邮件和短信根本不够——邮件没人及时看短信要花钱还有长度限制。微信企业号主动推送消息就成了最务实的方案员工微信里直接收应用消息点开即处理到达率远高于邮件。这份 C# 资源包就是干这个事的它把「企业号应用配置 → 获取 access_token → 组装消息体 → 调用发送接口 → 处理返回结果」整条链路封装好了拿到就能跑适合做企业内部管理系统、运维告警平台、工单系统的开发者。我拆这份资源时的第一印象是它没有把最核心的难点藏着掖着。企业号接口调用本身的坑不在 HTTP 请求而在 token 的过期缓存、消息类型的选择、可见范围与 agentid 的对应关系。下文先把原理讲透再给可直接抄的代码最后把我踩过的坑一条条列出来。2. 主动推送的核心链路从 access_token 到消息送达2.1 为什么需要 access_token以及它的缓存策略微信企业号现在叫企业微信但旧接口仍兼容的主动推送接口几乎所有操作都要求先拿 access_token。这个 token 是全局凭证有效期为 7200 秒但接口有调用频率限制。如果每次发消息都重新请求 token不仅浪费配额还可能因为频率超限被暂时封禁。所以正规做法是token 拿到后缓存起来快过期再去刷新。资源包里的 TokenManager 类做的是标准方案——首次启动时请求一次之后每次调用前检查本地时间戳与「过期时间」的差值剩余不足 5 分钟就主动刷新用锁防止并发请求时多个线程同时刷新 token。这比每次现取现用的写法严谨得多。2.2 消息体结构Text 与 TextCard 的选择企业号主动推送支持多种消息类型text、textcard、news、markdown 等。text 是最简单的纯文本适合简单提醒textcard 是卡片样式带标题、描述和跳转链接适合需要「点击详情去处理」的场景比如工单待办。textcard 的消息体格式如下{ touser: userid1|userid2, msgtype: textcard, agentid: 1000002, textcard: { title: 有新的待办工单, description: 工单 #2024001 等待处理\n请及时查看, url: https://oa.internal.example.com/todo/2024001, btntxt: 去处理 } }touser是企业成员的用户 ID不是手机号也不是姓名多个接收人用竖线分隔agentid是自建应用的 ID必须与消息所属应用一致。description里支持\n换行但需注意转义处理。资源包里封装了TextCardMessage构建方法传标题、描述、URL 进去即可避免手拼 JSON 出错。2.3 可见范围与 agentid一对最容易配错的参数有个概念容易绕晕agentid 是应用的唯一标识而应用的「可见范围」决定了哪些部门/成员能收到消息。如果发送时指定的 touser 不在应用的可见范围内接口会返回 60011 错误没有权限。这不是代码 bug而是企业号后台的配置问题。资源包的配置文件中预设了 agentid 参数但每个企业的 agentid 都不同。拿到资源后第一件事不是改代码而是去企业号后台找到自建应用的 agentid填写到配置里。3. 资源包落地把 C# 代码跑通并推送到你的微信3.1 项目结构与关键文件定位解压资源包后核心文件集中在三个位置文件/目录作用TokenManager.csaccess_token 的获取与缓存逻辑MessageSender.cs消息体构建与 HTTP 发送封装App.config企业号 CorpID、Secret、AgentId 配置Demo/一个控制台调用示例可直接运行先打开App.config把三个必填项填好企业号的 CorpID每个企业唯一、自建应用的 Secret、应用的 AgentId。这三项缺一不可且注意不要与「企业微信」的 Secret 混淆。3.2 发送一条文本消息的最小可运行代码以下是最小可运行的发送逻辑参考了资源包里 Demo 的调用方式using System; using EnterpriseWeChat.Push; class Program { static void Main(string[] args) { var config ConfigManager.LoadFromAppConfig(); var tokenManager new TokenManager(config.CorpId, config.Secret); var sender new MessageSender(tokenManager, config.AgentId); string userId zhangsan; // 企业号后台的 UserID不是微信号 string content 你的请假申请已通过审批请留意后续安排。; var result sender.SendText(userId, content); if (result.IsSuccess) { Console.WriteLine(消息发送成功); } else { Console.WriteLine($发送失败: {result.ErrorCode} {result.ErrorMessage}); } } }这里的关键点是Sender.SendText内部做了三件事先从 TokenManager 取当前可用的 token组装 text 消息体用 HttpClient 向企业号接口发 POST 请求。result.IsSuccess判断的是 HTTP 层面的返回码与业务返回码errcode 0同时成立不是只看网络通不通。我习惯在实际项目里把返回结果整体打日志包括errcode和errmsg这样排查问题能省一半时间。3.3 调试时的两个本地验证手段在没有真实企业号配置时可以用两个手段验证代码是否正确其一企业号接口支持touserall向应用可见范围内的所有人发送调试初期可以用它替代指定用户其二用 Postman 或 curl 手动请求一次发送接口排除 C# 代码层的问题。curl 示例如下curl -X POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_tokenYOUR_TOKEN \ -H Content-Type: application/json \ -d {touser:zhangsan,msgtype:text,agentid:1000002,text:{content:测试消息}}如果 curl 能发出去而 C# 代码失败问题基本在代码层的参数构造或 token 获取上。这个排查思路能帮你快速缩小范围。4. 避坑指南企业号推送开发中四个高频翻车点4.1 token 失效报错 40014现象程序运行一段时间后突然推送失败返回errcode: 40014, errmsg: invalid access_token。原因access_token 有效期是 7200 秒但如果你手动用 curl 或 Postman 请求过 token会生成新 token 并把旧的顶掉。你本地代码里缓存的还是旧 token自然失效。解决TokenManager 里要捕获 40014 错误遇到后强制清理本地缓存并重新获取 token。我一般会加一个「重试一次」的逻辑发送失败且错误码是 40014 时刷新 token 后重新发送。4.2 接口报 60011 没有权限现象明明用对了 UserID但提示 60011。原因该用户不在应用的可见范围内或者 UserID 写错——把登录名、手机号、姓名当成了 UserID。企业号后台的 UserID 在「通讯录-成员详情」里看。解决先在后台确认目标用户所属部门已添加到应用的可见范围再复制后台的 UserID 粘贴进代码不要手敲。如果确认无误仍报错检查代码里是否误用了touser之外的空格或竖线分隔错误。4.3 消息发出去了但部分人收不到现象同一部门里 A 能收到B 收不到或者发送时报成功但全员都没收到。原因最常见的是应用的可见范围只覆盖了部分部门而touser用了all或是批量用户组。其次是消息被微信折叠进「服务通知」里员工没注意看。解决发送前在后台核对可见范围发送后让收不到的人检查微信的「企业号」会话是否存在必要时在后台把应用的「消息接收方式」改为「实时接收」。这类问题不是代码能兜底的要在交付说明里讲清楚。4.4 多线程环境下 token 被并发刷新现象并发推送场景下日志里频繁出现「刷新 token」的提示且偶发 40014。原因多个线程同时发现 token 即将过期各自发起刷新请求导致旧 token 立即失效。解决TokenManager 内部加锁或用SemaphoreSlim控制刷新区间保证同一时间只有一个线程在刷新。资源包里已有基础锁实现但如果你在高并发环境使用建议把锁粒度放大到整个 token 检查 刷新过程。5. 进阶消息模板化与发送结果回执的定制5.1 把固定文案抽成模板匹配业务场景实际开发中不要每次硬编码消息内容建议把消息文案抽成模板。我一般这样做在配置库里存模板内容里保留占位符{name}、{orderId}、{status}运行时替换。string template 客户{name}的订单{orderId}已{status}请及时关注。; string content template .Replace({name}, customerName) .Replace({orderId}, orderId) .Replace({status}, statusText);这样做的好处是产品改文案时不用改代码重新发布运营可以直接维护模板。资源包里没有现成的模板引擎但这个替代方案几行就能实现比引入大型模板库更轻量。5.2 记录发送回执做失败重试机制企业号接口只保证「提交成功」不等于「送达成功」。如果成员取消关注或长时间不活跃消息可能一直处于「未读」状态。订单一类的关键通知需要补一条短信或站内信兜底。我的习惯是发送后把 taskid 和发送时间记录到数据库每 10 分钟跑一次任务查回执状态超过 30 分钟仍「未读」的转短信通道补发。回调接口的配置是个容易被忽略的坑企业号支持接收消息回执的「回调 URL」但需要你提供一个公网可达的地址且要完成 URL 验证。如果你在内网开发这段时间会被卡住——但这部分和推送功能本身解耦可以先不做。5.3 批量发送的正确姿势分批而非一次性企业号接口对批量发送有数量上限单次 touser 上限 1000 人超过会报错。如果你要推全员建议按部门分批发送每批 200 人左右中间 sleep 200 毫秒避免触发频率限制。常见做法是用一个简单的 for 循环分批foreach (var batch in userList.Chunk(200)) { string touser string.Join(|, batch); sender.SendText(touser, content); Thread.Sleep(200); }注意Chunk是 .NET 6 后才有的 API项目若是 .NET Framework 需要自己写分组逻辑。这个分批策略不仅能绕过上限还能在某一批失败时准确定位是哪批出了问题。5.4 从「发出去」到「有人处理」用回调数据倒逼闭环推送只是第一步真正要做的是「发了 → 看了 → 处理了」的闭环。资源包止步于发送成功但你在真实系统里还要关心回调接口——它会告诉你成员是否点击了卡片。把这些数据存起来才能做后续的「未读二次提醒」「超时升级到短信」策略。我的习惯是设计一张push_records表包含msg_id、userid、status、send_time、read_time五个字段。发送接口返回的msgid与回调里的MsgId对应上才能做状态流转。这套思路放进去后「推送功能」就从工具变成了业务闭环的一部分。我记得第一次做企业号推送时卡在 60011 上整整半天——最后发现是后台的可见范围没勾选新入职部门。代码没问题配置没到位那种无力感是导致我现在每次拿到这类资源都会先写「配置检查清单」的原因第一步核对 CorpID、Secret、AgentId第二步核对用户 UserID 与可见范围第三步用 curl 验证接口通不通第四步才跑代码。从那以后我每接手一个推送项目都强制走一遍这个流程没再翻过车。希望这篇拆解能帮你把这条链路走顺拿到资源后直接落地到你的系统里。本文还有配套的精品资源点击获取