微信公众号群发接口和原创校验

一、说明

在公众平台网站上，为订阅号提供了每天一条的群发权限，为服务号提供每月（自然月）4条的群发权限。而对于某些具备开发能力的公众号运营者，可以通过高级群发接口，实现更灵活的群发能力（这些接口只是说替代了公众平台网站的界面操作，不是说就突破条数限制了）。

1.1限制：

1、对于认证订阅号，群发接口每天可成功调用1次，此次群发可选择发送给全部用户或某个标签；
2、对于认证服务号虽然开发者使用高级群发接口的每日调用限制为100次，但是用户每月只能接收4条，无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败；
3、开发者可以使用预览接口校对消息样式和排版，通过预览接口可发送编辑好的消息给指定用户校验效果；
4、群发过程中，微信后台会自动进行图文消息原创校验，请提前设置好相关参数(send_ignore等)；
5、开发者可以主动设置 clientmsgid 来避免重复推送。
6、群发接口每分钟限制请求60次，超过限制的请求会被拒绝。
7、图文消息正文中插入自己帐号和其他公众号已群发文章链接的能力。

---

二、群发图文消息

群发图文消息的过程如下：
1、首先，预先将图文消息中需要用到的图片，使用上传图文消息内图片接口，上传成功并获得图片 URL；
2、上传图文消息素材，需要用到图片时，请使用上一步获取的图片 URL；
3、使用对用户标签的群发，或对 OpenID 列表的群发，将图文消息群发出去，群发时微信会进行原创校验，并返回群发操作结果；
4、在上述过程中，如果需要，还可以预览图文消息、查询群发状态，或删除已群发的消息等。

---

三、群发图片、文本

群发图片、文本等其他消息类型的过程如下：
1、如果是群发文本消息，则直接根据下面的接口说明进行群发即可；
2、如果是群发图片、视频等消息，则需要预先通过素材管理接口准备好 mediaID。

---

四、群发时使用is_to_all

关于群发时使用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条，且这些群发不会进入历史消息列表。

---

五、上传图文消息接口

下面介绍上传图文消息的接口（仅用于图文消息）

5.1 上传图文消息内的图片获取URL【订阅号与服务号认证后均可用】

请注意，本接口所上传的图片不占用公众号的素材库中图片数量的5000个的限制。图片仅支持jpg/png格式，大小必须在1MB以下

地址：
post-https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN

调用示例：
curl -F [email protected] "https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN"

示例中的media指form-data中媒体文件标识，有filename、filelength、content-type等信息

正常情况下，微信后台会返回此图片的URL

5.2 上传图文消息素材【订阅号与服务号认证后均可用】

地址：
post-https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN

post的数据包括文章的信息，如作者、标题、缩略图、content等，具体参数请看群发接口和原创校验的“上传图文消息素材”部分（群发的图文消息中可以添加小程序）

上传成功的话微信后台会返回形如下列数据的信息：

{
   "type":"news",
   "media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",
   "created_at":1391857799
}

---

六、原创校验

图文消息群发前将进行原创校验，相关设定如下：

6.1 群发接口新增原创校验流程

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

• 当前准备群发的文章，未命中原创库中的文章，则可以群发。
• 当前准备群发的文章，已命中原创库中的文章，则：
  
  • 若原创作者允许转载该文章，则可以进行群发。群发时，会自动替换成原文的样式，且会自动将文章注明为转载并显示来源（若希望修改原文内容或样式，或群发时不显示转载来源，可自行与原创公众号作者联系并获得授权之后再进行群发）。
  • 若原创作者禁止转载该文章，则不能进行群发（若希望转载该篇文章，可自行与原创公众号作者联系并获得授权之后再进行群发）。

6.2 群发接口的 send_ignore_reprint 参数

群发接口新增 send_ignore_reprint 参数，开发者可以对群发接口的 send_ignore_reprint 参数进行设置，指定待群发的文章被判定为转载时，是否继续群发。

• 当 send_ignore_reprint 参数设置为1时，文章被判定为转载时，且原创文允许转载时，将继续进行群发操作。
• 当 send_ignore_reprint 参数设置为0时（默认），文章被判定为转载时，将停止群发操作。

---

七、开始群发

下面介绍群发的相关接口（两种方式）

7.1 根据标签进行群发【订阅号与服务号认证后均可用】

地址为：
post-https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN
post的数据根据消息种类不同有所区别

1、图文消息（注意：图文消息的media_id需要通过“上传图文消息接口”中的方法来得到）

{
   "filter":{
      "is_to_all":false,
      "tag_id":2
   },
   "mpnews":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"mpnews",
    "send_ignore_reprint":0
}

2、文本

{
   "filter":{
      "is_to_all":false,
      "tag_id":2
   },
   "text":{
      "content":"CONTENT"
   },
    "msgtype":"text"
}

3、语音/音频（注意：此处media_id需通过基础支持中的上传下载多媒体文件来得到）

{
   "filter":{
      "is_to_all":false,
      "tag_id":2
   },
   "voice":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"voice"
}

4、图片（注意：此处media_id需通过基础支持中的上传下载多媒体文件来得到）

{
   "filter":{
      "is_to_all":false,
      "tag_id":2
   },
   "image":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"image"
}

5、视频
视频消息较为特殊，它的media_id需要做一次转换：
1、通过基础支持中的上传下载多媒体文件来得到初步的media_id
2、将此media_id用post请求到https://api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN
3、微信后台返回新的media_id
4、与其他群发消息一样调用接口

{
   "filter":{
      "is_to_all":false,
      "tag_id":2
   },
   "mpvideo":{
      "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc"
   },
    "msgtype":"mpvideo"
}

注意：此json中的media_id是转换后的media_id

6、卡券消息

{
   "filter":{
      "is_to_all":false,
      "tag_id":"2"
   },
  "wxcard":{              
           "card_id":"123dsdajkasd231jhksad"         
            },
   "msgtype":"wxcard"
}

以上json数据中的：

• “filter”用于设定图文消息的接收者；
• “is_to_all”用于设定是否向全部用户发送，值为true或false，选择true该消息群发给所有用户，选择false可根据tag_id发送给指定群组的用户；
• “tag_id”为群发到的标签的tag_id，参见用户管理中用户分组接口，若is_to_all值为true，可不填写tag_id

7.2 根据OpenID列表群发【订阅号不可用，服务号认证后可用】

地址为：
post-https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN

1、图文消息（注意：图文消息的media_id需要通过“上传图文消息接口”中的方法来得到）

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
   "mpnews":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"mpnews"，
    "send_ignore_reprint":0
}

2、文本

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
    "msgtype": "text",
    "text": { "content": "hello from boxer."}
}

3、语音

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
   "voice":{
      "media_id":"mLxl6paC7z2Tl-NJT64yzJve8T9c8u9K2x-Ai6Ujd4lIH9IBuF6-2r66mamn_gIT"
   },
    "msgtype":"voice"
}

4、图片

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
   "image":{
      "media_id":"BTgN0opcW3Y5zV_ZebbsD3NFKRWf6cb7OPswPi9Q83fOJHK2P67dzxn11Cp7THat"
   },
    "msgtype":"image"
}

5、视频（视频的media_id需要做一次转换，详细过程请看“根据标签进行群发”的“视频”部分）

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
   "mpvideo":{
      "media_id":"123dsdajkasd231jhksad",
      "title":"TITLE",
      "description":"DESCRIPTION"
   },
    "msgtype":"mpvideo"
}

6、卡券

{
   "touser":[
    "OPENID1",
    "OPENID2"
   ],
        "wxcard": {"card_id":"123dsdajkasd231jhksad"}
        "msgtype":"wxcard"
}

以上json数据中的：

• “touser”为图文消息的接收者，一串OpenID列表，OpenID最少2个，最多10000个

---

八、删除群发【订阅号与服务号认证后均可用】

群发之后，随时可以通过该接口删除群发。
地址为：
post-https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
post数据如下：

参数	是否必须	说明
msg_id	是	发送出去的消息ID
article_idx	否	要删除的文章在图文消息中的位置，第一篇编号为1，该字段不填或填0会删除全部文章

注意：
1、只有已经发送成功的消息才能删除
2、删除消息是将消息的图文详情页失效，已经收到的用户，还是能在其本地看到消息卡片。
3、删除群发消息只能删除图文消息和视频消息，其他类型的消息一经发送，无法删除。
4、如果多次群发发送的是一个图文消息，那么删除其中一次群发，就会删除掉这个图文消息，导致所有群发都失效

---

九、预览接口【订阅号与服务号认证后均可用】

开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求，在保留对openID预览能力的同时，增加了对指定微信号发送预览的能力，但该能力每日调用次数有限制（100次），请勿滥用。
地址为：
post-https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN

1、图文消息

{
   "touser":"OPENID", 
   "mpnews":{              
            "media_id":"123dsdajkasd231jhksad"               
             },
   "msgtype":"mpnews" 
}

2、文本

{     
    "touser":"OPENID",
    "text":{           
           "content":"CONTENT"            
           },     
    "msgtype":"text"
}

3、语音

{
    "touser":"OPENID",
    "voice":{              
            "media_id":"123dsdajkasd231jhksad"
            },
    "msgtype":"voice" 
}

4、图片

{
    "touser":"OPENID",
    "image":{      
            "media_id":"123dsdajkasd231jhksad"
            },
    "msgtype":"image" 
}

5、视频

{
    "touser":"OPENID",
    "mpvideo":{  "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",   
               },
    "msgtype":"mpvideo" 
}

6、卡券

{ "touser":"OPENID", 
  "wxcard":{              
           "card_id":"123dsdajkasd231jhksad",
            "card_ext": "{"code":"","openid":"","timestamp":"1402057159","signature":"017bb17407c8e0058a66d72dcc61632b70f511ad"}"               
            }, 
  "msgtype":"wxcard" 
}

请注意，上述JSON数据中的touser字段都可以改为towxname，这样就可以针对微信号进行预览（而非openID），towxname和touser同时赋值时，以towxname优先

---

十、查询群发消息发送状态【订阅号与服务号认证后均可用】

地址为：
post-https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN
post数据为：

{
   "msg_id": "201053012"
}

返回数据为（正确时）：

{
     "msg_id":201053012,
     "msg_status":"SEND_SUCCESS"
}

其中msg_status为消息发送后的状态，SEND_SUCCESS表示发送成功，SENDING表示发送中，SEND_FAIL表示发送失败，DELETE表示已删除

---

十一、事件推送群发结果

由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者URL（callback URL）推送事件（需要注意，由于群发任务彻底完成需要较长时间，将会在群发任务即将完成的时候，就推送群发结果，此时的推送人数数据将会与实际情形存在一定误差）。

推送数据如下（示例）：

<xml>
<ToUserName>< ![CDATA[gh_4d00ed8d6399] ]>ToUserName>
<FromUserName>< ![CDATA[oV5CrjpxgaGXNHIQigzNlgLTnwic] ]>FromUserName>
<CreateTime>1481013459CreateTime>
<MsgType>< ![CDATA[event] ]>MsgType>
<Event>< ![CDATA[MASSSENDJOBFINISH] ]>Event>
<MsgID>1000001625MsgID>
<Status>< ![CDATA[err(30003)] ]>Status>
<TotalCount>0TotalCount>
<FilterCount>0FilterCount>
<SentCount>0SentCount>
<ErrorCount>0ErrorCount>
<CopyrightCheckResult>
<Count>2Count>
<ResultList>
<item>
<ArticleIdx>1ArticleIdx>
<UserDeclareState>0UserDeclareState>
<AuditState>2AuditState>
<OriginalArticleUrl>< ![CDATA[Url_1] ]>OriginalArticleUrl>
<OriginalArticleType>1OriginalArticleType>
<CanReprint>1CanReprint>
<NeedReplaceContent>1NeedReplaceContent>
<NeedShowReprintSource>1NeedShowReprintSource>
item>
<item>
<ArticleIdx>2ArticleIdx>
<UserDeclareState>0UserDeclareState>
<AuditState>2AuditState>
<OriginalArticleUrl>< ![CDATA[Url_2] ]>OriginalArticleUrl>
<OriginalArticleType>1OriginalArticleType>
<CanReprint>1CanReprint>
<NeedReplaceContent>1NeedReplaceContent>
<NeedShowReprintSource>1NeedShowReprintSource>
item>
ResultList>
<CheckState>2CheckState>
CopyrightCheckResult>
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(30001) // 原创校验出现系统错误且用户选择了被判为转载就不群发 err(30002) // 原创校验被判定为不能群发 err(30003) // 原创校验被判定为转载文且用户选择了被判为转载就不群发
TotalCount	tag_id下粉丝数；或者openid_list中的粉丝数
FilterCount	过滤（过滤是指特定地区、性别的过滤、用户设置拒收的过滤，用户接收已超4条的过滤）后，准备发送的粉丝数，原则上，FilterCount = SentCount + ErrorCount
SentCount	发送成功的粉丝数
ErrorCount	发送失败的粉丝数
ResultList	各个单图文校验结果
ArticleIdx	群发文章的序号，从1开始
UserDeclareState	用户声明文章的状态
AuditState	系统校验的状态
OriginalArticleUrl	相似原创文的url
OriginalArticleType	相似原创文的类型
CanReprint	是否能转载
NeedReplaceContent	是否需要替换成原创文内容
NeedShowReprintSource	是否需要注明转载来源
CheckState	整体校验结果，1-未被判为转载，可以群发，2-被判为转载，可以群发，3-被判为转载，不能群发

---

十二、使用 clientmsgid 参数，避免重复推送

群发接口新增 clientmsgid 参数，开发者调用群发接口时可以主动设置 clientmsgid 参数，避免重复推送。群发时，微信后台将对 24 小时内的群发记录进行检查，如果该 clientmsgid 已经存在一条群发记录，则会拒绝本次群发请求，返回已存在的群发msgid，开发者可以调用“查询群发消息发送状态”接口查看该条群发的状态。
使用方法：
在群发时（根据OpenID列表群发或根据标签进行群发）在post数据中加入clientmsgid字段（开发方维护的群发msgid，长度限制64字节，如不填，则后台默认以群发范围和群发内容的摘要值做为clientmsgid）。
示例（根据标签进行群发）：

{
    "filter":{
       "is_to_all":false,
       "tag_id":2
    },
    "mpnews":{
       "media_id":"123dsdajkasd231jhksad"
    },
     "msgtype":"mpnews",
     "send_ignore_reprint":0,
     "clientmsgid":"send_tag_2" 
}

---

十三、控制群发速度

开发者可以使用限速接口来控制群发速度。

• 获取群发速度
  地址为：
  post-https://api.weixin.qq.com/cgi-bin/message/mass/speed/get?access_token=ACCESS_TOKEN
  返回结果为：

  参数	是否必须	说明
  speed	是	群发速度的级别
  realspeed	是	群发速度的真实值 单位：万/分钟

• 设置群发速度
  地址为：
  post-https://api.weixin.qq.com/cgi-bin/message/mass/speed/set?access_token=ACCESS_TOKEN
  post数据为：

  {
      "speed":1
  }

  群发速度（speed）的级别，是一个0到4的整数，数字越大表示群发速度越慢。

• speed 与 realspeed 的关系如下：

  speed	realspeed
  0	80w/分钟
  1	60w/分钟
  2	45w/分钟
  3	30w/分钟
  4	10w/分钟