在這篇微信公衆平臺高級接口開發教程中我們將介紹如何使用接口實現微信公衆平臺羣發功能。
本文分爲以下四個部分
準備羣發內容
選擇羣發對象
執行羣發
接收羣髮結果
一、準備羣發內容
羣發內容可以是文本、圖片、語音、視頻、圖文。羣發文本只需要文本內容其他內容需要獲得相應的media_id。
1. 文本內容
文本內容就是一段文字比如"微信公衆平臺開發最佳實踐"
2. 圖片、語音、視頻
要求如下
圖片image: 128K支持JPG格式
語音voice256K播放長度不超過60s支持AMR\MP3格式
視頻video1MB支持MP4格式
準備好以後需要使用上傳下載多媒體文件接口將其上傳到微信服務器獲得media_id。
上傳的開發方法可以參考本博客的第80篇教程 微信公衆平臺開發(80) 上傳下載多媒體文件
3. 圖文
首先要準備縮略圖要求如下
縮略圖thumb64KB支持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. 接收結果事件
羣發任務提交後羣發任務可能在一定時間後才完成因此羣發接口調用時僅會給出羣發任務是否提交成功的提示若羣發任務提交成功則在羣發任務結束時會向開發者在公衆平臺填寫的開發者URLcallback 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;
}