微信公眾平臺開發(89) 高階群發介面
在這篇微信公眾平臺高階介面開發教程中，我們將介紹如何使用介面實現微信公眾平臺群發功能。
本文分為以下四個部分：
- 準備群發內容
- 選擇群發物件
- 執行群發
- 接收群髮結果
一、準備群發內容
群發內容可以是文字、圖片、語音、視訊、圖文。群發文本只需要文字內容，其他內容需要獲得相應的media_id。
1. 文字內容
文字內容就是一段文字，比如："微信公眾平臺開發最佳實踐"
2. 圖片、語音、視訊
要求如下：
- 圖片（image）: 128K，支援JPG格式
- 語音（voice）：256K，播放長度不超過60s，支援AMR\MP3格式
- 視訊（video）：1MB，支援MP4格式
準備好以後，需要使用上傳下載多媒體檔案介面將其上傳到微信伺服器，獲得media_id。
上傳的開發方法，可以參考本部落格的第80篇教程 微信公眾平臺開發(80) 上傳下載多媒體檔案
3. 圖文
首先要準備縮圖，要求如下：
- 縮圖（thumb）：64KB，支援JPG格式
同樣的，使用上傳下載多媒體檔案介面，上傳到微信伺服器後，得到縮圖的media_id，
然後需要使用上傳圖文訊息素材介面將其上傳到微信伺服器，介面為
https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token=ACCESS_TOKEN
要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" }, { "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" } ] }
引數說明如下：
| 引數 | 是否必須 | 說明 |
|---|---|---|
| Articles | 是 | 圖文訊息，一個圖文訊息支援1到10條圖文 |
| thumb_media_id | 是 | 圖文訊息縮圖的media_id，可以在基礎支援-上傳多媒體檔案介面中獲得 |
| author | 否 | 圖文訊息的作者 |
| title | 是 | 圖文訊息的標題 |
| content_source_url | 否 | 在圖文訊息頁面點選“閱讀原文”後的頁面 |
| content | 是 | 圖文訊息頁面的內容，支援HTML標籤 |
| digest | 否 | 圖文訊息的描述 |
根據上述POST結構，定義圖文陣列如下：
上傳成功後，返回如下，將得到圖文訊息的media_id
{ "type":"news", "media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ", "created_at":1391857799 }
二、選擇群發物件
群發物件可以是使用者組，也可以是OpenID列表。
1.使用者組
獲得使用者分組，需要使用高階介面中的查詢所有分組介面，獲得相應的group_id，
開發方法，可以參考本部落格的第88篇教程 微信公眾平臺開發(88) 使用者分組介面
2.OpenID列表
OpenID列表，是使用高階介面中的獲取關注者列表介面來實現的。
開發方法，可以參考本部落格的第87篇教程 微信公眾平臺開發(87) 獲取關注者列表
三、執行群發
由於群發物件的不同，執行群發也有不同的方式。
1. 對使用者組群發
對使用者組群發的介面如下：
https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token=ACCESS_TOKEN
要POST的內容按內容不同組成也不一樣。
文字：
{ "filter":{ "group_id":"2" }, "text":{ "content":"CONTENT" }, "msgtype":"text" }
語音（注意此處media_id需通過基礎支援中的上傳下載多媒體檔案來得到）：
{ "filter":{ "group_id":"2" }, "voice":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"voice" }
圖片（注意此處media_id需通過基礎支援中的上傳下載多媒體檔案來得到）：
{ "filter":{ "group_id":"2" }, "image":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"image" }
視訊
{ "filter":{ "group_id":"2" }, "mpvideo":{ "media_id":"IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc", }, "msgtype":"mpvideo" }
圖文訊息（注意圖文訊息的media_id需要通過上述方法來得到）：
{ "filter":{ "group_id":"2" }, "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews" }
相關引數說明如下：
| 引數 | 是否必須 | 說明 |
|---|---|---|
| filter | 是 | 用於設定圖文訊息的接收者 |
| group_id | 是 | 群發到的分組的group_id |
| mpnews | 是 | 用於設定即將傳送的圖文訊息 |
| media_id | 是 | 用於群發的訊息的media_id |
| msgtype | 是 | 群發的訊息型別，圖文訊息為mpnews，文字訊息為text，語音為voice，音樂為music，圖片為image，視訊為video |
| title | 否 | 訊息的標題 |
| description | 否 | 訊息的描述 |
| thumb_media_id | 是 | 視訊縮圖的媒體ID |
其介面實現程式碼如下所示：
返回結果如下：
array(3) { ["errcode"]=> int(0) ["errmsg"]=> string(27) "send job submission success" ["msg_id"]=> float(2347614963) }
引數說明
| 引數 | 說明 |
|---|---|
| type | 媒體檔案型別，分別有圖片（image）、語音（voice）、視訊（video）和縮圖（thumb），圖文訊息為news |
| errcode | 錯誤碼 |
| errmsg | 錯誤資訊 |
| msg_id | 訊息ID |
下面是向用戶組傳送圖文訊息的效果，分別是接收到圖文訊息，檢視圖文訊息內容後的效果，
2.對OpenID列表群發
介面如下：
https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN
POST資料示例如下：
文字：
{ "touser": [ "oR5Gjjl_eiZoUpGozMo7dbBJ362A", "oR5Gjjo5rXlMUocSEXKT7Q5RQ63Q" ], "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" }
視訊：
{ "touser":[ "OPENID1", "OPENID2" ], "video":{ "media_id":"123dsdajkasd231jhksad", "title":"TITLE", "description":"DESCRIPTION" }, "msgtype":"video" }
圖文訊息（注意圖文訊息的media_id需要通過上述方法來得到）：
{ "touser":[ "OPENID1", "OPENID2" ], "mpnews":{ "media_id":"123dsdajkasd231jhksad" }, "msgtype":"mpnews" }
引數列表
| 引數 | 是否必須 | 說明 |
|---|---|---|
| touser | 是 | 填寫圖文訊息的接收者，一串OpenID列表，OpenID最少個，最多10000個 |
| mpnews | 是 | 用於設定即將傳送的圖文訊息 |
| media_id | 是 | 用於群發的圖文訊息的media_id |
| msgtype | 是 | 群發的訊息型別，圖文訊息為mpnews，文字訊息為text，語音為voice，音樂為music，圖片為image，視訊為video |
| title | 否 | 訊息的標題 |
| description | 否 | 訊息的描述 |
| thumb_media_id | 是 | 視訊縮圖的媒體ID |
返回資料示例（正確時的JSON返回結果）：
{ "errcode":0, "errmsg":"send job submission success", "msg_id":2347614964 }
四、接收群髮結果
1. 設定公眾號助手
為了能接收群髮結果，需要設定公眾號助手，結果將推送到繫結的個人微信賬號上。其設定如下
2. 接收結果事件
群發任務提交後，群發任務可能在一定時間後才完成，因此，群發介面呼叫時，僅會給出群發任務是否提交成功的提示，若群發任務提交成功，則在群發任務結束時，會向開發者在公眾平臺填寫的開發者URL（callback URL）推送事件。
推送的XML結構如下（傳送成功時）：
<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>
| 引數 | 說明 |
|---|---|
| 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 | group_id下粉絲數；或者openid_list中的粉絲數 |
| FilterCount | 過濾（過濾是指特定地區、性別的過濾、使用者設定拒收的過濾，使用者接收已超4條的過濾）後，準備傳送的粉絲數，原則上，FilterCount = SentCount + ErrorCount |
| SentCount | 傳送成功的粉絲數 |
| ErrorCount | 傳送失敗的粉絲數 |
從上可以看出，這其實是公眾號群發助手模擬向公眾號傳送訊息，那麼群髮結果也是返回給公眾號助手。
在微信公眾平臺PHP SDK中增加該事件訊息的處理結果如下：
private function receiveEvent($object) { $content = ""; switch ($object->Event) { case "subscribe": $content = "歡迎關注方倍工作室"; break; case "MASSSENDJOBFINISH": $content = "訊息ID：".$object->MsgID. "\n結果：".$object->Status. "\n粉絲數：".$object->TotalCount. "\n過濾：".$object->FilterCount. "\n傳送成功：".$object->SentCount. "\n傳送失敗：".$object->ErrorCount; break; default: break; } $result = $this->transmitText($object, $content); return $result; }