原公众号文档（包含订阅号与服务号）已升级为公众号（原订阅号）与服务号文档。公众号文档请直接参考本目录内容，服务号文档请 [点击此处](/doc/service/guide/README.md) 前往。 ## 1、前言 在公众平台网站上，为公众号提供了每天1条的群发权限，为服务号提供每月（自然月）4条的群发权限。而对于某些具备开发能力的公众号运营者，可以通过高级群发接口，实现更灵活的群发能力。 **请注意：** 1. 对于认证公众号，群发接口每天可成功调用1次，此次群发可选择发送给全部用户或某个标签。 2. 对于认证服务号，开发者使用高级群发接口的每日调用次数是有限制的；并且用户每月只能接收4条，无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败。 3. 开发者可以使用预览接口校对消息样式和排版，通过预览接口可发送编辑好的消息给指定用户校验效果。 4. 群发过程中，微信后台会自动进行文章原创校验，请提前设置好相关参数(send_ignore 等)。 5. 开发者可以主动设置 clientmsgid 来避免重复推送。 6. 群发接口每分钟限制请求60次，超过限制的请求会被拒绝。 7. 文章正文中支持插入自己账号和其他公众号已群发文章链接。 8. 对于已开启 API 群发保护的账号，群发全部用户时需要等待管理员进行确认，如管理员拒绝或30分钟内没有确认，该次群发失败。用户可通过“设置-安全中心-风险操作保护”中关闭 API 群发保护功能。 **群发文章的过程如下：** 1. 首先，预先将文章中需要用到的图片，使用上传文章内图片接口，上传成功并获得图片 URL。 2. 上传文章素材，需要用到图片时，请使用上一步获取的图片 URL。 3. 使用对用户标签的群发，或对 OpenID 列表的群发，将文章群发出去，群发时微信会进行原创校验，并返回群发操作结果。 4. 在上述过程中，如果需要，还可以预览文章、查询群发状态，或删除已群发的消息等。 **群发贴图、文本等其他消息类型的过程如下：** 1. 如果是群发文本消息，则直接根据下面的接口说明进行群发即可。 2. 如果是群发贴图、视频等消息，则需要预先通过素材管理接口准备好 media_id。 **关于群发时设置 is_to_all 为 true 使其进入公众号在微信客户端的历史消息列表的说明：** 1. 设置 is_to_all 为 true 且成功群发，会使得此次群发进入历史消息列表。 2. 为防止异常，认证公众号在一天内，只能设置 is_to_all 为 true 且成功群发一次，或者在公众平台官网群发（不管本次群发是对全体还是对某个分组）一次。以避免一天内有2条群发进入历史消息列表。 3. 类似地，服务号在一个月内，设置 is_to_all 为 true 且成功群发的次数，加上公众平台官网群发（不管本次群发是对全体还是对某个分组）的次数，最多只能是4次。 4. 服务号设置 is_to_all 为 false 时是可以多次群发的，但每个用户一个月内只会收到最多4条，且这些群发不会进入历史消息列表。 **其他注意事项：** 1. 请开发者注意，本接口中所有使用到 media_id 的地方，现在都可以使用素材管理中的永久素材 media_id 了。但注意，使用同一个素材群发出去的链接是一样的，这意味着，删除某一次群发，会导致整个链接失效。 2. 对于群发和预览接口中的内容(mpnews) ，请使用通过 “草稿箱 / 新建草稿” 接口获得的 media_id 。 ## 2、接口目录 | 接口名称 | 请求路径 | 描述 | | --- | --- | --- | | [上传文章和贴图图片](/doc/subscription/api/material/permanent/api_uploadimage.md) | /cgi-bin/media/uploadimg | 本接口用于上传文章和贴图内所需的图片 | | [删除群发消息](/doc/subscription/api/notify/message/api_deletemassmsg.md) | /cgi-bin/message/mass/delete | 群发之后，随时可以通过该接口删除群发 | | [获取群发速度](/doc/subscription/api/notify/message/api_getspeed.md) | /cgi-bin/message/mass/speed/get | 本接口用于获取消息的群发速度 | | [查询群发消息发送状态](/doc/subscription/api/notify/message/api_massmsgget.md) | /cgi-bin/message/mass/get | 本接口用于查询群发消息发送状态 | | [预览消息](/doc/subscription/api/notify/message/api_preview.md) | /cgi-bin/message/mass/preview | 本接口发送消息给指定用户，在手机端查看消息的样式和排版 | | [根据标签群发消息](/doc/subscription/api/notify/message/api_sendall.md) | /cgi-bin/message/mass/sendall | 本接口用于根据标签群发消息 | | [设置群发速度](/doc/subscription/api/notify/message/api_setspeed.md) | /cgi-bin/message/mass/speed/set | 本接口用于设置消息的群发速度 | | [上传文章素材](/doc/subscription/api/notify/message/api_uploadnewsmsg.md) | /cgi-bin/media/uploadnews | 本接口用于上传文章，该能力已更新为草稿箱 | ## 3、其他说明 ### 3.1 文章群发前将进行原创校验 ### 1）群发接口新增原创校验流程 开发者调用群发接口进行文章的群发时，微信会将开发者准备群发的文章，与公众平台原创库中的文章进行比较，校验结果分为以下几种： 1. 当前准备群发的文章，未命中原创库中的文章，则可以群发。 2. 当前准备群发的文章，已命中原创库中的文章，则： - 2.1 若原创作者允许转载该文章，则可以进行群发。群发时，会自动替换成原文的样式，且会自动将文章注明为转载并显示来源。若希望修改原文内容或样式，或群发时不显示转载来源，可自行与原创公众号作者联系并获得授权之后再进行群发。 - 2.2 若原创作者禁止转载该文章，则不能进行群发。若希望转载该篇文章，可自行与原创公众号作者联系并获得授权之后再进行群发。 ### 2）群发接口新增 send_ignore_reprint 参数 群发接口新增 send_ignore_reprint 参数（默认为0），开发者可以对群发接口的 send_ignore_reprint 参数进行设置，指定待群发的文章被判定为转载时，是否继续群发。 1. 当 send_ignore_reprint 参数设置为1时，若文章被判定为转载，且原创文允许转载时，将继续进行群发操作。 2. 当 send_ignore_reprint 参数设置为0时，若文章被判定为转载，将停止群发操作。 ### 3.2 使用 clientmsgid 参数，避免重复推送 群发接口新增 clientmsgid 参数，开发者调用群发接口时可以主动设置 clientmsgid 参数，避免重复推送。 群发时，微信后台将对 24 小时内的群发记录进行检查，如果该 clientmsgid 已经存在一条群发记录，则会拒绝本次群发请求，返回已存在的群发 msgid，开发者可以调用“查询群发消息发送状态”接口查看该条群发的状态。 **新增错误码** | 错误码 | 错误信息 | | --- | --- | | 45065 | 相同 clientmsgid 已存在群发记录，返回数据中带有已存在的群发任务的 msgid | | 45066 | 相同 clientmsgid 重试速度过快，请间隔1分钟重试 | | 45067 | clientmsgid 长度超过限制 | **接口示例及参数描述** ```json { "filter":{ "is_to_all":false, "tag_id":2 }, "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews", "send_ignore_reprint":0, "clientmsgid":"send_tag_2" } ``` **参数说明** | 参数 | 是否必须 | 说明 | | --- | --- | --- | | clientmsgid | 否 | 开发者侧群发msgid，长度限制32字节，如不填，则后台默认以群发范围和群发内容的摘要值做为 clientmsgid | **返回说明** clientmsgid 冲突时的返回示例： ```json { "errcode":45065, "errmsg":"clientmsgid exist", "msg_id":123456 } ``` ## 4、事件推送群发结果 - 由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者 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 | ###