一、為什麼要用自定義菜單
只有一個輸入框的對話頁面,操作起來太像命令列。自定義菜單把常用功能搬到畫面下方,點一下就有效果,更貼近一般使用者的習慣。它不只支援事件回應,也能直接跳轉 URL,遇到比較複雜的功能,跳去自家網頁處理即可。
請注意:自定義菜單只有服務號具備。
access_token 是公眾號呼叫各介面時的全域唯一憑證,正常有效期為 7200 秒,重複取得會讓先前那次失效。用 AppID 與 AppSecret 呼叫下列介面即可取得,所有微信介面都必須走 https。
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
參數:grant_type 固定填 client_credential;appid 為第三方使用者唯一憑證;secret 為對應密鑰。
成功回傳:
{"access_token":"ACCESS_TOKEN","expires_in":7200}其中 expires_in 是有效秒數。失敗則回傳錯誤碼,例如 AppID 無效:
{"errcode":40013,"errmsg":"invalid appid"}
目前最多 3 個一級菜單,每個一級菜單最多 5 個二級菜單;一級菜單文字上限 4 個漢字,二級菜單 7 個漢字,超出會以「...」顯示。由於微信客戶端有快取,建立後約需 24 小時才會顯示,測試時可以取消關注再重新關注來立即查看。
按鈕有兩種行為類型:
click:使用者點擊後,微信伺服器會推送一個 event 類型的訊息給開發者,並帶上你自訂的 key,之後就能依 key 做互動。
view:點擊後微信直接開啟按鈕上填寫的網址,適合搭配網頁授權取得使用者資料。
POST https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
{
"button": [
{ "type": "click", "name": "今日歌曲", "key": "V1001_TODAY_MUSIC" },
{ "type": "click", "name": "歌手簡介", "key": "V1001_TODAY_SINGER" },
{
"name": "菜單",
"sub_button": [
{ "type": "view", "name": "搜索", "url": "https://www.soso.com/" },
{ "type": "view", "name": "視頻", "url": "https://v.qq.com/" },
{ "type": "click", "name": "贊一下我們", "key": "V1001_GOOD" }
]
}
]
}參數說明:
button(必填):一級菜單陣列,1~3 個。sub_button(選填):二級菜單陣列,1~5 個。type(必填):click 或 view。name(必填):菜單標題,一級不超過 4 個漢字、二級不超過 7 個漢字。key(click 必填):事件 KEY,不超過 128 位元組。url(view 必填):網頁連結,不超過 256 位元組。成功回傳 {"errcode":0,"errmsg":"ok"};菜單名長度不合法則回傳 {"errcode":40018,"errmsg":"invalid button name size"}。
GET https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN
回傳的 JSON 結構與建立時一致,每個節點都會帶一個 sub_button 陣列。
GET https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN
使用者點擊後,若按鈕是 click 類型,微信會推送事件;view 類型的點擊不會上報。
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[FromUser]]></FromUserName> <CreateTime>123456789</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[CLICK]]></Event> <EventKey><![CDATA[EVENTKEY]]></EventKey> </xml>
EventKey 就是菜單裡設定的 KEY,靠它決定要回覆什麼。
延續上一篇的機器人專案,這次加上菜單功能。
在開發者模式中可以看到並重置 AppID 與 AppSecret。由於 token 有期限,實作時必須自行判斷過期:
private static DateTime GetAccessToken_Time;
private static int Expires_Period = 7200; // 預設 7200 秒
private static string mAccessToken;
public static string AccessToken {
get {
if (string.IsNullOrEmpty(mAccessToken) || HasExpired()) {
mAccessToken = GetAccessToken(AppID, AppSecret);
}
return mAccessToken;
}
}
private static string GetAccessToken(string appId, string appSecret) {
string url = string.Format(
"https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid={0}&secret={1}",
appId, appSecret);
string result = HttpUtility.GetData(url);
XDocument doc = XmlUtility.ParseJson(result, "root");
XElement root = doc.Root;
if (root != null) {
XElement token = root.Element("access_token");
if (token != null) {
GetAccessToken_Time = DateTime.Now;
if (root.Element("expires_in") != null) {
Expires_Period = int.Parse(root.Element("expires_in").Value);
}
return token.Value;
}
GetAccessToken_Time = DateTime.MinValue;
}
return null;
}
private static bool HasExpired() {
// 預留一分鐘誤差,避免邊緣時間失效
if (GetAccessToken_Time != DateTime.MinValue) {
if (DateTime.Now > GetAccessToken_Time.AddSeconds(Expires_Period).AddSeconds(-60)) {
return true;
}
}
return false;
}把常見城市做成點擊查詢,另外放一組 view 類型的外連做示範:
{
"button": [
{
"name": "鏈接",
"sub_button": [
{ "type": "view", "name": "搜索", "url": "https://www.baidu.com/" },
{ "type": "view", "name": "視頻", "url": "https://v.qq.com/" },
{ "type": "click", "name": "贊一下我們", "key": "BTN_GOOD" }
]
},
{
"name": "查詢天氣",
"sub_button": [
{ "type": "click", "name": "武漢", "key": "BTN_TQ_WUHAN" },
{ "type": "click", "name": "上海", "key": "BTN_TQ_SHANGHAI" },
{ "type": "click", "name": "北京", "key": "BTN_TQ_BEIJING" }
]
},
{ "type": "click", "name": "幫助", "key": "BTN_HELP" }
]
}菜單變動不頻繁,把 JSON 放在 txt 檔裡,再寫一個管理頁做四件事:從檔案載入、建立(推送並更新到微信伺服器)、查詢、刪除。
public class MenuManager {
private static readonly string Menu_Data_Path =
System.AppDomain.CurrentDomain.BaseDirectory + "/Data/menu.txt";
public static string GetMenu() {
string url = string.Format(
"https://api.weixin.qq.com/cgi-bin/menu/get?access_token={0}", Context.AccessToken);
return HttpUtility.GetData(url);
}
public static void CreateMenu(string menu) {
string url = string.Format(
"https://api.weixin.qq.com/cgi-bin/menu/create?access_token={0}", Context.AccessToken);
HttpUtility.SendHttpRequest(url, menu);
}
public static void DeleteMenu() {
string url = string.Format(
"https://api.weixin.qq.com/cgi-bin/menu/delete?access_token={0}", Context.AccessToken);
HttpUtility.GetData(url);
}
public static string LoadMenu() {
return FileUtility.Read(Menu_Data_Path);
}
}GET 與 POST 的細節都封裝在 HttpUtility 裡,正式環境建議再補上重試與逾時處理:
class HttpUtility {
public static string SendHttpRequest(string url, string data) {
return SendPostHttpRequest(url, "application/x-www-form-urlencoded", data);
}
public static string GetData(string url) {
return SendGetHttpRequest(url, "application/x-www-form-urlencoded");
}
public static string SendPostHttpRequest(string url, string contentType, string requestData) {
WebRequest request = HttpWebRequest.Create(url);
request.Method = "POST";
request.ContentType = contentType;
byte[] postBytes = Encoding.UTF8.GetBytes(requestData);
request.ContentLength = postBytes.Length;
using (Stream outstream = request.GetRequestStream()) {
outstream.Write(postBytes, 0, postBytes.Length);
}
string result = string.Empty;
using (WebResponse response = request.GetResponse()) {
if (response != null) {
using (Stream stream = response.GetResponseStream())
using (StreamReader reader = new StreamReader(stream, Encoding.UTF8)) {
result = reader.ReadToEnd();
}
}
}
return result;
}
public static string SendGetHttpRequest(string url, string contentType) {
WebRequest request = HttpWebRequest.Create(url);
request.Method = "GET";
request.ContentType = contentType;
string result = string.Empty;
using (WebResponse response = request.GetResponse()) {
if (response != null) {
using (Stream stream = response.GetResponseStream())
using (StreamReader reader = new StreamReader(stream, Encoding.UTF8)) {
result = reader.ReadToEnd();
}
}
}
return result;
}
}
class XmlUtility {
// 把 JSON 轉成 XDocument,方便用 XPath 取值
public static XDocument ParseJson(string json, string rootName) {
return JsonConvert.DeserializeXNode(json, rootName);
}
}view 類型會自動跳轉,不需處理;需要處理的是點擊事件:贊一下、查詢三個城市的天氣、幫助。沿用上一章的事件處理器擴充即可:
class EventHandler : IHandler {
private string RequestXml { get; set; }
public EventHandler(string requestXml) {
this.RequestXml = requestXml;
}
public string HandleRequest() {
string response = string.Empty;
EventMessage em = EventMessage.LoadFromXml(RequestXml);
if (em != null) {
switch (em.Event.ToLower()) {
case "subscribe":
response = SubscribeEventHandler(em);
break;
case "click":
response = ClickEventHandler(em);
break;
}
}
return response;
}
private string SubscribeEventHandler(EventMessage em) {
TextMessage tm = new TextMessage();
tm.ToUserName = em.FromUserName;
tm.FromUserName = em.ToUserName;
tm.CreateTime = Common.GetNowTime();
tm.Content = "歡迎您關注***,我是大哥大,有事就問我,呵呵!\n\n";
return tm.GenerateContent();
}
private string ClickEventHandler(EventMessage em) {
string result = string.Empty;
if (em != null && em.EventKey != null) {
switch (em.EventKey.ToUpper()) {
case "BTN_GOOD":
result = btnGoodClick(em);
break;
case "BTN_TQ_BEIJING":
result = searchWeather("beijing", em);
break;
case "BTN_TQ_SHANGHAI":
result = searchWeather("shanghai", em);
break;
case "BTN_TQ_WUHAN":
result = searchWeather("wuhan", em);
break;
case "BTN_HELP":
result = btnHelpClick(em);
break;
}
}
return result;
}
private string btnGoodClick(EventMessage em) {
TextMessage tm = new TextMessage();
tm.ToUserName = em.FromUserName;
tm.FromUserName = em.ToUserName;
tm.CreateTime = Common.GetNowTime();
tm.Content = @"謝謝您的支持!";
return tm.GenerateContent();
}
private string btnHelpClick(EventMessage em) {
TextMessage tm = new TextMessage();
tm.ToUserName = em.FromUserName;
tm.FromUserName = em.ToUserName;
tm.CreateTime = Common.GetNowTime();
tm.Content = @"查詢天氣,輸入 tq 城市名稱\拼音\首字母";
return tm.GenerateContent();
}
private string searchWeather(string cityName, EventMessage em) {
TextMessage tm = new TextMessage();
tm.Content = WeatherHelper.GetWeather(cityName);
tm.ToUserName = em.FromUserName; // 發送者與接收者對調
tm.FromUserName = em.ToUserName;
tm.CreateTime = Common.GetNowTime();
return tm.GenerateContent();
}
}
以上即為本篇全部內容,希望對你的開發有所幫助。