# 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、接口目录

接口名称英文名请求路径
上传图文消息内的图片获取 URLmassmsgget/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)群发接口新增原创校验流程

开发者调用群发接口进行图文消息的群发时,微信会将开发者准备群发的文章,与公众平台原创库中的文章进行比较,校验结果分为以下几种:

  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 长度超过限制

接口示例及参数描述

{
    "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

#