企微手机版
企微协议版微信协议版
企微协议版微信协议版
  1. 消息
  • 文档首页
  • 更新日志
  • 手机版后台保活设置指南
  • Q&A 常见疑问
  • 回调
    • 回调格式
    • 设置回调URL
    • 查询回调URL
    • 删除回调URL
  • 用户
    • 获取用户信息
    • 获取联系人二维码
    • 修改姓名
    • 修改别名
    • 修改头像
    • 修改性别
  • 消息
    • 发送文本消息
      POST
    • 发送消息(协议)
      POST
    • 撤回消息
      POST
    • 发送大视频
      POST
    • 发送视频号
      POST
    • 发送文件
      POST
    • 发送合并转发
      POST
    • 发送表情/GIF
      POST
    • 发送图片
      POST
    • 发送链接
      POST
    • 发送名片
      POST
    • 发送@消息(群聊)
      POST
    • 发送视频
      POST
    • 发送语音
      POST
    • 发送小程序
      POST
    • 查询群发任务目标列表
      POST
    • 确认群发消息
      POST
    • 极速群发
      POST
    • 发送引用消息
      POST
    • 申请语音转文字
      POST
    • 查询语音转文字结果
      POST
    • 确认企微内部消息已读
      POST
    • 标记会话已读
      POST
    • 检查客户或群是否可以群发
      POST
    • 查询待确认群发任务
      POST
    • 同步群发任务发送状态
      POST
    • 获取群发任务详情
      POST
    • 发送H5视频号消息
      POST
    • 发送位置
      POST
  • 客户
    • 同意客户申请
    • 获取企业联系人列表
    • 批量获取客户信息
    • 删除好友
    • 获取客户申请列表
    • 获取客户列表
    • 同步申请联系人
    • 同步联系人
    • 更新联系人
    • 批量删除单向好友
    • 获取缓存联系人列表
    • 获取单向好友列表
    • 获取用户信息(带检查)
    • 查询是否双向好友
    • 获取好友MultiData
    • 搜索微信/企微用户
    • 添加搜索的微信用户
    • 添加名片为联系人
    • 通过二维码名片获取联系人
    • 通过二维码名片添加微信用户
    • 重新添加被删联系人
    • 主动分页同步消息
    • 添加搜索到的企微用户
    • 检查名片联系人
    • 操作联系人黑名单
    • 批量删除单向好友
    • 获取缓存联系人列表
    • 获取单向好友列表
    • 获取用户信息(带检查)
    • 查询是否双向好友
    • 搜索微信/企微用户
    • 添加搜索的微信用户
    • 添加名片为联系人
    • 通过二维码名片获取联系人
    • 通过二维码名片添加微信用户
    • 重新添加被删联系人
    • 添加搜索到的企微用户
    • 检查名片联系人
    • 操作联系人黑名单
  • 会话
    • 获取会话群列表
    • 获取群置顶消息
    • 获取会话列表
    • 设置会话折叠
    • 设置会话免打扰
    • 设置会话置顶
    • 消息置顶/取消置顶
    • 会话操作(旧路径兼容)
    • 独立获取会话配置
    • 同步聊天标签列表
    • 创建聊天标签
    • 修改聊天标签
    • 删除聊天标签
    • 同步会话所属标签
    • 修改会话所属标签
    • 设置群置顶消息(协议)
    • 取消群置顶消息(协议)
  • 群组
    • 接受群邀请
    • 通过群添加联系人
    • 获取群成员列表
    • 批量获取群详情
    • 转让群主
    • 创建客户群
    • 解散群
    • 获取群聊黑名单
    • 获取群二维码
    • 添加群成员
    • 设置群昵称
    • 设置群邀请确认
    • 禁止改群名
    • 修改群名
    • 设置群公告
    • 修改群备注
    • 操作群黑名单
    • 退群
    • 移除群成员
    • 设置群管理员
    • 保存群到通讯录
    • 禁止互加联系人
    • 同步群信息
    • 获取客户群列表(协议)
    • 邀请/添加群成员(协议)
    • 获取入群欢迎语列表
    • 创建文本入群欢迎语
    • 应用已有入群欢迎语
    • 获取群防骚扰规则
    • 设置群关联的防骚扰规则
    • 操作客户群白名单
    • 审批群邀请申请
    • 设置群自动回复
    • 获取群模板
    • 将群模板应用到指定群
    • 创建客户群(空群别名)
    • 获取群置顶消息(别名)
    • 置顶群消息(别名)
    • 取消置顶群消息(别名)
    • 取消群管理员(别名)
  • 朋友圈
    • 设置朋友圈签名
    • 发布朋友圈
    • 获取发布的朋友圈记录
    • 获取指定朋友圈详情
    • 删除朋友圈
    • 评论朋友圈
    • 删除朋友圈评论
    • 点赞/取消点赞
    • 确认发送朋友圈任务
    • 获取朋友圈任务记录
    • 获取朋友圈任务发送状态
    • 设置朋友圈封面
  • 客户标签
    • 批量打标签
    • 创建标签
    • 删除标签
    • 获取企业标签
    • 获取个人标签
    • 修改标签
    • 操作用户标签
    • 获取企业和个人标签
    • 批量追加客户标签
  • 开放平台
    • ChatId转RoomId
    • 获取应用信息
    • 获取附件素材
    • 获取Banner列表
    • 获取个人Banner信息
    • OpenID转VID
    • RoomId转ChatId
    • VID转ExternalUserID
    • 检查OAuth URL
    • VID转OpenID
    • 获取URL动作码
  • CDN
    • 配置存储(OSS/COS/MinIO)
    • FTN下载文件
    • CDN下载文件
    • CDN上传文件
    • 上传图片
    • FTN上传文件
    • 微信文件下载
    • CDN上传文件(别名)
    • CDN下载文件(别名)
  • 组织架构
    • 获取架构节点数据
    • 修改同事信息
    • 同步公司架构
    • 同步同事信息
  • 企业
    • 获取企业简要信息
  • 同步
  • 数据模型
    • BaseRequest
    • GuidParam
    • ErrorResponse
    • CommonResponse
  1. 消息

极速群发

POST
/msg/send_group_msg
Fila cmd 103。直接向好友/群批量群发消息(区别于任务制群发,即时发送)。消息列表按顺序发送。

请求体#

{
    "app_key": "applAnm75tj7hx7Q0iq",
    "app_secret": "替换为你的 app_secret",
    "path": "/msg/send_group_msg",
    "data": {
        "guid": "af5cd5cc37ddb475",
        "group_list": [10728651244869916, 10976447000310532],
        "message_list": [
            { "text": { "content": "你好" } }
        ]
    }
}

字段说明#

外层#

字段类型必填说明
app_keystring是应用 key
app_secretstring是应用密钥
pathstring是固定 /msg/send_group_msg
dataobject是业务参数,见下表

data#

字段类型必填说明
guidstring是设备 guid
user_listuint64[]否好友群发目标 VID 列表
group_listuint64[]否群群发目标 ID 列表
message_listobject[]是消息列表,按顺序发送
user_list 和 group_list 至少传一个,可同时传。

message_list[](重点)#

没有 type 字段! 消息类型由字段名区分(oneof 结构),每个元素只包含一个类型字段,值为该类型的参数对象:
类型字段值对象说明
textTextMessage文本
image_urlGroupImageUrlMessage图片 URL
videoVideoMessage视频(CDN)
fileFileMessage文件(CDN)
weappWeAppMessage小程序
linkLinkMessage链接卡片
feed_videoFeedVideoMessage视频号
h5_feed_videoH5WechatSphFeedMessage视频号 H5
❌ 错误写法(会报 proto: syntax error):
{ "type": "text", "text": "你好" }
✅ 正确写法:
{ "text": { "content": "你好" } }

各消息类型示例#

文本#

{ "text": { "content": "群发文本,可包含 {$@} 标记" } }
字段类型说明
contentstring文本内容,可含 {$@} 标记
at_liststring[]可选,@ 用户列表,"0" 表示 @所有人

图片 URL#

{ "image_url": { "image_url": "https://example.com/a.jpg", "size": 10240, "thumb_width": 200, "thumb_height": 200 } }

视频 / 文件(CDN)#

file_id / aes_key / md5 等来自 /cdn/c2c_upload 上传接口的响应,先上传再群发:
{ "video": { "file_id": "xxx", "size": 123456, "file_name": "a.mp4", "aes_key": "xxx", "md5": "xxx", "duration": 15, "width": 720, "height": 1280 } }
{ "file": { "file_id": "xxx", "size": 123456, "file_name": "a.pdf", "aes_key": "xxx", "md5": "xxx" } }

小程序#

{ "weapp": { "username": "gh_xxx", "appid": "wx_xxx", "appname": "小程序名", "appicon": "https://...", "title": "卡片标题", "page_path": "pages/index/index", "file_id": "xxx", "size": 1024, "aes_key": "xxx", "md5": "xxx" } }

链接卡片#

{ "link": { "title": "标题", "desc": "描述", "url": "https://example.com", "image_url": "https://example.com/cover.jpg" } }

响应#

{
    "error_code": 0,
    "error_message": "",
    "data": {
        "result": {
            "msgid": 123456789
        }
    }
}
error_code = 0 表示成功,data.result.msgid 为本次群发任务 ID。

常见错误#

错误信息原因
proto: syntax error ... unexpected tokenmessage_list 格式错(如 text 传了字符串、带了 type 字段)
Unknown command type设备 App 版本过旧,不认识该命令,需升级 App
Failed to serialize request设备端必填参数为空(如 message_list 为空)
fila: unsupported pathpath 写错,服务端无此路径

注意事项#

1.
group_list / user_list 的 ID 是 64 位整数(超过 JS 安全整数范围 2^53-1)。用 JavaScript 代码构造请求时必须以字符串形式传(protojson 接受 "10728651244869916" 字符串),否则精度丢失导致目标错误。直接在 Apifox 粘贴 JSON 原文则不受影响。
2.
一次群发的多条消息按 message_list 顺序发送。
3.
群发对象需在设备通讯录内,群发结果可通过回调获取。

请求参数

Body 参数application/json必填

示例
{
    "guid": "string",
    "user_list": [
        "string"
    ],
    "group_list": [
        "string"
    ],
    "message_list": [
        {
            "text": {
                "content": "string",
                "at_list": [
                    "string"
                ]
            },
            "image_url": {
                "image_url": "string",
                "size": 0,
                "thumb_width": 0,
                "thumb_height": 0
            },
            "video": {
                "file_id": "string",
                "size": 0,
                "file_name": "string",
                "aes_key": "string",
                "md5": "string",
                "duration": 0,
                "width": 0,
                "height": 0,
                "auth_key": "string"
            },
            "file": {
                "file_id": "string",
                "size": 0,
                "file_name": "string",
                "aes_key": "string",
                "md5": "string",
                "auth_key": "string"
            },
            "weapp": {
                "username": "string",
                "appid": "string",
                "appname": "string",
                "appicon": "string",
                "title": "string",
                "page_path": "string",
                "file_id": "string",
                "size": 0,
                "aes_key": "string",
                "md5": "string",
                "auth_key": "string"
            },
            "link": {
                "title": "string",
                "desc": "string",
                "url": "string",
                "image_url": "string"
            },
            "feed_video": {
                "feed_type": 0,
                "cover_url": "string",
                "thumb_url": "string",
                "avatar": "string",
                "nickname": "string",
                "desc": "string",
                "url": "string",
                "extras": "string",
                "object_id": "string",
                "object_nonce_id": "string"
            },
            "h5_feed_video": {
                "feed_type": 0,
                "cover_url": "string",
                "thumb_url": "string",
                "avatar": "string",
                "nickname": "string"
            }
        }
    ]
}

请求示例代码

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location '/msg/send_group_msg' \
--header 'Content-Type: application/json' \
--data '{
    "guid": "string",
    "user_list": [
        "string"
    ],
    "group_list": [
        "string"
    ],
    "message_list": [
        {
            "text": {
                "content": "string",
                "at_list": [
                    "string"
                ]
            },
            "image_url": {
                "image_url": "string",
                "size": 0,
                "thumb_width": 0,
                "thumb_height": 0
            },
            "video": {
                "file_id": "string",
                "size": 0,
                "file_name": "string",
                "aes_key": "string",
                "md5": "string",
                "duration": 0,
                "width": 0,
                "height": 0,
                "auth_key": "string"
            },
            "file": {
                "file_id": "string",
                "size": 0,
                "file_name": "string",
                "aes_key": "string",
                "md5": "string",
                "auth_key": "string"
            },
            "weapp": {
                "username": "string",
                "appid": "string",
                "appname": "string",
                "appicon": "string",
                "title": "string",
                "page_path": "string",
                "file_id": "string",
                "size": 0,
                "aes_key": "string",
                "md5": "string",
                "auth_key": "string"
            },
            "link": {
                "title": "string",
                "desc": "string",
                "url": "string",
                "image_url": "string"
            },
            "feed_video": {
                "feed_type": 0,
                "cover_url": "string",
                "thumb_url": "string",
                "avatar": "string",
                "nickname": "string",
                "desc": "string",
                "url": "string",
                "extras": "string",
                "object_id": "string",
                "object_nonce_id": "string"
            },
            "h5_feed_video": {
                "feed_type": 0,
                "cover_url": "string",
                "thumb_url": "string",
                "avatar": "string",
                "nickname": "string"
            }
        }
    ]
}'

返回响应

🟢200
application/json
OK
Bodyapplication/json

示例
{
    "error_code": 0,
    "error_message": "string",
    "data": {
        "result": {}
    }
}
修改于 2026-09-07 11:05:15
上一页
确认群发消息
下一页
发送引用消息
Built with