返回上一级 最佳实践

企业微信 API 接口开发：外部联系人 · 群聊消息群发

SendGroupsMsg CDN 素材 · 收件人拉取 文档：wechatapi.apifox.cn
外部联系人与群聊群发最佳实践封面

整体架构

  1. 实例管理层：初始化、代理、登录登出、多实例查询，生成全局 uuid
  2. 素材上传层：CDN / 大文件上传，产出 cdnkey、aeskey、md5
  3. 收件人拉取层：外部联系人、内部成员、客户群 / 内部群 ID，组装 vids
  4. 消息发送层：单发接口 + 群发 SendGroupsMsg（底层复用单发能力）
  5. 消息回调层：HTTP / RabbitMQ，接收回执与客户回复
  6. 辅助工具层：群管理、标签、文件下载、ID 互转

群发核心逻辑

  • SendGroupsMsg 无「每人每日一条」类单人限制，可按需批量推送
  • 本质是批量单发：一次传入多个联系人 / 群 ID，推送同一组消息
  • vids 只能全为联系人 vid，或全为群 roomid，禁止混合
  • 支持文本、图文、文件、视频、链接、小程序、视频号等类型组合

统一返回规范

  • errcode=0：成功，业务数据在 data
  • errcode≠0：失败，看 errmsg
  • 高频错误：缺少 uuid → errcode:500, errmsg:"uuid参数不存在"

账号与回调基础

  • 初始化 /wxwork/init（deverType=ipad）
  • 回调 /wxwork/SetCallbackUrl（HTTP 或 RabbitMQ）；服务端须同步返回 {"errcode":0,"errmsg":"ok"}
  • 登录：getQrCode / CheckCode / automaticLogin / LoginOut
  • 离线补齐：登录后 /wxwork/SyncAllData，is_select=1 时继续分页

素材上传（群发前置）

  • 图片 ≤25MB：本地 CdnUploadImg；网络图 CdnUploadImgLink
  • 文件 / silk 语音：CdnUploadFile / UploadCdnLink
  • 视频：≤25MB 走 CDN 视频接口；更大走大文件链路
  • 下载区分：内部好友/内部群可用 CDN；个微外部发来的图文件须用外部下载接口，否则易 403

收件人拉取

  • 外部联系人：/wxwork/GetExternalContacts（可过滤拉黑、已删）
  • 客户群：GetChatroomMembers / GetSessionRoomList
  • 群成员：GetRoomUserList（按 roomid 取成员 vid）

群发核心接口 SendGroupsMsg

接口见正式文档 /wxwork/SendGroupsMsg。主要参数：

  • uuid：实例标识（必填）
  • vids：接收人数组
  • isroom：true=群发群；false=群发联系人
  • msg_list：消息内容数组（多类型混合）

常见 msg_list 类型示例：纯文本 type=0、CDN 图片 type=14、CDN 文件 type=15、链接 type=13、小程序 type=78、超大视频 type=22 等。返回 msg_id 可用于回调匹配发送回执。

配套单发与回调作用

  • 单聊/单条仍可用 SendTextMsg、SendCDNImgMsg、RevokeMsg、MarkAsRead、sendQuoteMsg、SpeechToTextEntity 等
  • 回调用途：群发回执、客户实时回复、群变更与好友新增等事件

完整请求/响应字段请打开 wechatapi.apifox.cn。需要报备测试请 联系客服。