EasyWeChat 企业微信消息开发指南：主动发送、被动接收与任务卡片状态更新

后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载本文基于 EasyWeChat 5.x 文档中《企业微信消息》篇展开系统讲解在 PHP 项目中通过 EasyWeChat 向企业微信成员主动发送消息文本消息与任务卡片消息、被动接收消息以及更新任务卡片消息状态的完整用法。读完本文你将掌握$app-messenger消息通道的链式调用范式、任务卡片消息的构造与状态回写并能结合仓库源码理解底层 API 调用的鉴权与重试机制。一、企业微信消息的两种模式与公众号一致EasyWeChat 的企业微信模块把消息处理划分为两类主动发送消息由你的应用服务器主动调用企业微信 API向指定成员userid推送文本、任务卡片等消息典型场景如审批结果通知、订单状态提醒。对应本篇文档的核心对象是$app-messengerMessenger 实例。被动接收消息成员在客户端触发事件或发消息时企业微信服务器回调你的服务端 URL由你的程序解析、处理并可选回复。对应模块是$app-server详见 服务端文档。两者的分界很清晰主动发送走「应用服务器 → 企业微信 API → 成员」被动接收走「成员 → 企业微信服务器 → 你的回调地址」。本文先聚焦主动发送再说明被动接收的接入要点。注意区分$app-messenger用于向企业微信应用成员发消息而向群聊机器人发消息用的是$app-group_robot_messenger群机器人通道详见 群机器人文档两者目标不同、API 端点也不同不要混用。二、初始化应用发送消息的前提发送消息前需要先按企业微信企业内部开发的要求初始化Application。参考 企业微信应用配置文档一个典型的配置如下$config [ corp_id xxxxxxxxxxxxxxxxx, agent_id 100020, // 如果有 agent_id 则填写 secret xxxxxxxxxx, // 指定 API 调用返回结果的类型array(default)/collection/object/raw/自定义类名 response_type array, log [ level debug, file __DIR__./wechat.log, ], ]; $app Factory::work($config);其中corp_id为企业 IDagent_id为应用 IDsecret为应用密钥三者共同决定了消息 API 的调用身份。在 EasyWeChat 5.x 中Factory::work()负责装配整个企业微信应用从当前仓库源码结构看src/Work/Application.php是这一模块的工厂实现它通过createClient()构建带 access_token 注入能力的 HTTP 客户端AccessTokenAwareClient并将base_uri默认指向https://qyapi.weixin.qq.com/见getHttpClientDefaultOptions()源码第 183-189 行同时以响应体中的errcode作为失败判定、按配置决定是否抛出异常源码第 130-138 行。也就是说你调用消息 API 时access_token 的获取、附加与过期处理都由底层客户端自动完成无需手工拼接。三、主动发送消息1. 获取 Messenger 实例主动发送消息统一通过 Messenger 完成获取方式即文档所述// 获取 Messenger 实例 $messenger $app-messenger;Messenger 采用「先message()准备消息、再toUser()指定接收人、最后send()发送」的链式 API也可以调整链上顺序。下面分别演示两种常用消息类型。2. 发送任务卡片消息TextCard任务卡片消息适合需要成员点击查看详情或反馈处理状态的场景如请假审批、工单流转。构造消息时使用EasyWeChat\Kernel\Messages\TextCarduse EasyWeChat\Kernel\Messages\TextCard; // 获取 Messenger 实例 $messenger $app-messenger; // 准备消息 $message new TextCard([ title 你的请假单审批通过, description 单号1928373, ...., url http://easywechat.com/oa/.... ]); // 发送 $messenger-message($message)-toUser(overtrue)-send();TextCard的核心字段说明字段必填含义title是卡片标题会醒目地展示给成员description是卡片描述正文可写单号、审批意见等详情url是成员点击卡片后跳转的链接如 OA 详情页toUser(overtrue)中的参数是成员的userid非昵称、非手机号需要从企业微信通讯录或 OAuth 授权结果中获取。3. 发送普通文本消息文本消息无需构造消息对象直接传入字符串即可EasyWeChat 提供了两种等价写法$messenger-message(你的请假单单号1928373已经审批通过)-toUser(overtrue)-send(); // 或者写成 $messenger-toUser(overtrue)-send(你的请假单单号1928373已经审批通过);可以看到两种写法语义完全一致message()负责装载内容toUser()负责指定接收人send()负责真正触发发送。这种链式设计让你可以在业务代码中以更自然的方式组合「发给谁 发什么」。四、更新任务卡片消息状态任务卡片消息发送后如果成员在卡片上进行了操作如点击「同意」「拒绝」业务系统往往需要同步更新卡片状态。此时使用 Messenger 的updateTaskcard方法$messenger-updateTaskcard(array $userids, int $agentId, string $taskId, string $replaceName 已收到)参数说明参数类型必填含义$useridsarray是需要更新状态的成员 userid 数组$agentIdint是应用 IDagent_id指明卡片所属应用$taskIdstring是任务 ID标识要更新的那张任务卡片$replaceNamestring否替换后的按钮文案默认已收到该方法用于把任务卡片上的按钮文案如「待处理」更新为处理后的状态如「已收到」实现任务卡片的状态流转。taskId是发送任务卡片消息时随消息带出的标识业务侧需要在发送与回调两侧保持一致才能准确回写状态。五、被动接收消息被动接收消息接收企业微信服务器推送的事件与消息不属于 Messenger 的职责而是由服务端模块统一处理。整体接入分为两步在配置中补齐服务端校验所需参数。参考 服务端文档$config [ corp_id xxxxxxxxxxxxxxxxx, agent_id 100022, secret xxxxxxxxxx, // server config token xxxxxxxxx, aes_key xxxxxxxxxxxxxxxxxx, //... ]; $app Factory::work($config);注册消息处理器并返回响应$app-server-push(function($message){ // $message[FromUserName] // 消息来源 // $message[MsgType] // 消息类型event .... return Hello easywechat.; }); $response $app-server-serve(); $response-send();$response为Symfony\Component\HttpFoundation\Response实例在 Laravel、ThinkPHP 等框架中可按框架约定直接返回或发送。接收到的$message数组包含FromUserName消息来源 userid、MsgType消息类型如text、event等字段当企业微信启用消息加密时加解密由服务端模块基于token与aes_key自动完成。六、消息发送的底层链路小结结合本篇文档与 企业微信模块源码 可以梳理出主动发送消息的完整调用链$app-messenger取得 Messenger它最终依赖应用级的 HTTP 客户端Application::createClient()构建AccessTokenAwareClient源码第 130-138 行自动注入由getAccessToken()管理的 access_token客户端以响应 JSON 中的errcode判断接口失败并在配置允许时抛出异常发送请求默认指向https://qyapi.weixin.qq.com/源码第 186 行各消息接口的具体路径由对应 API 方法拼接。因此只要corp_id、agent_id、secret配置正确底层鉴权与请求细节无需额外关心而被动接收则需要额外配置token与aes_key用于回调校验与加解密。发送与接收两条链路配合即可覆盖企业微信应用消息处理的主流场景。延伸阅读企业微信应用配置corp_id/agent_id/secret/response_type/log等完整配置项说明企业微信服务端被动接收消息、回调校验与加解密的完整接入群机器人向群聊发送消息的独立通道$app-group_robot_messenger4.x 版本同样提供本篇消息能力见 4.x 消息文档API 保持一致升级时注意版本差异即可赞分享后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载相关推荐EasyWeChat 企业微信消息收发实战主动发送文本与卡片消息、被动接收与回复全指南EasyWeChat 企业微信消息收发实战主动发送文本与卡片消息、被动接收与回复全指南 企业微信WeWork是 EasyWeChat 四大核心应用之一其后端即时通讯EasyWeChat 企业微信群机器人开发指南Webhook 消息发送全解析EasyWeChat 企业微信群机器人开发指南Webhook 消息发送全解析 企业微信群机器人是 EasyWeChat 企业微信Work模块中一个轻量且实后端即时通讯企业微信开发终极指南使用EasyWeChat快速集成通讯录与消息推送企业微信开发终极指南使用EasyWeChat快速集成通讯录与消息推送 企业微信已成为企业数字化转型的核心工具但其开放接口的复杂性常让开发者望而却步。本文将通后端即时通讯上一篇ComfyUI-VideoHelperSuiteAI视频工作流的技术赋能与实践指南下一篇Electric Agents 反应式观察者模式用 ctx.observe() 监听实体变更并自动唤醒处理器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考