# 根据标签群发消息 [调试诊断](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_tools) > 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。 接口英文名：sendAll 本接口用于根据标签群发消息 ##### 图文消息群发前将进行原创校验 开发者调用群发接口进行图文消息的群发时，微信会将开发者准备群发的文章，与公众平台原创库中的文章进行比较，校验结果分为以下几种： - 当前准备群发的文章，未命中原创库中的文章，则可以群发。 - 当前准备群发的文章，已命中原创库中的文章，则： - 若原创作者允许转载该文章，则可以进行群发。群发时，会自动替换成原文的样式，且会自动将文章注明为转载并显示来源。若希望修改原文内容或样式，或群发时不显示转载来源，可自行与原创公众号作者联系并获得授权之后再进行群发。 - 若原创作者禁止转载该文章，则不能进行群发。若希望转载该篇文章，可自行与原创公众号作者联系并获得授权之后再进行群发。 群发接口新增 send_ignore_reprint 参数（默认为0），开发者可以对群发接口的 send_ignore_reprint 参数进行设置，指定待群发的文章被判定为转载时，是否继续群发。 - 当 send_ignore_reprint 参数设置为1时，若文章被判定为转载，且原创文允许转载时，将继续进行群发操作。 - 当 send_ignore_reprint 参数设置为0时，若文章被判定为转载，将停止群发操作。 #### API 群发安全保护 对于开启 API 群发保护的用户，群发全部用户后需要等待管理员进行确认，如管理员拒绝或30分钟内没有确认，该次群发失败。用户可通过”设置-安全中心-风险操作保护“中关闭 API 群发保护功能。 ## 1. 调用方式 ### HTTPS 调用 ```bash POST https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN ``` ### 云调用 - 调用方法：officialAccount.message.sendall - 出入参和 HTTPS 调用相同，调用方式可查看 [云调用](/doc/oplatform/developers/dev/cloudCall.md) 说明文档。 ### 第三方调用 - 本接口支持第三方平台代商家调用。 - 该接口所属的权限集 id 为：7 - 服务商获得其中之一权限集授权后，可通过使用 [authorizer_access_token](/doc/oplatform/developers/dev/AuthorizerAccessToken.md) 代商家进行调用，具体可查看 [第三方调用](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/call_interface.md) 说明文档。 ## 2. 请求参数 ### 查询参数 `Query String Parameters` ```json [ { "参数名": "access_token", "类型": "string", "必填": "是", "说明": "接口调用凭证，可使用 [access_token](/doc/subscription/api/base/api_getaccesstoken)、[authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken.md)" } ] ``` ### 请求体 `Request Payload` ```json [ { "参数名": "filter", "类型": "object", "必填": "是", "说明": "用于设定图文消息的接收者" }, { "参数名": "msgtype", "类型": "string", "必填": "是", "说明": "群发的消息类型，图文消息为mpnews，文本消息为text，语音为voice，音乐为music，图片为image，视频为mpvideo，卡券为wxcard" }, { "参数名": "mpnews", "类型": "object", "必填": "否", "说明": "图文消息" }, { "参数名": "text", "类型": "object", "必填": "否", "说明": "文本消息" }, { "参数名": "voice", "类型": "object", "必填": "否", "说明": "语音消息" }, { "参数名": "images", "类型": "object", "必填": "否", "说明": "图片消息" }, { "参数名": "mpvideo", "类型": "object", "必填": "否", "说明": "视频消息" }, { "参数名": "wxcard", "类型": "object", "必填": "否", "说明": "卡券消息" }, { "参数名": "clientmsgid", "类型": "string", "必填": "否", "说明": "开发者侧群发msgid，长度限制32字节，如不填，则后台默认以群发范围和群发内容的摘要值做为 clientmsgid" } ] ``` ### Body.filter `Object Payload` 用于设定图文消息的接收者 ```json [ { "参数名": "is_to_all", "类型": "string", "必填": "否", "说明": "用于设定是否向全部用户发送，值为true或false，选择true该消息群发给所有用户，选择false可根据tag_id发送给指定群组的用户" }, { "参数名": "tag_id", "类型": "string", "必填": "否", "说明": "群发到的标签的tag_id，参见用户管理中用户分组接口，若is_to_all值为true，可不填写tag_id" } ] ``` ### Body.mpnews `Object Payload` 图文消息 ```json [ { "参数名": "media_id", "类型": "string", "必填": "否", "说明": "用于群发的图文消息的media_id" } ] ``` ### Body.text `Object Payload` 文本消息 ```json [ { "参数名": "content", "类型": "string", "必填": "否", "说明": "文本内容" } ] ``` ### Body.voice `Object Payload` 语音消息 ```json [ { "参数名": "media_id", "类型": "string", "必填": "否", "说明": "用于群发的图文消息的media_id" } ] ``` ### Body.images `Object Payload` 图片消息 ```json [ { "参数名": "media_ids", "类型": "array", "必填": "否", "说明": "用于群发的图文消息的media_id列表" }, { "参数名": "recommend", "类型": "string", "必填": "否", "说明": "推荐语" }, { "参数名": "title", "类型": "string", "必填": "否", "说明": "标题" }, { "参数名": "need_open_comment", "类型": "number", "必填": "否", "说明": "开启评论（1-开启，0-关闭）" }, { "参数名": "only_fans_can_comment", "类型": "number", "必填": "否", "说明": "只有粉丝能评论（1-开启，0-关闭）" } ] ``` ### Body.mpvideo `Object Payload` 视频消息 ```json [ { "参数名": "media_id", "类型": "string", "必填": "否", "说明": "用于群发的图文消息的media_id" } ] ``` ### Body.wxcard `Object Payload` 卡券消息 ```json [ { "参数名": "card_id", "类型": "string", "必填": "否", "说明": "卡券 ID" } ] ``` ## 3. 返回参数 ### 返回体 `Response Payload` ```json [ { "参数名": "type", "类型": "string", "说明": "媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息" }, { "参数名": "errcode", "类型": "number", "说明": "错误码" }, { "参数名": "errmsg", "类型": "string", "说明": "错误信息" }, { "参数名": "msg_id", "类型": "number", "说明": "消息发送任务的ID" }, { "参数名": "msg_data_id", "类型": "number", "说明": "消息的数据ID，，该字段只有在群发图文消息时，才会出现。可以用于在图文分析数据接口中，获取到对应的图文消息的数据，是图文分析数据接口中的msgid字段中的前半部分，详见图文分析数据接口中的msgid字段的介绍。" } ] ``` ## 4. 注意事项 1. 图文消息的 media_id 需要通过[新增临时素材](/doc/subscription/api/material/temporary/api_uploadtempmedia)，或通过[新增草稿](/doc/subscription/api/draftbox/draftmanage/api_draft_add)接口来得到。 2. 如果 media_id 是通过 “草稿箱 / 新建草稿” 接口来得到的，那么在群发成功后 media_id 会失效，后台草稿也会被自动删除。 3. 海外微信公众号仅支持发送图文(mpnews)消息。 4. 在返回成功时，意味着群发任务提交成功，并不意味着此时群发已经结束，所以，仍有可能在后续的发送过程中出现异常情况导致用户未收到消息，如消息有时会进行审核、服务器不稳定等。此外，群发任务一般需要较长的时间才能全部发送完毕，请耐心等待。 #### 避免重复发送 开发者调用群发接口时可以主动设置 clientmsgid 参数，避免重复推送。 群发时，微信后台将对 24 小时内的群发记录进行检查，如果该 clientmsgid 已经存在一条群发记录，则会拒绝本次群发请求，返回已存在的群发 msgid，开发者可以调用“查询群发消息发送状态”接口查看该条群发的状态。 #### 事件推送群发结果 由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者 URL（callback URL）推送事件。 > 需要注意，由于群发任务彻底完成需要较长时间，将会在群发任务即将完成的时候，就推送群发结果，此时的推送人数数据将会与实际情形存在一定误差 推送的 XML 结构如下（发送成功时）： ```xml 1481013459 1000001625 0 0 0 0 2 1 0 2 1 1 1 1 2 0 2 1 1 1 1 2 1 1 ``` **参数说明** | 参数 | 说明 | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ToUserName | 公众号的微信号 | | FromUserName | 公众号群发助手的微信号，为 mphelper | | CreateTime | 创建时间的时间戳 | | MsgType | 消息类型，此处为 event | | Event | 事件信息，此处为 MASSSENDJOBFINISH | | MsgID | 群发的消息ID | | Status | 群发的结果，为 “send success” 或 “send fail” 或 “err(num)”。但 “send success” 时，也有可能因用户拒收公众号的消息、系统错误等原因造成少量用户接收失败。err(num) 是审核失败的具体原因，可能的情况如下：err(10001):涉嫌广告, err(20001):涉嫌政治, err(20004):涉嫌社会, err(20002):涉嫌色情, err(20006):涉嫌违法犯罪, err(20008):涉嫌欺诈, err(20013):涉嫌版权, err(22000):涉嫌互推(互相宣传), err(21000):涉嫌其他, err(93115):公开地图使用不规范,err(30001):原创校验出现系统错误且用户选择了被判为转载就不群发, err(30002): 原创校验被判定为不能群发, err(30003): 原创校验被判定为转载文且用户选择了被判为转载就不群发, err(40001)：管理员拒绝, err(40002)：管理员30分钟内无响应，超时 | | TotalCount | tag_id 下粉丝数；或者 touser 中的粉丝数 | | FilterCount | 过滤（过滤是指特定地区、性别的过滤、用户设置拒收的过滤，用户接收已超4条的过滤）后准备发送的粉丝数，一般 FilterCount 约等于 SentCount + ErrorCount | | SentCount | 发送成功的粉丝数 | | ErrorCount | 发送失败的粉丝数 | | ResultList | 各个单图文校验结果 | | ArticleIdx | 群发文章的序号，从1开始 | | UserDeclareState | 用户声明文章的状态。0表示用户未声明原创；1表示用户声明原创；2表示用户声明转载 | | AuditState | 系统校验的状态。0表示尚未未校验原创；1表示校验原创中；11表示校验原创通过；其他表示校验原创未通过 | | OriginalArticleUrl | 相似原创文的 url | | OriginalArticleType | 相似原创文的类型。1表示原创文；2表示历史非原创文；3表示新闻类；4表示黑文类 | | CanReprint | 是否能转载 | | NeedReplaceContent | 是否需要替换成原创文内容 | | NeedShowReprintSource | 是否需要注明转载来源 | | CheckState | 整体校验结果。1-未被判为转载，可以群发，2-被判为转载，可以群发，3-被判为转载，不能群发 | | ArticleUrl | 群发文章的 url | ## 5. 代码示例 ### 5.1 图文消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":2 }, "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews", "send_ignore_reprint":0 } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ### 5.2 文本消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":2 }, "text":{ "content":"CONTENT" }, "msgtype":"text" } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ### 5.3 语音消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":2 }, "voice":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"voice" } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ### 5.4 图片消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":2 }, "images": { "media_ids": [ "aaa", "bbb", "ccc" ], "recommend": "xxx", "title": "yyy", "need_open_comment": 1, "only_fans_can_comment": 0 }, "msgtype":"image" } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ### 5.5 视频消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":2 }, "mpvideo":{ "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc" }, "msgtype":"mpvideo" } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ### 5.6 卡券消息 请求示例 ``` json { "filter":{ "is_to_all":false, "tag_id":"2" }, "wxcard":{ "card_id":"123dsdajkasd231jhksad" }, "msgtype":"wxcard" } ``` 返回示例 ``` json { "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 } ``` ## 6. 错误码 以下是本接口的错误码列表，其他错误码可参考 [通用错误码](/doc/oplatform/developers/errCode/README.md)；调用接口遇到报错，可使用官方提供的 [API 诊断工具](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_errcode) 辅助定位和分析问题。 ```json [ { "错误码": "40001", "错误描述": "invalid credential  access_token isinvalid or not latest", "解决方案": "access_token 无效或不为最新获取的 access_token，请开发者确认access_token的有效性" }, { "错误码": "40007", "错误描述": "invalid media_id", "解决方案": "无效的媒体ID" }, { "错误码": "40008", "错误描述": "invalid message type", "解决方案": "不合法的消息类型" }, { "错误码": "40066", "错误描述": "invalid url", "解决方案": "url不存在" }, { "错误码": "40152", "错误描述": "invalid tag id", "解决方案": "tag_id 不存在" }, { "错误码": "40215", "错误描述": "invalid image count", "解决方案": "减少图片个数" }, { "错误码": "40227", "错误描述": "", "解决方案": "" }, { "错误码": "40228", "错误描述": "empty content", "解决方案": "消息内容为空，请检查参数" }, { "错误码": "40229", "错误描述": "empty cover", "解决方案": "封面为空，请检查参数" }, { "错误码": "41001", "错误描述": "access_token missing", "解决方案": "缺少 access_token 参数" }, { "错误码": "41040", "错误描述": "no", "解决方案": "不符合声明文字原创的要求" }, { "错误码": "42001", "错误描述": "access_token expired", "解决方案": "access_token 超时，请检查 access_token 的有效期，请参考基础支持 - 获取 access_token 中，对 access_token 的详细机制说明" }, { "错误码": "42010", "错误描述": "masssend too fast", "解决方案": "操作太快，请重试" }, { "错误码": "43002", "错误描述": "require POST method", "解决方案": "方法调用错误，请用 post 方法调用" }, { "错误码": "44004", "错误描述": "empty content", "解决方案": "消息内容为空，请检查参数" }, { "错误码": "44009", "错误描述": "", "解决方案": "" }, { "错误码": "45002", "错误描述": "content size out of limit", "解决方案": "消息内容超过限制" }, { "错误码": "45009", "错误描述": "reach max api daily quota limit", "解决方案": "超出接口每日调用限制" }, { "错误码": "45011", "错误描述": "api minute-quota reach limit  mustslower  retry next minute", "解决方案": "API 调用太频繁，请稍候再试" }, { "错误码": "45028", "错误描述": "has no masssend quota", "解决方案": "当前周期内的发表次数已用完" }, { "错误码": "45062", "错误描述": "has agreement ad. please use mp.weixin.qq.com", "解决方案": "已接广告，不支持api群发" }, { "错误码": "45065", "错误描述": "clientmsgid exist", "解决方案": "相同 clientmsgid 已存在群发记录，返回数据中带有已存在的群发任务的 msgid" }, { "错误码": "45066", "错误描述": "same clientmsgid retry too fast", "解决方案": "相同 clientmsgid 重试速度过快，请间隔1分钟重试" }, { "错误码": "45067", "错误描述": "clientmsgid size out of limit", "解决方案": "clientmsgid 长度超过限制" }, { "错误码": "45113", "错误描述": "This API has been unsupported. For more details, please view https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&announce_id=11720505508vg7fd&version=&lang=zh_CN", "解决方案": "已不支持商品消息与卡券发表" }, { "错误码": "45159", "错误描述": "invalid tag id", "解决方案": "非法的tag_id" }, { "错误码": "48001", "错误描述": "api unauthorized", "解决方案": "api 功能未授权，请确认公众号/服务号已获得该接口，可以在「公众平台官网 - 开发者中心页」中查看接口权限" }, { "错误码": "48004", "错误描述": "api forbidden for irregularities view detail on mp.weixin.qq.com", "解决方案": "api 接口被封禁，请登录 mp.weixin.qq.com 查看详情" }, { "错误码": "48021", "错误描述": "auto-save draft can not preview/send, please save manually", "解决方案": "该草稿最后一次是系统自动保存的，不允许群发。可以前往 mp 微信公众平台后台或者公众号助手 app 里手动保存下草稿后重试发表" }, { "错误码": "48022", "错误描述": "api masssend not support api upload video", "解决方案": "api 上传的视频不允许用 api 发表" }, { "错误码": "48023", "错误描述": "the account is banned", "解决方案": "当前账号被封禁" }, { "错误码": "50002", "错误描述": "user limited", "解决方案": "用户受限，可能是用户帐号被冻结或注销" }, { "错误码": "53504", "错误描述": "need pass quiz", "解决方案": "需要答题后才可以发表，请前往公众平台官网进行发表" }, { "错误码": "61004", "错误描述": "access clientip is not registered", "解决方案": "第三方平台出口IP未设置" }, { "错误码": "61007", "错误描述": "api is unauthorized to component", "解决方案": "尚未将对应的权限集授权给第三方平台" }, { "错误码": "89504", "错误描述": "群发仍在审批流程中", "解决方案": "请稍等或联系管理员确认" }, { "错误码": "89505", "错误描述": "群发进入管理员确认流程", "解决方案": "请稍等或联系管理员确认" }, { "错误码": "268488001", "错误描述": "system busy, please try later", "解决方案": "系统繁忙，请稍后再试" } ] ``` ## 7. 适用范围 本接口在不同账号类型下的可调用情况： ```json [ { "公众号": "仅认证", "服务号": "仅认证" } ] ``` - 仅认证：表示仅允许企业主体已认证账号调用，未认证或不支持认证的账号无法调用。 - 其他未明确声明的账号类型，如无特殊说明，均不可调用此接口。