高级群发接口

在公众平台网站上，为订阅号提供了每天一条的群发权限，为服务号提供每月（自然月）4条的群发权限。而对于某些具备开发能力的公众号运营者，可以通过高级群发接口，实现更灵活的群发能力。

请注意：

1、对于认证订阅号，群发接口每天可成功调用1次，此次群发可选择发送给全部用户或某个标签； 2、对于认证服务号虽然开发者使用高级群发接口的每日调用限制为100次，但是用户每月只能接收4条，无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败； 3、具备微信支付权限的公众号，在使用群发接口上传、群发图文消息类型时，可使用标签加入外链； 4、开发者可以使用预览接口校对消息样式和排版，通过预览接口可发送编辑好的消息给指定用户校验效果。

1、首先，预先将图文消息中需要用到的图片，使用上传图文消息内图片接口，上传成功并获得图片URL 2、上传图文消息素材，需要用到图片时，请使用上一步获取的图片URL 3、使用对用户标签的群发，或对OpenID列表的群发，将图文消息群发出去 4、在上述过程中，如果需要，还可以预览图文消息、查询群发状态，或删除已群发的消息等

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

1、使用is_to_all为true且成功群发，会使得此次群发进入历史消息列表。 2、为防止异常，认证订阅号在一天内，只能使用is_to_all为true进行群发一次，或者在公众平台官网群发（不管本次群发是对全体还是对某个分组）一次。以避免一天内有2条群发进入历史消息列表。 3、类似地，服务号在一个月内，使用is_to_all为true群发的次数，加上公众平台官网群发（不管本次群发是对全体还是对某个分组）的次数，最多只能是4次。 4、设置is_to_all为false时是可以多次群发的，但每个用户只会收到最多4条，且这些群发不会进入历史消息列表。

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

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN 调用示例（使用curl命令，用FORM表单方式上传一个图片）： curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN"

参数说明

返回说明正常情况下的返回结果为：

{ "url": "http://mmbiz.qpic.cn/mmbiz/gLO17UPS6FS2xsypf378iaNhWacZ1G1UplZYWEYfwvuU6Ont96b1roYs CNFwaRrSaKTPCUdBK9DgEHicsKwWCBRQ/0" }

其中url就是上传图片的URL，可用于后续群发中，放置到图文消息中。

错误时微信会返回错误码等信息，请根据错误码查询错误信息

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{ "articles": [ { "thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelOXCFZiq2OsIU-p", "author":"xxx", "title":"Happy Day", "content_source_url":"www.qq.com", "content":"content", "digest":"digest", "show_cover_pic":1 }, { "thumb_media_id":"qI6_Ze_6PtV7svjolgs-rN6stStuHIjs9_DidOHaj0Q-mwvBelOXCFZiq2OsIU-p", "author":"xxx", "title":"Happy Day", "content_source_url":"www.qq.com", "content":"content", "digest":"digest", "show_cover_pic":0 } ] }

返回说明

返回数据示例（正确时的JSON返回结果）：

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

错误时微信会返回错误码等信息，请根据错误码查询错误信息

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

图文消息（注意图文消息的media_id需要通过上述方法来得到）：

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

文本：

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

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

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

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

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

视频

请注意，此处视频的media_id需通过POST请求到下述接口特别地得到：https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKENPOST数据如下（此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{ "media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ", "title": "TITLE", "description": "Description" }

返回将为

{ "type":"video", "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc", "created_at":1398848981 }

然后，POST下述数据（将media_id改为上一步中得到的media_id），即可进行发送

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

卡券消息（注意图文消息的media_id需要通过上述方法来得到）：

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

返回说明

返回数据示例（正确时的JSON返回结果）：

{ "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 }

请注意：在返回成功时，意味着群发任务提交成功，并不意味着此时群发已经结束，所以，仍有可能在后续的发送过程中出现异常情况导致用户未收到消息，如消息有时会进行审核、服务器不稳定等。此外，群发任务一般需要较长的时间才能全部发送完毕，请耐心等待。

错误时微信会返回错误码等信息，请根据错误码查询错误信息

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

图文消息（注意图文消息的media_id需要通过上述方法来得到）：

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

文本：

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

语音：

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

图片：

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

视频：

请注意，此处视频的media_id需通过POST请求到下述接口特别地得到： https://api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN POST数据如下（此处media_id需通过基础支持中的上传下载多媒体文件来得到）：

{ "media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ", "title": "TITLE", "description": "Description" }

返回将为

{ "type":"video", "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc", "created_at":1398848981 }

然后，POST下述数据（将media_id改为上一步中得到的media_id），即可进行发送

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

卡券：

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

返回说明

返回数据示例（正确时的JSON返回结果）：

{ "errcode":0, "errmsg":"send job submission success", "msg_id":34182, "msg_data_id": 206227730 }

请注意：在返回成功时，意味着群发任务提交成功，并不意味着此时群发已经结束，所以，仍有可能在后续的发送过程中出现异常情况导致用户未收到消息，如消息有时会进行审核、服务器不稳定等。此外，群发任务一般需要较长的时间才能全部发送完毕，请耐心等待。

错误时微信会返回错误码等信息，请根据错误码查询错误信息

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

群发之后，随时可以通过该接口删除群发。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{ "msg_id":30124 }

请注意：

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

返回说明

返回数据示例（正确时的JSON返回结果）：

{ "errcode":0, "errmsg":"ok" }

错误时微信会返回错误码等信息，请根据错误码查询错误信息

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

开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求，在保留对openID预览能力的同时，增加了对指定微信号发送预览的能力，但该能力每日调用次数有限制（100次），请勿滥用。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

图文消息（其中media_id与根据分组群发中的media_id相同）：

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

文本：

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

语音（其中media_id与根据分组群发中的media_id相同）：

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

图片（其中media_id与根据分组群发中的media_id相同）：

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

视频（其中media_id与根据分组群发中的media_id相同）：

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

卡券：

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

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

{ "towxname":"示例的微信号", "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews" }

返回说明

返回数据示例（正确时的JSON返回结果）：

{ "errcode":0, "errmsg":"preview success", "msg_id":34182 }

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN

POST数据说明

POST数据示例如下：

{ "msg_id": "201053012" }

返回说明

返回数据示例（正确时的JSON返回结果）：

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

事件推送群发结果

由于群发任务提交后，群发任务可能在一定时间后才完成，因此，群发接口调用时，仅会给出群发任务是否提交成功的提示，若群发任务提交成功，则在群发任务结束时，会向开发者在公众平台填写的开发者URL（callback URL）推送事件。

需要注意，由于群发任务彻底完成需要较长时间，将会在群发任务即将完成的时候，就推送群发结果，此时的推送人数数据将会与实际情形存在一定误差

推送的XML结构如下（发送成功时）：

   1394524295   1988  100 80 75 5