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

说明

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

限制：

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为true（表示对所有用户发送）使其进入公众号在微信客户端的历史消息列表：

1、使用is_to_all为true且成功群发，会使得此次群发进入历史消息列表。

2、为防止异常，认证订阅号在一天内，只能使用is_to_all为true进行群发一次，或者在公众平台官网群发（不管本次群发是对全体还是对某个分组）一次。以避免一天内有2条群发
4000
进入历史消息列表。

3、类似地，服务号在一个月内，使用is_to_all为true群发的次数，加上公众平台官网群发（不管本次群发是对全体还是对某个分组）的次数，最多只能是4次。

4、设置is_to_all为false时是可以多次群发的，但每个用户只会收到最多4条，且这些群发不会进入历史消息列表。

上传图文消息接口

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

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

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

地址：

post-

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

调用示例：

curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN"

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

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

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

地址：

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
}

原创校验

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

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

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

当前准备群发的文章，未命中原创库中的文章，则可以群发。

当前准备群发的文章，已命中原创库中的文章，则：

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

若原创作者禁止转载该文章，则不能进行群发（若希望转载该篇文章，可自行与原创公众号作者联系并获得授权之后再进行群发）。

群发接口的 send_ignore_reprint 参数

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

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

当 send_ignore_reprint 参数设置为0时（默认），文章被判定为转载时，将停止群发操作。

开始群发

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

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

地址为：

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

根据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>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>
</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/分钟