# 1、前言
在公众平台网站上,为公众号提供了每天1条的群发权限,为服务号提供每月(自然月)4条的群发权限。而对于某些具备开发能力的公众号运营者,可以通过高级群发接口,实现更灵活的群发能力。
请注意:
- 对于认证公众号,群发接口每天可成功调用1次,此次群发可选择发送给全部用户或某个标签。
- 对于认证服务号,开发者使用高级群发接口的每日调用次数是有限制的;并且用户每月只能接收4条,无论在公众平台网站上,还是使用接口群发,用户每月只能接收4条群发消息,多于4条的群发将对该用户发送失败。
- 开发者可以使用预览接口校对消息样式和排版,通过预览接口可发送编辑好的消息给指定用户校验效果。
- 群发过程中,微信后台会自动进行图文消息原创校验,请提前设置好相关参数(send_ignore 等)。
- 开发者可以主动设置 clientmsgid 来避免重复推送。
- 群发接口每分钟限制请求60次,超过限制的请求会被拒绝。
- 图文消息正文中支持插入自己账号和其他公众号已群发文章链接。
- 对于已开启 API 群发保护的账号,群发全部用户时需要等待管理员进行确认,如管理员拒绝或30分钟内没有确认,该次群发失败。用户可通过“设置-安全中心-风险操作保护”中关闭 API 群发保护功能。
群发图文消息的过程如下:
- 首先,预先将图文消息中需要用到的图片,使用上传图文消息内图片接口,上传成功并获得图片 URL。
- 上传图文消息素材,需要用到图片时,请使用上一步获取的图片 URL。
- 使用对用户标签的群发,或对 OpenID 列表的群发,将图文消息群发出去,群发时微信会进行原创校验,并返回群发操作结果。
- 在上述过程中,如果需要,还可以预览图文消息、查询群发状态,或删除已群发的消息等。
群发图片、文本等其他消息类型的过程如下:
- 如果是群发文本消息,则直接根据下面的接口说明进行群发即可。
- 如果是群发图片、视频等消息,则需要预先通过素材管理接口准备好 media_id。
关于群发时设置 is_to_all 为 true 使其进入公众号在微信客户端的历史消息列表的说明:
- 设置 is_to_all 为 true 且成功群发,会使得此次群发进入历史消息列表。
- 为防止异常,认证公众号在一天内,只能设置 is_to_all 为 true 且成功群发一次,或者在公众平台官网群发(不管本次群发是对全体还是对某个分组)一次。以避免一天内有2条群发进入历史消息列表。
- 类似地,服务号在一个月内,设置 is_to_all 为 true 且成功群发的次数,加上公众平台官网群发(不管本次群发是对全体还是对某个分组)的次数,最多只能是4次。
- 服务号设置 is_to_all 为 false 时是可以多次群发的,但每个用户一个月内只会收到最多4条,且这些群发不会进入历史消息列表。
其他注意事项:
- 请开发者注意,本接口中所有使用到 media_id 的地方,现在都可以使用素材管理中的永久素材 media_id 了。但注意,使用同一个素材群发出去的链接是一样的,这意味着,删除某一次群发,会导致整个链接失效。
- 对于群发和预览接口中的图文消息 (mpnews) ,请使用通过 “草稿箱 / 新建草稿” 接口获得的 media_id 。
# 2、接口目录
接口名称 | 英文名 | 请求路径 |
---|---|---|
上传图文消息内的图片获取 URL | massmsgget | /cgi-bin/media/uploadimg |
上传图文消息素材 | massmsgget | /cgi-bin/media/uploadnews |
根据标签群发消息 | sendAll | /cgi-bin/message/mass/sendall |
删除群发 | deleteMassMsg | /cgi-bin/message/mass/delete |
预览消息 | preview | /cgi-bin/message/mass/preview |
查询群发消息发送状态 | massmsgget | /cgi-bin/message/mass/get |
获取群发速度 | getSpeed | /cgi-bin/message/mass/speed/get |
设置群发速度 | setSpeed | /cgi-bin/message/mass/speed/set |
# 3、其他说明
# 3.1 图文消息群发前将进行原创校验
# 1)群发接口新增原创校验流程
开发者调用群发接口进行图文消息的群发时,微信会将开发者准备群发的文章,与公众平台原创库中的文章进行比较,校验结果分为以下几种:
当前准备群发的文章,未命中原创库中的文章,则可以群发。
当前准备群发的文章,已命中原创库中的文章,则:
- 2.1 若原创作者允许转载该文章,则可以进行群发。群发时,会自动替换成原文的样式,且会自动将文章注明为转载并显示来源。若希望修改原文内容或样式,或群发时不显示转载来源,可自行与原创公众号作者联系并获得授权之后再进行群发。
- 2.2 若原创作者禁止转载该文章,则不能进行群发。若希望转载该篇文章,可自行与原创公众号作者联系并获得授权之后再进行群发。
# 2)群发接口新增 send_ignore_reprint 参数
群发接口新增 send_ignore_reprint 参数(默认为0),开发者可以对群发接口的 send_ignore_reprint 参数进行设置,指定待群发的文章被判定为转载时,是否继续群发。
当 send_ignore_reprint 参数设置为1时,若文章被判定为转载,且原创文允许转载时,将继续进行群发操作。
当 send_ignore_reprint 参数设置为0时,若文章被判定为转载,将停止群发操作。
# 3.2 使用 clientmsgid 参数,避免重复推送
群发接口新增 clientmsgid 参数,开发者调用群发接口时可以主动设置 clientmsgid 参数,避免重复推送。
群发时,微信后台将对 24 小时内的群发记录进行检查,如果该 clientmsgid 已经存在一条群发记录,则会拒绝本次群发请求,返回已存在的群发 msgid,开发者可以调用“查询群发消息发送状态”接口查看该条群发的状态。
新增错误码
错误码 | 错误信息 |
---|---|
45065 | 相同 clientmsgid 已存在群发记录,返回数据中带有已存在的群发任务的 msgid |
45066 | 相同 clientmsgid 重试速度过快,请间隔1分钟重试 |
45067 | clientmsgid 长度超过限制 |
接口示例及参数描述
{
"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 冲突时的返回示例:
{
"errcode":45065,
"errmsg":"clientmsgid exist",
"msg_id":123456
}
# 4、事件推送群发结果
- 由于群发任务提交后,群发任务可能在一定时间后才完成,因此,群发接口调用时,仅会给出群发任务是否提交成功的提示,若群发任务提交成功,则在群发任务结束时,会向开发者在公众平台填写的开发者 URL(callback URL)推送事件。
- 需要注意,由于群发任务彻底完成需要较长时间,将会在群发任务即将完成的时候,就推送群发结果,此时的推送人数数据将会与实际情形存在一定误差
- 推送的 XML 结构如下(发送成功时):
<xml>
<ToUserName><![CDATA[gh_4d00ed8d6399]]></ToUserName>
<FromUserName><![CDATA[oV5CrjpxgaGXNHIQigzNlgLTnwic]]></FromUserName>
<CreateTime>1481013459</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[MASSSENDJOBFINISH]]></Event>
<MsgID>1000001625</MsgID>
<Status><![CDATA[err(30003)]]></Status>
<TotalCount>0</TotalCount>
<FilterCount>0</FilterCount>
<SentCount>0</SentCount>
<ErrorCount>0</ErrorCount>
<CopyrightCheckResult>
<Count>2</Count>
<ResultList>
<item>
<ArticleIdx>1</ArticleIdx>
<UserDeclareState>0</UserDeclareState>
<AuditState>2</AuditState>
<OriginalArticleUrl><![CDATA[Url_1]]></OriginalArticleUrl>
<OriginalArticleType>1</OriginalArticleType>
<CanReprint>1</CanReprint>
<NeedReplaceContent>1</NeedReplaceContent>
<NeedShowReprintSource>1</NeedShowReprintSource>
</item>
<item>
<ArticleIdx>2</ArticleIdx>
<UserDeclareState>0</UserDeclareState>
<AuditState>2</AuditState>
<OriginalArticleUrl><![CDATA[Url_2]]></OriginalArticleUrl>
<OriginalArticleType>1</OriginalArticleType>
<CanReprint>1</CanReprint>
<NeedReplaceContent>1</NeedReplaceContent>
<NeedShowReprintSource>1</NeedShowReprintSource>
</item>
</ResultList>
<CheckState>2</CheckState>
</CopyrightCheckResult>
<ArticleUrlResult>
<Count>1</Count>
<ResultList>
<item>
<ArticleIdx>1</ArticleIdx>
<ArticleUrl><![CDATA[Url]]></ArticleUrl>
</item>
</ResultList>
</ArticleUrlResult>
</xml>
参数说明
参数 | 说明 |
---|---|
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 |