The Official Accounts Platform website allows Subscription Accounts to broadcast once per day and Service Accounts to broadcast four times per calendar month. Some Official Account operators with development capabilities can achieve more flexible broadcast capabilities through the advanced broadcast API.
Notes:
1. For verified Subscription Accounts, the broadcast API can be successfully called once per day. The broadcast message can be sent to all users or users under a tag.
2. For verified Service Accounts, developers can call the advanced broadcast API 100 times per day, but users can only receive 4 broadcast messages each month, regardless of whether these messages are sent on the Official Accounts Platform website or via the API. The broadcast messages exceeding the limit (4) cannot be sent to users.
3. Developers can use the preview API to check the message style and typesetting and also send an edited message to the specified user to verify the result.
4. During the broadcast process, the Weixin backend will automatically review the article for originality. Set relevant parameters (send_ignore, etc.) in advance.
5. Developers can set up clientmsgid to avoid repeated pushes.
6. A maximum of 60 requests per minute is allowed for the broadcast API. Requests over the limit will be rejected.
7. Links to articles broadcasted from your account and other Official Accounts can be added in the main body of the article.
The process of broadcasting an article is as follows:
1. Upload the image needed in the article in advance using the "Upload Images in Article" API and get the image URL.
2. Upload the article asset. When you need to use the image, use the image URL obtained in the previous step.
3. Broadcast the article to users under a tag or users in the OpenID list. During the broadcast process, Weixin will review the originality and return the broadcast result.
4. In the above processes, you can preview the article, query the broadcast status, or delete the broadcasted message when necessary.
The process of broadcasting images, texts, and other message types is as follows:
1 To broadcast a text message, directly follow the API description below.
2 To broadcast an image or video message, get the mediaID in advance via the Media Asset Management API.
Notes:
1. If is_to_all is set to true for a broadcast, the successfully sent broadcast message will be included in the history message list of the Official Account in the Weixin app.
2. To prevent exceptions, a verified Subscription Account can only broadcast once by setting is_to_all to true or on the Official Accounts Platform website (whether to all users or to a group) per day. This is to avoid having 2 broadcast messages included in the history message list in one day.
3. Similarly, a Service Account can only broadcast 4 times by setting is_to_all to true and on the Official Accounts Platform website (whether to all users or to a group) per month.
4. If is_to_all is set to false, multiple broadcasts are allowed. However, each user will only receive up to 4 broadcast messages, and these messages will not be included in the history message list.
In addition, developers should know that the media_id of permanent assets in Media Asset Management can be used where media_id is required in the API. Note that the links broadcasted using the same asset are the same, which means that deleting a broadcast will invalidate all the links.
Contents
2 Uploading Articles (Available for Verified Subscription Accounts and Verified Service Accounts)
3 Broadcast by Tag (Available for Verified Subscription Accounts and Verified Service Accounts)
5 Deleting Broadcasts (Available for Verified Subscription Accounts and Verified Service Accounts)
6 Preview (Available for Verified Subscription Accounts and Verified Service Accounts)
9 Using the clientmsgid Parameter to Avoid Repeated Push
10 Controlling Broadcast Speed
# Uploading Images in Article to Obtain URL (Available for Verified Subscription Accounts and Verified Service Accounts)
Note that the images uploaded via this API are excluded from the maximum storage limit of 5,000 images for an Official Account's media asset library. Only JPG/PGN images smaller than 1 MB are supported.
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
Calling Example (using the curl command to upload an image via FORM):
curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN"
Parameters:
| Parameter | Required | Description |
|---|---|---|
| access_token | Yes | The credential for calling the API |
| media | Yes | The identifier of the media file in form-data, including the information such as filename, filelength, and content-type. |
Response description The result returned for a successful request:
{
"url": "http://mmbiz.qpic.cn/mmbiz/gLO17UPS6FS2xsypf378iaNhWacZ1G1UplZYWEYfwvuU6Ont96b1roYs CNFwaRrSaKTPCUdBK9DgEHicsKwWCBRQ/0"
}
The above URL is the URL of the uploaded image and can be used in articles for broadcasting later.
When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.
# Uploading Articles (Available for Verified Subscription Accounts and Verified Service Accounts)
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN
POST data description
POST data example:
{
"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,
"need_open_comment":1,
"only_fans_can_comment":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,
"need_open_comment":1,
"only_fans_can_comment":1
}
]
}
| Parameter | Required | Description |
|---|---|---|
| Articles | Yes | Article. A broadcast can contain 1 to 8 articles. |
| thumb_media_id | Yes | The media_id of the thumbnail of an article, which can be obtained in Media Asset Management > New Assets. |
| author | No | The article's author |
| title | Yes | The article's title |
| content_source_url | No | The page to be redirected to after Read More on the article page is tapped. For security reasons, if you need to redirect to the Appstore, you can use a short URL such as itun.es or appsto.re and suffix #wechat_redirect to the short URL. |
| content | Yes | The content of the article page. HTML tags are supported. Only Official Accounts with WeChat Pay permission can use "a" tags. To insert Mini Program cards, see below. |
| digest | No | The article description. If this field is left empty, the first 64 characters in the main body will be fetched by default. |
| show_cover_pic | No | Indicates whether to display the cover. 1: True; 0: False. |
| need_open_comment | No | Uint32 Indicates whether to enable comment. 0: Disabled; 1: Enabled. |
| only_fans_can_comment | No | Uint32 Indicates whether to allow followers to comment only. 0: All users; 1: Followers. |
To insert a Mini Program in the broadcast article, you need to add a redirect link to the Mini Program in the "content" field when calling the "Upload Articles" API. There are three styles to choose from.
Redirect to the Mini Program by tapping the Mini Program card. Code example:
<mp-miniprogram data-miniprogram-appid="wx123123123" data-miniprogram-path="pages/index/index" data-miniprogram-title="Mini Program example" data-progarm-imageurl="http://example.com/demo.jpg"></mp-miniprogram>
Redirect to the Mini Program by tapping the text. Code example:
<p><a data-miniprogram-appid="wx123123123" data-miniprogram-path="pages/index" href="">Tap the text to redirect to the Mini Program</a></p>
Redirect to the Mini Program by tapping the image. Code example:
<p><a data-miniprogram-appid="wx123123123" data-miniprogram-path="pages/index" href=""><img src="https://mmbiz.qpic.cn/mmbiz_jpg/demo/0?wx_fmt=jpg" alt="" data-width="null" data-ratio="NaN"></a></p>
Parameters
| Parameter | Required | Description |
|---|---|---|
| data-miniprogram-appid | Yes | The AppID of the Mini Program |
| data-miniprogram-path | Yes | The path to the Mini Program to be opened |
| data-miniprogram-title | Yes | The title of the Mini Program card, not more than 35 characters. |
| data-miniprogram-imageurl | Yes | The URL to the cover image of the Mini Program card. The image size must be 1080*864 pixels. |
Response
Example of response data (The returned JSON packet for a successful request):
{
"type":"news",
"media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",
"created_at":1391857799
}
| Parameter | Description |
|---|---|
| type | Media file types, including images (parameter = "image"), voice (parameter = "voice"), videos (parameter = "video"), thumbnails (parameter = "thumb"), and articles (parameter = "news"). |
| media_id | The unique identifier of an uploaded media file/article |
| created_at | Upload time of the media file |
When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.
Originality review will be performed before an article is broadcasted
I. The originality review process is added for the Broadcast API
When a developer calls the Broadcast API to broadcast an article, Weixin will compare the article to be broadcasted by the developer with the articles in the Original Works Archive of the Official Accounts Platform. The review results are divided into the following types:
When the article to be broadcasted does not hit any article in the Original Works Archive, it can be broadcasted.
When the article to be broadcasted hits an article in the Original Works Archive:
2.1 It can be broadcasted if the original author allows reposts. When the article is broadcasted, it will be automatically restored to the original style and amarked as a repost with the source indicated.
If you want to change the original content or style, or do not want to display the original author when broadcasting the article, you can contact the original author of the Official Account to obtain authorization.
2.2 It cannot be broadcasted if the original author forbids reposts.
If you still want to repost the article, you can contact the original author of the Official Account to obtain authorization.
II. The send_ignore_reprint parameter is added in the Broadcast API
The send_ignore_reprint parameter is added in the Broadcast API. Developers can set the parameter to specify whether to continue broadcasting an article which is determined to be a repost.
If the send_ignore_reprint parameter is set to 1, when an article is determined to be a repost and the original author allows reposts, the broadcast will continue.
If the send_ignore_reprint parameter is set to 0, when an article is determined to be a repost, the broadcast will be stopped.
The send_ignore_reprint defaults to 0.
For relevant error codes of the broadcast operation, see the Common Error Codes documentation.
# Broadcast by Tag (Available for Verified Subscription Accounts and Verified Service Accounts)
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN
POST data description
POST data example:
Article (get the article's media_id by the above method):
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"mpnews":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"mpnews",
"send_ignore_reprint":0
}
Text:
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"text":{
"content":"CONTENT"
},
"msgtype":"text"
}
Voice/Audio (get the media_id from Media Asset Management > New Assets):
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"voice":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"voice"
}
Image (get the media_id from Media Asset Management > New Assets):
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"image":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"image"
}
Video
Note that the media_id of the video here is specifically obtained via the POST request to the following API: https://api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN. The POST data is as follows (get the media_id from Media Asset Management > New Assets):
{
"media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ",
"title": "TITLE",
"description": "Description"
}
The response will be as follows
{
"type":"video",
"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",
"created_at":1398848981
}
Then, POST the following data (change the media_id to the media_id obtained in the previous step), and you can broadcast the message
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"mpvideo":{
"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc"
},
"msgtype":"mpvideo"
}
Card/Coupon message (get the article's media_id by the above method):
{
"filter":{
"is_to_all":false,
"tag_id":"2"
},
"wxcard":{
"card_id":"123dsdajkasd231jhksad"
},
"msgtype":"wxcard"
}
| Parameter | Required | Description |
|---|---|---|
| filter | Yes | Sets the recipients of the article |
| is_to_all | No | Sets whether to broadcast the message to all users. The value of "true" means broadcasting the message to all users, and "false" means broadcasting the message to the users of the specified group according to the tag_id. |
| tag_id | No | The tag_id of the tag of the users to which the message is broadcasted. See User Group API in User Management. If is_to_all is set to true, tag_id is not required. |
| mpnews | Yes | Sets the article to be sent |
| media_id | Yes | The media_id of the message to be broadcasted |
| msgtype | Yes | Broadcast message types, including articles (parameter = "mpnews"), text (parameter = "text"), voices (parameter = "voice"), music (parameter = "music"), images (parameter = "image"), videos (parameter = "video"), and cards/coupons (parameter = "wxcard"). |
| title | No | The message's title |
| description | No | The message description |
| thumb_media_id | Yes | The media ID of the video thumbnail |
| send_ignore_reprint | Yes | Indicates whether to continue broadcasting an article which is determined to be a repost. 1 means continuing broadcasting (repost), and 0 means stopping broadcasting (default). |
Response
Example of response data (The returned JSON packet for a successful request):
{
"errcode":0,
"errmsg":"send job submission success",
"msg_id":34182,
"msg_data_id": 206227730
}
| Parameter | Description |
|---|---|
| type | Media file types, including images (parameter = "image"), voice (parameter = "voice"), videos (parameter = "video"), thumbnails (parameter = "thumb"), and articles (parameter = "news"). |
| errcode | Error code |
| errmsg | Error message |
| msg_id | Message sending task ID |
| msg_data_id | The data ID of the message. This field is displayed only when an article is to be broadcasted. As a part of the msgid field in the Article Summary API, it can be used to obtain the data of the appropriate article in the Article Summary API. For details, see the description of the msgid field in the Article Summary API. |
Note: A success response indicates the successful submission of a broadcast task rather than the completion of the task. Therefore, exceptions may still occur during the broadcasting process that cause users' failure to receive the message, such as message review and server instability. In addition, broadcast tasks generally take a long time to complete. Please be patient.
When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.
# Broadcast by OpenID List (Unavailable for Subscription Accounts and Available for Verified Service Accounts)
API fequest format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN
POST data description
POST data example:
Article (get the article's media_id by the above method):
{
"touser":[
"OPENID1",
"OPENID2"
],
"mpnews":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"mpnews",
"send_ignore_reprint":0
}
Text:
{
"touser":[
"OPENID1",
"OPENID2"
],
"msgtype": "text",
"text": { "content": "hello from boxer."}
}
Voice:
{
"touser":[
"OPENID1",
"OPENID2"
],
"voice":{
"media_id":"mLxl6paC7z2Tl-NJT64yzJve8T9c8u9K2x-Ai6Ujd4lIH9IBuF6-2r66mamn_gIT"
},
"msgtype":"voice"
}
Image:
{
"touser":[
"OPENID1",
"OPENID2"
],
"image":{
"media_id":"BTgN0opcW3Y5zV_ZebbsD3NFKRWf6cb7OPswPi9Q83fOJHK2P67dzxn11Cp7THat"
},
"msgtype":"image"
}
Video:
Note that the media_id of the video here is specifically obtained via the POST request to the following API: https://api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN. The POST data is as follows (get the media_id from Media Asset Management > New Assets):
{
"media_id": "rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ",
"title": "TITLE",
"description": "Description"
}
The response will be as follows
{
"type":"video",
"media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",
"created_at":1398848981
}
Then, POST the following data (change the media_id to the media_id obtained in the previous step), and you can broadcast the message
{
"touser":[
"OPENID1",
"OPENID2"
],
"mpvideo":{
"media_id":"123dsdajkasd231jhksad",
"title":"TITLE",
"description":"DESCRIPTION"
},
"msgtype":"mpvideo"
}
Card/Coupon:
{
"touser":[
"OPENID1",
"OPENID2"
],
"wxcard": {"card_id":"123dsdajkasd231jhksad"}
"msgtype":"wxcard"
}
| Parameter | Required | Description |
|---|---|---|
| touser | Yes | The recipients of the article. It is a list of OpenIDs, with a minimum of 2 OpenIDs and a maximum of 10000. |
| mpnews | Yes | Sets the article to be sent |
| media_id | Yes | The media_id of the article to be broadcasted |
| msgtype | Yes | Broadcast message types, including articles (parameter = "mpnews"), text (parameter = "text"), voices (parameter = "voice"), music (parameter = "music"), images (parameter = "image"), videos (parameter = "video"), and cards/coupons (parameter = "wxcard"). |
| title | No | The message's title |
| description | No | The message description |
| thumb_media_id | Yes | The media ID of the video thumbnail |
| send_ignore_reprint | Yes | Indicates whether to continue broadcasting an article which is determined to be a repost. 1 means continuing broadcasting (repost), and 0 means stopping broadcasting (default). |
Response
Example of response data (The returned JSON packet for a successful request):
{
"errcode":0,
"errmsg":"send job submission success",
"msg_id":34182,
"msg_data_id": 206227730
}
| Parameter | Description |
|---|---|
| type | Media file types, including images (parameter = "image"), voice (parameter = "voice"), videos (parameter = "video"), thumbnails (parameter = "thumb"), and articles (parameter = "news"). |
| errcode | Error code |
| errmsg | Error message |
| msg_id | Message sending task ID |
| msg_data_id | The data ID of the message. This field is displayed only when an article is to be broadcasted. As a part of the msgid field in the Article Summary API, it can be used to obtain the data of the appropriate article in the Article Summary API. For details, see the description of the msgid field in the Article Summary API. |
Note: A success response indicates the successful submission of a broadcast task rather than the completion of the task. Therefore, exceptions may still occur during the broadcasting process that cause users' failure to receive the message, such as message review and server instability. In addition, broadcast tasks generally take a long time to complete. Please be patient.
When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.
# Deleting Broadcasts (Available for Verified Subscription Accounts and Verified Service Accounts)
Broadcasted messages can be deleted via this API at any time.
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
POST data description
POST data example:
{
"msg_id":30124,
"article_idx":2
}
| Parameter | Required | Description |
|---|---|---|
| msg_id | Yes | ID of the broadcasted message |
| article_idx | No | The location of the article to be deleted in the multiple-article broadcast. The first article is numbered as 1, and so on. If this field is left empty or 0 is specified, all the articles will be deleted. |
Notes:
1. Only messages that have been successfully sent can be deleted.
2. Deleting a message means invalidating the details page of the message. Users who have received the message can still view the message card on their phone.
3. Only articles and video messages that have been broadcasted can be deleted.
4. If an article is broadcasted multiple times, deleting one broadcast will also delete the article and invalidate all the other broadcasts.
Response
Example of response data (The returned JSON packet for a successful request):
{
"errcode":0,
"errmsg":"ok"
}
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.
# Preview (Available for Verified Subscription Accounts and Verified Service Accounts)
Developers can use this API to send messages to specified users and view the style and typesetting of messages on their phone. To meet the needs of third-party platform developers, we've added a capability to send previews to designated Weixin IDs while keeping the capability to preview OpenIDs. However, this new capability can only be called 100 times per day, so use it as necessary.
API fequest format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN
POST data description
POST data example:
Article (use the media_id in the Broadcast by Tag API):
{
"touser":"OPENID",
"mpnews":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"mpnews"
}
Text:
{
"touser":"OPENID",
"text":{
"content":"CONTENT"
},
"msgtype":"text"
}
Voice (use the media_id in the Broadcast by Tag API):
{
"touser":"OPENID",
"voice":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"voice"
}
Image (use the media_id in the Broadcast by Tag API):
{
"touser":"OPENID",
"image":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"image"
}
Video (use the media_id in the Broadcast by Tag API):
{
"touser":"OPENID",
"mpvideo":{ "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",
},
"msgtype":"mpvideo"
}
Card/Coupon:
{ "touser":"OPENID",
"wxcard":{
"card_id":"123dsdajkasd231jhksad",
"card_ext": "{"code":"","openid":"","timestamp":"1402057159","signature":"017bb17407c8e0058a66d72dcc61632b70f511ad"}"
},
"msgtype":"wxcard"
}
Note: The touser field in the above JSON data can be changed to towxname, so that developers can preview by Weixin ID instead of OpenID. When towxname and touser are both specified, towxname is preferred. The JSON data after the field is changed is as follows (take article as an example): Article:
{
"towxname":"An example Weixin ID",
"mpnews":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"mpnews"
}
| Parameter | Description |
|---|---|
| touser | The OpenIDs of the users receiving the message in the Official Account. This field can be changed to towxname so as to preview Weixin IDs. |
| msgtype | Broadcast message types, including articles (parameter = "mpnews"), text (parameter = "text"), voices (parameter = "voice"), music (parameter = "music"), images (parameter = "image"), videos (parameter = "video"), and cards/coupons (parameter = "wxcard"). |
| media_id | The media_id of the message to be broadcasted |
| content | The content of the text message broadcasted |
Response
Example of response data (The returned JSON packet for a successful request):
{
"errcode":0,
"errmsg":"preview success",
"msg_id":34182
}
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| msg_id | Message ID |
# Querying Broadcast Message Sending Status (Available for Verified Subscription Accounts and Verified Service Accounts)
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN
POST data description
POST data example:
{
"msg_id": "201053012"
}
| Parameter | Description |
|---|---|
| msg_id | The message ID returned after a message is broadcasted |
Response
Example of response data (The returned JSON packet for a successful request):
{
"msg_id":201053012,
"msg_status":"SEND_SUCCESS"
}
| Parameter | Description |
|---|---|
| msg_id | The message ID returned after a message is broadcasted |
| msg_status | The message status. SEND_SUCCESS: Message sent; SENDING: Sending message; SEND_FAIL: Sending failed; DELETE: Message deleted. |
# Broadcast Result Event Push
As it takes some time to complete a submitted broadcast task, only a message indicating whether the broadcast task is submitted successfully will be given when the Broadcast API is called. If the task is submitted successfully, an event will be pushed to the URL (callback URL) entered by the developer on the Official Accounts Platform upon the completion of the task.
Note: Since a broadcast task takes a long time to complete, the broadcast result will be pushed when the task is about to be completed. For this reason, the pushed number of recipients may be different from the actual number.
The XML structure for a successful push is as follows, with the result of originality review being included:
<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>
| Parameter | Description |
|---|---|
| ToUserName | The Weixin ID of the Official Account |
| FromUserName | The Weixin ID of the Official Accounts broadcast assistant, which is mphelper. |
| CreateTime | Timestamp of the creation time |
| MsgType | Message type. It is event in this case. |
| Event | Event message. It is MASSSENDJOBFINISH in this case. |
| MsgID | ID of the message broadcasted |
| Status | Broadcast result. Possible values are "send success", "send fail", and "err(num)". However, when the status is "send success", some users may still fail to receive the broadcasted message due to their setting to reject Official Accounts messages or system errors. err(num) indicates the specific reason for review failure, including: err(10001), //Contained ads; err(20001), //Involved politics; err(20004), //Involved social issues; err(20002), //Contained lewd content; err(20006), //Suspected of violating laws and committing crimes; err(20008), //Suspected of fraud; err(20013), //Involved copyright issues; err(22000), //Suspected of mutual promotion; err(21000), //Suspected of other situations; err(30001) //System error occurred during the originality review and the user chose not to broadcast an article determined to be a repost; err(30002) //The originality review determined that the message could not be broadcasted; err(30003) //The originality review determined the article was reposted and the user chose not to broadcast an article determined to be a repost |
| TotalCount | The number of followers under the tag_id or in the openid_list |
| FilterCount | The number of followers to whom the message is to be sent after filtering (the filters include filtering by specific region, filtering by gender, filtering users who set to reject messages, and users who have received 4 messages). In principle, FilterCount = SentCount + ErrorCount. |
| SentCount | The number of followers who have received the message |
| ErrorCount | The number of followers who did not receive the message |
| ResultList | The review result of each single article |
| ArticleIdx | The serial number of the broadcasted article, starting from 1. |
| UserDeclareState | The article status declared by the user |
| AuditState | The article status from system review |
| OriginalArticleUrl | URL to the similar original article |
| OriginalArticleType | Type of the similar original article |
| CanReprint | Indicates whether repost is allowed |
| NeedReplaceContent | Indicates whether to use the original article instead |
| NeedShowReprintSource | Indicates whether to indicate the original author of the reposted article |
| CheckState | Final review result |
| CheckState | 1 - It is not determined to be reposted and can be broadcasted; 2 - It is determined to be reposted but can be broadcasted; 3 - It is determined to be reposted and cannot be broadcasted |
# Using the clientmsgid Parameter to Avoid Repeated Push
- The clientmsgid parameter is added in the Broadcast API for developers to set on their own to avoid repeated push.
Before a message is broadcasted, the Weixin backend will check the broadcast record within 24 hours, and reject the broadcast request and return the existing msgid if this clientmsgid exists. You can call the "Query Broadcast Message Sending Status" API to view the status of the broadcast message.
- New error codes
| Error Code | Description |
|---|---|
| 45065 | The clientmsgid already has a broadcast record. The returned data contains the msgid of the existing broadcast task. |
| 45066 | The clientmsgid retries too frequently. Retry after 1 minute. |
| 45067 | The length of the clientmsgid exceeds the limit. |
- API example and parameter description
{
"filter":{
"is_to_all":false,
"tag_id":2
},
"mpnews":{
"media_id":"123dsdajkasd231jhksad"
},
"msgtype":"mpnews",
"send_ignore_reprint":0,
"clientmsgid":"send_tag_2"
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| clientmsgid | No | The broadcast msgid on the developer side, which is limited to 64 bytes. If this is left empty, the backend will use the digest value of the broadcast scope and broadcast content as the clientmsgid value by default. |
Response
Response example in case of clientmsgid conflict: {
"errcode":45065,
"errmsg":"clientmsgid exist",
"msg_id":123456
}
# Controlling Broadcast Speed
Developers can use the speed limit API to control the broadcast speed.
Get broadcast speed
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/speed/get?access_token=ACCESS_TOKEN
Response description The result returned for a successful request:
{
"speed":3,
"realspeed":15
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| speed | Yes | Broadcast speed level |
| realspeed | Yes | The actual value of the broadcast speed (10000 users/minute) |
Set broadcast speed
API request format
HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/mass/speed/set?access_token=ACCESS_TOKEN
Request example
{
"speed":1
}
Parameters:
| Parameter | Required | Description |
|---|---|---|
| speed | Yes | Broadcast speed level |
The broadcast speed level is an integer from 0 to 4. A larger number means a lower speed.
The relationship between "speed" and "realspeed" is as follows:
| speed | realspeed |
|---|---|
| 0 | 800000 users/minute |
| 1 | 600000 users/minute |
| 2 | 450000 users/minute |
| 3 | 300000 users/minute |
| 4 | 100000 users/minute |
Error Codes
| Error Code | Description |
|---|---|
| 45083 | The "speed" parameter value is not within 0-4 |
| 45084 | The "speed" parameter is not set |