星点匠心建站 星点匠心建站XD JIANXIN STUDIO
400-883-9527 免费定制方案
ARTICLE DETAIL

资讯详情

深耕新锐建站与运营推广的一线实战洞察。

企业微信API消息推送开发指南

企业微信API消息推送开发指南 1. 企业微信消息推送需求解析企业微信作为企业内部沟通协作的主流平台其API开放能力为系统集成提供了丰富可能。主动消息推送是企业微信API最常用的场景之一典型应用包括审批结果实时通知系统告警自动推送日报周报定时发送业务流程状态更新传统邮件或短信通知存在到达率低、交互性差的问题。通过QiWe API企业微信官方接口实现消息推送具有以下优势消息100%直达微信客户端支持富文本、卡片、图文等消息格式可追溯消息阅读状态无需额外用户授权2. 开发环境准备2.1 基础账号配置在开始调用API前需要完成以下准备工作企业微信管理后台配置登录企业微信管理后台work.weixin.qq.com进入「应用管理」→「自建应用」创建新应用记录关键参数CorpID企业唯一标识AgentID应用IDSecret应用凭证密钥IP白名单设置在应用详情页找到「接收消息」设置添加服务器出口IP到白名单多个IP需用英文逗号分隔重要提示Secret是敏感信息应当通过环境变量或配置中心管理切勿硬编码在代码中。2.2 开发工具选型根据技术栈不同推荐以下开发方案技术栈推荐工具特点Pythonrequests库简单易用适合快速验证JavaOkHttp3异步支持好企业级应用首选Node.jsaxiosPromise特性适合消息队列场景PHPGuzzle兼容性强适合传统系统集成以Python为例基础依赖安装pip install requests cryptography3. API调用核心实现3.1 获取AccessTokenAccessToken是调用所有API的通行证获取流程如下构造请求URLhttps://qyapi.weixin.qq.com/cgi-bin/gettoken?corpidIDcorpsecretSECRET处理响应示例import requests def get_token(corp_id, corp_secret): url fhttps://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid{corp_id}corpsecret{corp_secret} response requests.get(url) return response.json().get(access_token)关键注意事项Token有效期为2小时需要缓存复用每日获取次数限制2000次建议使用Redis等缓存中间件存储Token3.2 消息体结构设计企业微信支持多种消息类型以下是文本消息的完整JSON结构{ touser: UserID1|UserID2, toparty: PartyID1|PartyID2, totag: TagID1|TagID2, msgtype: text, agentid: 1000002, text: { content: 您的订单已处理完成请及时查看。 }, safe: 0, enable_id_trans: 0 }参数说明表字段必填说明touser否成员ID列表最多1000个toparty否部门ID列表最多100个msgtype是消息类型text/image/voice等agentid是应用IDcontent是消息内容最长2048字节safe否是否加密传输0-否 1-是3.3 消息发送实现完整Python示例代码def send_wechat_message(user_list, content): token get_token(CORP_ID, SECRET) url fhttps://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token} payload { touser: |.join(user_list), msgtype: text, agentid: AGENT_ID, text: {content: content}, safe: 0 } headers {Content-Type: application/json} response requests.post(url, jsonpayload, headersheaders) if response.json().get(errcode) ! 0: raise Exception(f发送失败: {response.text}) return True4. 高级功能实现4.1 模板卡片消息对于复杂业务场景推荐使用模板卡片消息{ touser: UserID, msgtype: template_card, template_card: { card_type: text_notice, source: { icon_url: https://example.com/logo.png, desc: 系统通知 }, main_title: { title: 工单处理提醒, desc: 您有一个待处理的工单 }, task_id: task_123, buttons: [ { text: 查看详情, key: btn_1 } ] } }4.2 消息加密传输对于敏感信息需启用加密传输获取企业微信官方提供的EncodingAESKey使用WXBizMsgCrypt工具类进行加密在请求中设置safe1Java加密示例WXBizMsgCrypt crypt new WXBizMsgCrypt(token, encodingAESKey, corpId); String encryptedMsg crypt.encrypt(plainText);5. 生产环境注意事项5.1 性能优化建议批量发送策略单次API调用最多支持1000个接收人超过限额需分批发送建议每批间隔200-500ms错误处理机制def safe_send(user, content, retry3): for i in range(retry): try: return send_wechat_message(user, content) except Exception as e: if i retry - 1: log_error(f最终发送失败: {str(e)}) time.sleep(2 ** i) return False5.2 监控指标建设建议监控以下关键指标指标名称监控方式告警阈值API成功率日志分析99.5%Token获取次数接口计数1500次/天消息延迟时间戳比对5秒用户未读数回调统计持续增长6. 常见问题排查6.1 错误代码速查表错误码含义解决方案40001无效Token检查Secret是否正确重新获取Token40014无效消息体验证JSON格式检查字段类型41028消息内容超长拆分内容或改用图文消息60011超过频率限制降低发送频率增加间隔时间6.2 消息未到达排查步骤检查接收人是否在当前应用可见范围验证用户微信是否绑定企业微信查看管理后台「应用通知」开关状态检查用户是否设置了消息免打扰我在实际项目中发现iOS客户端有时会出现消息延迟的情况。通过以下方法可显著改善在消息体添加task_id字段避免连续发送相同内容重要消息配合邮件二次通知
返回列表