Advanced group sending interface

##Advanced group sending interface

On the public platform website, subscription accounts are provided with one group message permission per day, and service accounts are provided with 4 messages per month (natural month) group sending permission. For some public account operators with development capabilities, they can achieve more flexible group sending capabilities through the advanced group sending interface.

Please note:

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

The process of sending group pictures and text messages is as follows:

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

The process of group sending pictures, texts and other message types is as follows:

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

Regarding using is_to_all as true when sending a group message, it will enter the historical message list of the official account in the WeChat client:

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

In addition, developers please note that all places where media_id is used in this interface can now use material management The permanent material media_id in the. Please note that the links sent out using the same material are the same. This means that deleting a certain group will cause the entire link to become invalid.

Upload the picture in the graphic message to obtain the URL [available after the subscription account and service account are authenticated]

Please note that the pictures uploaded through this interface do not occupy the 5,000 limit of the number of pictures in the public account’s material library. Images only support jpg/png format, and the size must be less than 1MB.

Interface call request description

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"

Parameter description

Parameter	Is it required	Description
access_token	Yes	Call interface credentials
media	is the media file identifier in	form-data, including filename, filelength, content-type, etc. information

Return instructions Under normal circumstances, the return result is:

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

The url is the URL of the uploaded image, which can be used in subsequent group sending and placed in graphic messages.

In case of error, WeChat will return error code and other information. Please query the error information based on the error code

##Upload graphic message materials [available after authentication of subscription account and service account]

Interface call request instructions

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

POST data description

POST data examples are as follows:

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

##content_source_urlNoThe page after clicking "Read the original text" on the graphic message page is subject to security restrictions. If you need to jump to the Appstore, you can use the short link service of itun.es or appsto.re, and add the #wechat_redirect suffix after the short link. . content is the content of the graphic message page and supports HTML tags.Official accounts with WeChat payment permissions can use the a tag, but other official accounts cannot use

Parameter	Is it necessary	Description
Articles	Yes	Graphic message, one graphic message supports 1 to 8 graphic messages
thumb_media_id	is the abbreviation of	The media_id of the thumbnail can be obtained from the basic support-upload multimedia file interface
author	No	The author of the graphic message
title	Yes	The title of the graphic message


digest	No	Description of graphic messages
show_cover_pic	No	Whether to display the cover, 1 means to display it, 0 means not to display it

Return instructions

Return data example (JSON return result when correct):

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

Parameters	Description
type	Media file types include image, voice, video and thumbnail, image and text News (news)
media_id	The unique identifier obtained after the media file/graphic message is uploaded
created_at	Media file upload time

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

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

接口调用请求说明

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

POST data description

POST data examples are as follows:

Graphic message (note that the media_id of the graphic message needs to be obtained through the above method):

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

Text:

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

Voice (note that the media_id here needs to be uploaded through basic support) Download multimedia files to get):

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

Pictures (note that the media_id here needs to be obtained by uploading and downloading multimedia files in basic support):

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

Video

Please note , the media_id of the video here needs to be obtained through POST request to the following interface: https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN POST The data is as follows (media_id here needs to be obtained by uploading and downloading multimedia files in basic support):

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

The return will be

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

Then, POST the following data (change media_id to the previous step media_id obtained from ), you can send

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

card and coupon messages (note that the media_id of graphic messages needs to be obtained through the above method):

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

# used for group messages ##

Parameter	Is it necessary	Description
filter	Yes	Used to set the recipients of graphic messages
is_to_all	No	Used to set whether to send to all users, The value is true or false. Select true to send the message to all users in bulk. Select false to send it to users in the specified group based on tag_id
tag_id	No	The tag_id of the tag sent in bulk, participate in the user grouping interface in user management. If the is_to_all value is true, you do not need to fill in the tag_id
mpnews	Yes	Used to set the graphic message to be sent
media_id	is the media_id
msgtype	is the message type of	. The graphic message is mpnews, the text message is text, the voice is voice, the music is music, the picture is image, and the video is video, the card coupon is wxcard
title	No	Title of the message
description	No	Description of the message
thumb_media_id	is the media ID of the	video thumbnail

Return instructions

Return data example (JSON return result when correct):

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

Parameters	Description
type	Media file types include image, voice, video and thumbnail, Figure The text message is news
errcode	Error code
errmsg	Error message
msg_id	The ID of the message sending task
msg_data_id	The data ID of the message. This field is only available in the group sending diagram It will only appear when you send a message. It can be used to obtain the data of the corresponding graphic message in the graphic and text analysis data interface. It is the first half of the msgid field in the graphic and text analysis data interface. For details, see the introduction of the msgid field in the graphic and text analysis data interface.

Please note: When the success is returned, it means that the mass sending task was successfully submitted, but it does not mean that the mass sending has ended at this time . Therefore, it is still possible that an abnormal situation may occur during the subsequent sending process, causing the user to The message is not received, for example, the message is sometimes reviewed, the server is unstable, etc. In addition, mass sending tasks generally take a long time to be sent completely, please wait patiently .

In case of error, WeChat will return error code and other information. Please query the error information based on the error code

##Multiple messages based on the OpenID list [Subscription account is not available, service account is available after authentication]

Interface call request description

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

POST data description

POST data examples are as follows:

图文消息（注意图文消息的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"
}

Coupon:

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

参数	是否必须	说明
touser	是	填写图文消息的接收者，一串OpenID列表，OpenID最少2个，最多10000个
mpnews	是	用于设定即将发送的图文消息
media_id	是	用于群发的图文消息的media_id
msgtype	is the message type of	. The graphic message is mpnews, the text message is text, the voice is voice, the music is music, the picture is image, and the video is video, the card coupon is wxcard
title	No	Title of the message
description	No	Description of the message
thumb_media_id	is the media ID of the	video thumbnail

返回说明

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

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

参数	说明
type	媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息
errcode	错误码
errmsg	错误信息
msg_id	消息发送任务的ID
msg_data_id	消息的数据ID，，该字段只有在群发图文消息时，才会出现。可以用于在图文分析数据接口中，获取到对应的图文消息的数据，是图文分析数据接口中的msgid字段中的前半部分，详见图文分析数据接口中的msgid字段的介绍。

In case of error, WeChat will return error code and other information. Please query the error information based on the error code

##Delete the group message [Available after the subscription account and service account are authenticated]

After the group message is sent, you can delete the group message at any time through this interface .

接口调用请求说明

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

POST data description

POST data examples are as follows:

{
   "msg_id":30124
}

参数	是否必须	说明
msg_id	是	发送出去的消息ID

Please note:

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

Return instructions

Return data example (JSON return result when correct):

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

Parameter	Description
errcode	Error code
errmsg	error message

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

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

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

接口调用请求说明

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

POST data description

POST data examples are as follows:

图文消息（其中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" 
}

Parameter	Description
touser	The openid of the user who receives the message corresponding to the official account, This field can also be changed to towxname to preview the WeChat account
msgtype	The message type of the group, the graphic message is mpnews, the text message is text, The voice is voice, the music is music, the picture is image, the video is video, and the coupon is wxcard
media_id	The media_id used for group messages
content	The content of the text when sending a text message

Return instructions

Return data example (JSON return result when correct):

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

Parameter	Description
errcode	Error code
errmsg	Error message
msg_id	Message ID

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

接口调用请求说明

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

POST data description

POST data examples are as follows:

{
   "msg_id": "201053012"
}

Parameter	Description
msg_id	The message id returned after sending a group message

Return description

Return data example (JSON return result when correct):

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

Parameters	Description
msg_id	The message id returned after sending a group message
msg_status	The status after the message is sent, SEND_SUCCESS means the sending is successful

#Event push group results

Since the group sending task may be completed after a certain period of time after the group sending task is submitted, when the group sending interface is called, only a prompt will be given whether the group sending task is submitted successfully. If the group sending task is submitted successfully, the group sending task will be At the end, the event will be pushed to the developer URL (callback URL) filled in by the developer on the public platform.

It should be noted that since the mass sending task takes a long time to be completely completed, the mass sending result will be pushed when the mass sending task is about to be completed. The number of people pushed at this time will be different from the actual situation. Error

The pushed XML structure is as follows (when sent successfully):

<xml>
<ToUserName><![CDATA[gh_3e8adccde292]]></ToUserName>
<FromUserName><![CDATA[oR5Gjjl_eiZoUpGozMo7dbBJ362A]]></FromUserName>
<CreateTime>1394524295</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[MASSSENDJOBFINISH]]></Event>
<MsgID>1988</MsgID>
<Status><![CDATA[sendsuccess]]></Status>
<TotalCount>100</TotalCount>
<FilterCount>80</FilterCount>
<SentCount>75</SentCount>
<ErrorCount>5</ErrorCount>
</xml>

#MsgTypeMessage type, here is eventEventEvent information, here is MASSSENDJOBFINISH MsgIDThe message ID of the mass messageStatusThe structure of the mass message is "send success" ” or “send fail” or “err(num)”. However, when sending success, a small number of users may fail to receive messages due to users refusing to receive messages from the official account, system errors, etc. err(num) is the specific reason for the audit failure. The possible situations are as follows:

Parameter	Description
ToUserName	WeChat ID of the public account
FromUserName	The WeChat ID of the public account group assistant, the timestamp of the creation time for mphelper




	err(10001), //suspected advertising err(20001), //suspected political err(20004), //suspected social err(20002) , //suspected of pornography err(20006), //suspected of illegal crimes err(20008), //suspected of fraud err(20013), //suspected of copyright err(22000), //suspected of mutual promotion (mutual promotion) err(21000) ), //suspected of other
TotalCount	The number of fans under tag_id; or the number of fans in openid_list
FilterCount	Filter (Filtering refers to filtering for specific regions, genders, filtering that the user sets to reject, and filtering that the user has received more than 4 items), the number of fans to be sent, in principle, FilterCount = SentCount ErrorCount
SentCount	Number of fans sent successfully
ErrorCount	Number of fans sent failed

← Customer service message

Template message interface →

Advanced group sending interface

Upload the picture in the graphic message to obtain the URL [available after the subscription account and service account are authenticated]

##Upload graphic message materials [available after authentication of subscription account and service account]

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

##Multiple messages based on the OpenID list [Subscription account is not available, service account is available after authentication]

##Delete the group message [Available after the subscription account and service account are authenticated]

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

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

#Event push group results

php.cn