Advanced Broadcast Interface
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

On the WeChat Official Account Platform, a subscription account is allowed to send 1 broadcast message per day, while a service account is allowed 4 per calendar month. Official accounts using developer mode can broadcast more flexibly using this API.

Notes:

1. A subscription account is allowed to send a single broadcast message per day to all users or users of a group.
2. A service account is allowed to send up to 100 broadcast messages per day, but users will receive only four messages per calendar month. This limitation applies to all broadcast messages, whether they are sent via the WeChat Official Account Admin Platform or via the broadcast API. Messages which exceed this limit will not be received by users.
3. Official accounts having payment access can add external links via the <a> tag if they send or broadcast rich media files via the broadcast API.
4. Developers can send messages to specified users via the preview API in order to test for message design and performance.

Contents

Upload Article Message Data

Request Description

HTTP request mode: POST
https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN

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

Parameter Required Description
Articles Yes One article message can support 1-10 news items
thumb_media_id Yes The Media ID for the article message's thumbnail. See also Basic Support->Transferring Multimedia Files
author No The author of an article message
title Yes The title of an article message
content_source_url No Switch to this page after clicking Original Text
content Yes The content of the corresponding article message page. Supports HTML tags.
digest No The description of the article message
show_cover_pic No Shows the cover picture when set to 1, hides if 0.

Result

Example of a result when the broadcast operation is successful:

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

Parameter Description
type Media file types is one of: image, voice, video and thumb. The type for an article message is news.
media_id The media ID obtained from uploading any media files/article messages
created_at Upload time of a media file

WeChat returns information about errors when they occur. Refer to the error codes listed here: Return Codes

Group-Based Broadcast

Request

http request mode: POST
https://api.wechat.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN

POST Data

Example:

Article message(Please note that media_id of an article message is obtained by using the above method):

{
   "filter":{
      "group_id":"2"
   },
   "mpnews":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"mpnews"
}

Text:

{
   "filter":{
      "group_id":"2"
   },
   "text":{
      "content":"CONTENT"
   },
    "msgtype":"text"
}

Voice(Please note that media_id here is obtained on Basic Support->Transferring Multimedia Files):

{
   "filter":{
      "group_id":"2"
   },
   "voice":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"voice"
}

Image(Please note that media_id here is obtained on Basic Support->Transferring Multimedia Files):

{
   "filter":{
      "group_id":"2"
   },
   "image":{
      "media_id":"123dsdajkasd231jhksad"
   },
    "msgtype":"image"
}

Video Please note that media_id here is obtained at the following URL: https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN POST data is as follows(See Basic Support->Transferring Multimedia Files):

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

The result will be something like this:

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

After that, POST the following data(change media_id here to the one obtained from the previous step):

{
   "filter":{
      "group_id":"2"
   },
   "mpvideo":{
      "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",
   },
    "msgtype":"mpvideo"
}

Parameter Required Description
filter Yes Set the recipient of an article message
group_id Yes ID of any groups to be broadcast to
mpnews Yes Set article messages to be sent
media_id Yes ID of the message to be broadcast
msgtype Yes Indicate the broadcast message types. mpnews for article messages, text for text message, voice for voice messages, music for music messages, image for image messages, and video for video messages.
title No The title of the message
description No The description of the message
thumb_media_id Yes Media ID of the video's thumbnail image


Result

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

Example (successful result):

Parameter Description
type Media file type includes image, voice, video and thumb. The type of an article message is news.
errcode The error code
errmsg The error message
msg_id Message ID

Note: When the result is successful, this only indicates that the message was successfully submitted. The subsequent broadcast step -- which may take considerable time -- has not yet finished. Exceptions that occur later during the broadcast step may result in users' failure to receive your messages. This could be because the messages are under review or due to server issues.

WeChat returns information about errors when they occur. Refer to the error codes listed here: Return Codes

OpenID List-Based Broadcast

Request

http request mode: POST
https://api.wechat.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN

POST Data

Example:

Article message(Please note that the media_id of an article message is obtained using the above method):

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

Text:

{
   "touser": [
     "oR5Gjjl_eiZoUpGozMo7dbBJ362A", 
     "oR5Gjjo5rXlMUocSEXKT7Q5RQ63Q" 
   ], 
   "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:

Please note that media_id here is obtained via POST rerquest to the following URL: https://file.api.weixin.qq.com/cgi-bin/media/uploadvideo?access_token=ACCESS_TOKEN POST data is as follows(Please note that media_id here is obtained on Basic Support->Transferring Multimedia Files):

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


Return data will be:

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

Then, POST the following data(change media_id to the one obtained in the previous step) and send

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


Parameter Required Description
touser Yes Set a recipient of the article message. The range of OpenID ranges from 1 to 10000.
mpnews Yes Set article messages to be sent soon
media_id Yes Media ID of the article messages to be broadcast
msgtype Yes Media ID of the messages to be broadcast
msgtype Yes Indicate broadcast message type, which will be one of: mpnews (for article messages),text,voice,music,image, or video.
title No The tittle of a message
description No The description of a message
thumb_media_id Yes Media ID of a video thumb

Return Data

Example of Return Data(JSON return result when performed correctly):

{
  "errcode":0,
  "errmsg":"send job submission success",
  "msg_id":34182
}
Parameter Description
type Media file types include image, voice, video and thumb. The type of an article message is news.
errcode Error code
errmsg Error message
msg_id Message ID

Note: When the result is successful, this only indicates that the message was successfully submitted. The subsequent broadcast step -- which may take considerable time -- has not yet finished. Exceptions that occur later during the broadcast step may result in users' failure to receive your messages. This could be because the messages are under review or due to server issues.

WeChat returns information about errors when they occur. Refer to the error codes listed here: Return Codes

Broadcast Message Deletion

Request

http request mode: POST
https://api.wechat.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN

POST Data

Example:

{
   "msgid":30124
}


Parameter Required Description
msg_id Yes ID of messages sent

Notes: Messages can be deleted after they've been successfully sent. Users will still be able to view the message, even if the article's message page has been taken down. Only article and video messages may be deleted once sent.

Return Data

Example of Return Data(JSON return result when performed correctly):

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


Parameter Description
errcode Error code
errmsg Error message

WeChat returns information about errors when they occur. Refer to the error codes listed here: Return Codes

Preview API

Developers can send messages to specified users via this API in order to test for message design and performance.

Request Description

HTTP request method: POST
https://api.wechat.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN

POST Data

Example:

Article (media_id is identical to the one contained in the subsequent a group-targeted broadcast message):

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

Text:

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

Voice (media_id is identical to the one contained in the subsequent group-targeted broadcast message):

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

Image (media_id is identical to the one contained in the subsequent group-targeted broadcast message): {

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

Video (media_id is identical to the one contained in the subsequent group-targeted broadcast message):

{
    "touser":"OPENID",
    "mpvideo":{  "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc",   
    },
    "msgtype":"mpvideo" 
}
Parameter Description
touser OpenID of the message receiver visible by the official account
msgtype Type of broadcast message: mpnews (for rich media article groups or single article messages), text, voice, music, image, or video
media_id media_id of the broadcast message
content Content of text messages when sending broadcast messages of "text" type

Return Description An example of a successful JSON response is as follows:

{
   "errcode":0,
   "errmsg":"send job submission success",
   "msg_id":34182
}
Parameter Description
errcode Error code
errmsg Error description
media_id Message ID

Query Message Sending Status

Request Description

HTTP request method: POST
https://api.wechat.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN

POST Data

Example:

{
   "msg_id": "201053012"
}
Parameter Description
msg_id Message ID returned after a message is broadcast

Return Description

An example of a successful JSON response is as follows:

{
    "msg_id":201053012,
    "msg_status":"SEND_SUCCESS"
}
Parameter Description
msg_id Message ID returned after a message is broadcast
msg_status Status after a message is sent. SEND_SUCCESS indicates message has been successfully sent

Event Push Broadcast Result

A broadcast task may be completed within a certain time after submission. Therefore, when broadcast interface is called, only a tip about submission status is displayed. If a broadcast task is submitted successfully, an event push is sent to developer's URL (callback URL) registered on OA after the broadcast task is completed.

The XML structure of this event push is as follows (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>
Parameter Description
ToUserName WeChat ID of an official account
FromUserName WeChat ID of Official Account Broadcast Messages is mphelper
CreateTime Timestamp of create time
MsgType Message type, event in this case.
Event Event information. It is MASSSENDJOBFINISH in this case.
MsgID Broadcast message ID
Status Broadcast status is send success, send fail or err(num). When it is send success, however, it may be the case that some users failed to receive OA messages due to their settings or due to system errors. err(num) indicates the specific reason for the failure, which may be one of the following:

err(10001), //Advertising err(20001), //Politically sensitive info err(20004), //Socially sensitive info err(20002), //Porn err(20006), //Violation and crime err(20008), //Scam err(20013), //Copyright infringement err(22000), //Mutual publicity err(21000), //Others

TotalCount Number of followers in group_id; or number of followers in openid_list
FilterCount The number of followers who are prepared to broadcast after filtering(The filtering is an operation of screening specified regions, gender, users who set the broadcast rejection function. In theory, FilterCount = SentCount + ErrorCount
SentCount Number of followers who broadcast successfully
ErrorCount Number of followers who failed to broadcast
Developer Guide
Custom-defined Menu
WeChat JS-SDK