高階群發介面
高階群發介面
在公眾平台網站上，為訂閱號碼提供了每天一條的群發權限，為服務號碼提供每月（自然月）4條的群發權限。而對於某些具備開發能力的公眾號運營者，可以透過高級群發接口，實現更靈活的群發能力。
請注意：
1、对于认证订阅号，群发接口每天可成功调用1次，此次群发可选择发送给全部用户或某个标签； 2、对于认证服务号虽然开发者使用高级群发接口的每日调用限制为100次，但是用户每月只能接收4条，无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败； 3、具备微信支付权限的公众号，在使用群发接口上传、群发图文消息类型时，可使用<a>标签加入外链； 4、开发者可以使用预览接口校对消息样式和排版，通过预览接口可发送编辑好的消息给指定用户校验效果。
群發圖文訊息的過程如下：
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条群发进入历史消息列表。 3、类似地，服务号在一个月内，使用is_to_all为true群发的次数，加上公众平台官网群发（不管本次群发是对全体还是对某个分组）的次数，最多只能是4次。 4、设置is_to_all为false时是可以多次群发的，但每个用户只会收到最多4条，且这些群发不会进入历史消息列表。
另外，請開發者註意，本介面中所有使用到media_id的地方，現在都可以使用素材管理中的永久素材media_id了。 請但注意，使用同一個素材群發出去的連結是一樣的，這意味著，刪除某一次群發，會導致整個連結失效。
已上傳圖文訊息內的圖片取得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"
參數說明
| 參數 | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 呼叫介面憑證 |
| media | 是 | form-data中媒體檔案標識，有filename、filelength、content-type等資訊 |
回傳說明 正常情況下的回傳結果為：
{
"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
}
]
}| 參數 | 是否必須 | 說明 |
|---|---|---|
| Articles | ##是#圖文訊息，一個圖文訊息支援1到8條圖文 | |
| 是 | 圖文訊息縮略圖的media_id，可以在基礎支援-上傳多媒體檔案介面中獲得 | |
| #否 | 圖文訊息的作者 | |
| 是 | 圖文訊息的標題 | |
| ################ ###在圖文訊息頁面點選「閱讀原文」後的頁面，受安全限制，如需跳轉Appstore，可以使用itun.es或appsto.re的短鏈服務，並在短鏈後增加#wechat_redirect 後綴。 ############content######是######圖文訊息頁面的內容，支援HTML標籤。具備微信支付權限的公眾號，可以使用a標籤，其他公眾號不能使用 | ||
| #digest | #否 | ##圖文訊息的描述|
| #否 | 是否顯示封面，1為顯示，0為不顯示 |
傳回說明
傳回資料範例（正確時的JSON回傳結果）：{
"type":"news",
"media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",
"created_at":1391857799
}| 說明 | ||
|---|---|---|
| 媒體檔案類型，分別有圖片（image）、語音（voice）、視訊（video）和縮圖（thumb），圖文訊息（news） | ||
| 媒體檔案/圖文訊息上傳後取得的唯一識別 | ||
| 媒體檔案上傳時間 |
| 參數 | 是否必須 | 說明 |
|---|---|---|
| filter | 是 | 用於設定圖文訊息的接收者 |
| is_to_all | #否 | #用於設定是否向全部使用者發送，值為true或false，選擇true該訊息群發給所有用戶，選擇false可依tag_id傳送給指定群組的用戶 |
| tag_id | 否 | 群發到的標籤的tag_id，參加用戶管理中用戶分組接口，若is_to_all值為true，可不填入tag_id |
| mpnews | #是 | 用來設定即將發送的圖文訊息 |
| media_id | #是 | 用於群發的訊息的media_id |
| msgtype | 是 | 群發的訊息類型，圖文訊息為mpnews，文字訊息為text，語音為voice，音樂為music，圖片為image，影片為video，卡券為wxcard |
| title | 否 | 訊息的標題 |
| 否 | 訊息的描述 | |
| 是 | 影片縮圖的媒體ID |
| 參數 | 說明 | |
|---|---|---|
| type | 媒體檔案類型，分別有圖片（image）、語音（voice）、視訊（video）和縮圖（thumb），圖文訊息為news | |
| errcode | 錯誤碼 | |
| #errmsg | ##錯誤訊息||
| 訊息傳送任務的ID | ||
| 訊息的資料ID，該欄位只有在群發圖文消息時，才會出現。可用於在圖文分析資料介面中，取得對應的圖文訊息的數據，是圖文分析資料介面中的msgid欄位中的前半部分，詳見圖文分析資料介面中的msgid欄位的介紹。 |
| 参数 | 是否必须 | 说明 |
|---|---|---|
| touser | 是 | 填写图文消息的接收者，一串OpenID列表，OpenID最少2个，最多10000个 |
| mpnews | 是 | 用于设定即将发送的图文消息 |
| media_id | 是 | 用于群发的图文消息的media_id |
| msgtype | 是 | 群發的訊息類型，圖文訊息為mpnews，文字訊息為text，語音為voice，音樂為music，圖片為image，影片為video，卡券為wxcard |
| title | 否 | 訊息的標題 |
| 否 | 訊息的描述 | |
| 是 | 影片縮圖的媒體ID |
| 参数 | 说明 |
|---|---|
| type | 媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息 |
| errcode | 错误码 |
| errmsg | 错误信息 |
| msg_id | 消息发送任务的ID |
| msg_data_id | 消息的数据ID，，该字段只有在群发图文消息时，才会出现。可以用于在图文分析数据接口中，获取到对应的图文消息的数据，是图文分析数据接口中的msgid字段中的前半部分，详见图文分析数据接口中的msgid字段的介绍。 |
請注意：在返回成功時，意味著群發任務提交成功，並不意味著此時群發已經結束，所以，仍有可能在後續的發送過程中出現異常情況導致用戶未收到訊息，如訊息有時會進行審核、伺服器不穩定等。此外，群發任務一般需要較長的時間才能全部發送完畢，請耐心等待。
錯誤時微信會傳回錯誤碼等訊息，請根據錯誤碼查詢錯誤訊息
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
POST資料說明
POST資料範例如下：
{
"msg_id":30124
}| 参数 | 是否必须 | 说明 |
|---|---|---|
| msg_id | 是 | 发送出去的消息ID |
請注意：
1、只有已经发送成功的消息才能删除 2、删除消息是将消息的图文详情页失效，已经收到的用户，还是能在其本地看到消息卡片。 3、删除群发消息只能删除图文消息和视频消息，其他类型的消息一经发送，无法删除。 4、如果多次群发发送的是一个图文消息，那么删除其中一次群发，就会删除掉这个图文消息也，导致所有群发都失效
回傳說明
傳回資料範例（正確時的JSON回傳結果）：
{
"errcode":0,
"errmsg":"ok"
}| 參數 | 說明 |
|---|---|
| errcode | #錯誤碼 |
| 錯誤訊息 |
| 參數 | 說明 |
|---|---|
| #touser | 接收訊息使用者對應該是公眾號碼的openid，此欄位也可以改為towxname，以實現對微訊號的預覽 |
| msgtype | 群發的訊息類型，圖文訊息為mpnews，文字訊息為text，語音為voice，音樂為music，圖片為image，影片為video，卡券為wxcard |
| media_id | 用於群發的訊息的media_id |
| content | 傳送文字訊息時文字的內容 |
傳回說明
傳回資料範例（正確時的JSON回傳結果）：
{
"errcode":0,
"errmsg":"preview success",
"msg_id":34182
}| 參數 | 說明 |
|---|---|
| errcode | #錯誤碼 |
| errmsg | 錯誤訊息 |
| msg_id | 訊息ID |
查询群发消息发送状态【订阅号与服务号认证后均可用】
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/message/mass/get?access_token=ACCESS_TOKEN
POST資料說明
POST資料範例如下：
{
"msg_id": "201053012"
}| 參數 | 說明 |
|---|---|
| #msg_id | 群發訊息後傳回的訊息id |
#回傳說明
傳回資料範例（正確時的JSON回傳結果）：
{
"msg_id":201053012,
"msg_status":"SEND_SUCCESS"
}| 參數 | 說明 |
|---|---|
| msg_id | #群組發送訊息後傳回的訊息id |
| 訊息傳送後的狀態，SEND_SUCCESS表示傳送成功 |
| 參數 | 說明 |
|---|---|
| #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 ), //涉嫌其他 |
| TotalCount | tag_id下粉絲數；或是openid_list中的粉絲數 |
| FilterCount | #。 （過濾是指特定地區、性別的過濾、用戶設定拒收的過濾，用戶接收已超4條的過濾）後，準備發送的粉絲數，原則上，FilterCount = SentCount ErrorCount |
| #SentCount | 發送成功的粉絲數 |
| ErrorCount | 發送失敗的粉絲數 |
