Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十一）：高階介面說明

SZW發表於2014-06-02

這裡所說的高階介面是指面向通過認證的服務號開通的高階功能。

高階功能大致可以分類為：

使用者介面
分組介面
客服介面（有別於之前介紹的多客服）
群發介面
多媒體介面
二維碼介面
模板訊息介面（不是所有賬號都可開通）
OAuth2.0（相對比較複雜，後面會有專門介紹）

　　以上所有的介面都包含在Senparc.Weixin.MP.AdvancedAPIs名稱空間下。

一些共同的操作

　　幾乎所有的高階介面都需要用到AccessToken來通訊（注意，下面如果沒有特殊說明的介面都需要這個AccessToken，但並非所有），因此多數會有一個AccessToken引數傳入，有關AccessToken獲取和操作的方式見Senparc.Weixin.MP SDK 微信公眾平臺開發教程（八）：通用介面說明。

使用者介面

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/User

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    //介面詳見：http://mp.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E7%94%A8%E6%88%B7%E5%9F%BA%E6%9C%AC%E4%BF%A1%E6%81%AF
    
    /// <summary>
    /// 使用者介面
    /// </summary>
    public static class User
    {
        /// <summary>
        /// 獲取使用者資訊
        /// </summary>
        /// <param name="accessToken">呼叫介面憑證</param>
        /// <param name="openId">普通使用者的標識，對當前公眾號唯一</param>
        /// <param name="lang">返回國家地區語言版本，zh_CN 簡體，zh_TW 繁體，en 英語</param>
        /// <returns></returns>
        public static UserInfoJson Info(string accessToken, string openId, Language lang = Language.zh_CN)
        {
            string url = string.Format("https://api.weixin.qq.com/cgi-bin/user/info?access_token={0}&openid={1}&lang={2}",
                accessToken, openId, lang.ToString());
            return HttpUtility.Get.GetJson<UserInfoJson>(url);

            //錯誤時微信會返回錯誤碼等資訊，JSON資料包示例如下（該示例為AppID無效錯誤）:
            //{"errcode":40013,"errmsg":"invalid appid"}
        }

        /// <summary>
        /// 獲取關注著OpenId資訊
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="nextOpenId"></param>
        /// <returns></returns>
        public static OpenIdResultJson Get(string accessToken, string nextOpenId)
        {
            string url = string.Format("https://api.weixin.qq.com/cgi-bin/user/get?access_token={0}",
                accessToken);
            if (!string.IsNullOrEmpty(nextOpenId))
            {
                url += "&next_openid=" + nextOpenId;
            }
            return HttpUtility.Get.GetJson<OpenIdResultJson>(url);
        }
    }
}

分組介面

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/Groups

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    /// <summary>
    /// 使用者組介面
    /// </summary>
    public static class Groups
    {

        /// <summary>
        /// 建立分組
        /// </summary>
        /// <returns></returns>
        public static CreateGroupResult Create(string accessToken, string name)
        {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/groups/create?access_token={0}";
            var data = new
            {
                group = new
                {
                    name = name
                }
            };
            return CommonJsonSend.Send<CreateGroupResult>(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 傳送文字資訊
        /// </summary>
        /// <param name="accessToken"></param>
        /// <returns></returns>
        public static GroupsJson Get(string accessToken)
        {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/groups/get?access_token={0}";
            var url = string.Format(urlFormat, accessToken);
            return HttpUtility.Get.GetJson<GroupsJson>(url);
        }

        /// <summary>
        /// 獲取使用者分組
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <returns></returns>
        public static GetGroupIdResult GetId(string accessToken, string openId)
        {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/groups/getid?access_token={0}";
            var data = new { openid = openId };
            return CommonJsonSend.Send<GetGroupIdResult>(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 建立分組
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="id"></param>
        /// <param name="name">分組名字（30個字元以內）</param>
        /// <returns></returns>
        public static WxJsonResult Update(string accessToken, int id, string name)
        {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/groups/update?access_token={0}";
            var data = new
            {
                group = new
                {
                    id = id,
                    name = name
                }
            };
            return CommonJsonSend.Send(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 移動使用者分組
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="toGroupId"></param>
        /// <returns></returns>
        public static WxJsonResult MemberUpdate(string accessToken, string openId, int toGroupId)
                {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/groups/members/update?access_token={0}";
            var data = new
            {
                openid = openId,
                to_groupid = toGroupId
            };
            return CommonJsonSend.Send(accessToken, urlFormat, data);
        }
    }
}

客服介面

　　說明一下，這裡的客服介面和之前的“多客服”是有差別的，之前介紹的多客服是把使用者對話狀態切換到多客服客，訊息傳送到專門的多客服戶端，這個對話是由使用者主動發起的。而這裡的“客服”實際上是指在任意時間，主動推送訊息給指定過的使用者（使用者在48小時內有過互動），對話不需要由使用者主動發起。

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/Custom

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    /// <summary>
    /// 客服介面
    /// </summary>
    public static class Custom
    {
        private const string URL_FORMAT = "https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token={0}";

        /// <summary>
        /// 傳送文字資訊
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="content"></param>
        /// <returns></returns>
        public static WxJsonResult SendText(string accessToken, string openId, string content)
        {
            var data = new
            {
                touser = openId,
                msgtype = "text",
                text = new
                {
                    content = content
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }

        /// <summary>
        /// 傳送圖片訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="mediaId"></param>
        /// <returns></returns>
        public static WxJsonResult SendImage(string accessToken, string openId, string mediaId)
        {
            var data = new
            {
                touser = openId,
                msgtype = "image",
                image = new
                {
                    media_id = mediaId
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }

        /// <summary>
        /// 傳送語音訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="mediaId"></param>
        /// <returns></returns>
        public static WxJsonResult SendVoice(string accessToken, string openId, string mediaId)
        {
            var data = new
            {
                touser = openId,
                msgtype = "voice",
                voice = new
                {
                    media_id = mediaId
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }

        /// <summary>
        /// 傳送視訊訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="mediaId"></param>
        /// <param name="thumbMediaId"></param>
        /// <returns></returns>
        public static WxJsonResult SendVideo(string accessToken, string openId, string mediaId, string thumbMediaId)
        {
            var data = new
            {
                touser = openId,
                msgtype = "video",
                video = new
                {
                    media_id = mediaId,
                    thumb_media_id = thumbMediaId
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }

        /// <summary>
        /// 傳送音樂訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="title">音樂標題（非必須）</param>
        /// <param name="description">音樂描述（非必須）</param>
        /// <param name="musicUrl">音樂連結</param>
        /// <param name="hqMusicUrl">高品質音樂連結，wifi環境優先使用該連結播放音樂</param>
        /// <param name="thumbMediaId">視訊縮圖的媒體ID</param>
        /// <returns></returns>
        public static WxJsonResult SendMusic(string accessToken, string openId, string title, string description,
                                    string musicUrl, string hqMusicUrl, string thumbMediaId)
        {
            var data = new
            {
                touser = openId,
                msgtype = "music",
                music = new
                {
                    title = title,
                    description = description,
                    musicurl = musicUrl,
                    hqmusicurl = hqMusicUrl,
                    thumb_media_id = thumbMediaId
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }

        /// <summary>
        /// 傳送圖文訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="openId"></param>
        /// <param name="title">音樂標題（非必須）</param>
        /// <param name="description">音樂描述（非必須）</param>
        /// <param name="musicUrl">音樂連結</param>
        /// <param name="hqMusicUrl">高品質音樂連結，wifi環境優先使用該連結播放音樂</param>
        /// <param name="thumbMediaId">視訊縮圖的媒體ID</param>
        /// <returns></returns>
        public static WxJsonResult SendNews(string accessToken, string openId, List<Article> articles)
        {
            var data = new
            {
                touser = openId,
                msgtype = "news",
                news = new
                {
                    articles = articles.Select(z => new
                                {
                                    title = z.Title,
                                    description = z.Description,
                                    url = z.Url,
                                    picurl = z.PicUrl//圖文訊息的圖片連結，支援JPG、PNG格式，較好的效果為大圖640*320，小圖80*80
                                }).ToList()
                }
            };
            return CommonJsonSend.Send(accessToken, URL_FORMAT, data);
        }
    }
}

群發介面

　　這裡的群發效果和登入微信後臺群發是一樣的。

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/GroupMessage

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    /// <summary>
    /// 高階群發介面
    /// </summary>
    public static class GroupMessage
    {
        /// <summary>
        /// 根據分組進行群發
        /// 
        /// 請注意：
        /// 1、該介面暫時僅提供給已微信認證的服務號
        /// 2、雖然開發者使用高階群發介面的每日呼叫限制為100次，但是使用者每月只能接收4條，請小心測試
        /// 3、無論在公眾平臺網站上，還是使用介面群發，使用者每月只能接收4條群發訊息，多於4條的群發將對該使用者傳送失敗。
        /// 
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="groupId">群發到的分組的group_id</param>
        /// <param name="mediaId">用於群發的訊息的media_id</param>
        /// <returns></returns>
        public static SendResult SendGroupMessageByGroupId(string accessToken, string groupId, string mediaId)
        {
            const string urlFormat = "https://api.weixin.qq.com/cgi-bin/message/mass/sendall?access_token={0}";
            var data = new
            {
                filter = new
                {
                    group_id = groupId
                },
                mpnews = new
                {
                    media_id = mediaId
                },
                msgtype = "mpnews"
            };
            return CommonJsonSend.Send<SendResult>(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 根據OpenId進行群發
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="mediaId">用於群發的訊息的media_id</param>
        /// <param name="openIds">openId字串陣列</param>
        /// <returns></returns>
        public static SendResult SendGroupMessageByOpenId(string accessToken, string mediaId, params string[] openIds)
        {
            const string urlFormat = "https://api.weixin.qq.com/cgi-bin/message/mass/send?access_token={0}";

            var data = new
            {
                touser = openIds,
                mpnews = new
                {
                    media_id = mediaId
                },
                msgtype = "mpnews"
            };
            return CommonJsonSend.Send<SendResult>(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 刪除群發訊息
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="mediaId">傳送出去的訊息ID</param>
        /// <returns></returns>
        public static WxJsonResult DeleteSendMessage(string accessToken, string mediaId)
        {
            //官方API地址為https://api.weixin.qq.com//cgi-bin/message/mass/delete?access_token={0}，應該是多了一個/
            const string urlFormat = "https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token={0}";

            var data = new
            {
                msgid = mediaId
            };
            return CommonJsonSend.Send<WxJsonResult>(accessToken, urlFormat, data);
        }
    }
}

多媒體介面

　　多媒體介面用於上傳圖片、語音、圖文訊息等多媒體資訊，一般這些資訊都可以用於客服介面或群發。

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/Media

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    //介面詳見：http://mp.weixin.qq.com/wiki/index.php?title=%E4%B8%8A%E4%BC%A0%E4%B8%8B%E8%BD%BD%E5%A4%9A%E5%AA%92%E4%BD%93%E6%96%87%E4%BB%B6
    
    /// <summary>
    /// 多媒體檔案介面
    /// </summary>
    public static class Media
    {
        /// <summary>
        /// 上傳媒體檔案
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="type"></param>
        /// <param name="file"></param>
        /// <returns></returns>
        public static UploadResultJson Upload(string accessToken, UploadMediaFileType type, string file)
        {
            var url = string.Format("http://file.api.weixin.qq.com/cgi-bin/media/upload?access_token={0}&type={1}", accessToken, type.ToString());
            var fileDictionary = new Dictionary<string, string>();
            fileDictionary["media"] = file;
            return HttpUtility.Post.PostFileGetJson<UploadResultJson>(url, null, fileDictionary, null);
        }

        /// <summary>
        /// 下載媒體檔案
        /// </summary>
        /// <param name="accessToken"></param>
        /// <param name="mediaId"></param>
        /// <param name="stream"></param>
        public static void Get(string accessToken, string mediaId, Stream stream)
        {
            var url = string.Format("http://file.api.weixin.qq.com/cgi-bin/media/get?access_token={0}&media_id={1}",
                accessToken, mediaId);
            HttpUtility.Get.Download(url, stream);
        }

        /// <summary>
        /// 上傳圖文訊息素材
        /// </summary>
        /// <param name="accessToken">Token</param>
        /// <param name="news">圖文訊息組</param>
        /// <returns></returns>
        public static UploadMediaFileResult UploadNews(string accessToken, params NewsModel[] news)
        {
            const string urlFormat = "https://api.weixin.qq.com/cgi-bin/media/uploadnews?access_token={0}";
            var data = new
            {
                articles = news
            };
            return CommonJsonSend.Send<UploadMediaFileResult>(accessToken, urlFormat, data);
        }


    }
}

二維碼介面

　　使用二維碼介面可以方便地建立和驗證二維碼。所建立的二維碼用於讓使用者關注或識別掃描的場景。

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/QrCode

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    //API：http://mp.weixin.qq.com/wiki/index.php?title=%E7%94%9F%E6%88%90%E5%B8%A6%E5%8F%82%E6%95%B0%E7%9A%84%E4%BA%8C%E7%BB%B4%E7%A0%81

    /// <summary>
    /// 二維碼介面
    /// </summary>
    public static class QrCode
    {
        /// <summary>
        /// 建立二維碼
        /// </summary>
        /// <param name="expireSeconds">該二維碼有效時間，以秒為單位。 最大不超過1800。0時為永久二維碼</param>
        /// <param name="sceneId">場景值ID，臨時二維碼時為32位整型，永久二維碼時最大值為1000</param>
        /// <returns></returns>
        public static CreateQrCodeResult Create(string accessToken, int expireSeconds, int sceneId)
        {
            var urlFormat = "https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token={0}";
            object data = null;
            if (expireSeconds > 0)
            {
                data = new
                {
                    expire_seconds = expireSeconds,
                    action_name = "QR_SCENE",
                    action_info = new
                    {
                        scene = new
                        {
                            scene_id = sceneId
                        }
                    }
                };
            }
            else
            {
                data = new
                {
                    action_name = "QR_LIMIT_SCENE",
                    action_info = new
                    {
                        scene = new
                        {
                            scene_id = sceneId
                        }
                    }
                };
            }
            return CommonJsonSend.Send<CreateQrCodeResult>(accessToken, urlFormat, data);
        }

        /// <summary>
        /// 獲取二維碼（不需要AccessToken）
        /// 錯誤情況下（如ticket非法）返回HTTP錯誤碼404。
        /// </summary>
        /// <param name="ticket"></param>
        /// <param name="stream"></param>
        public static void ShowQrCode(string ticket, Stream stream)
        {
            var urlFormat = "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket={0}";
            HttpUtility.Get.Download(string.Format(urlFormat, ticket), stream);
        }
    }
}

模板訊息介面

　　模板訊息類似於簡訊通知，它遵循一定的模板格式（和圖文資訊等不一樣），不是每個通過驗證的服務號都可以獲取。

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/TemplateMessage

　　原始碼中相關方法如下：

namespace Senparc.Weixin.MP.AdvancedAPIs
{
    /// <summary>
    /// 模板訊息介面
    /// </summary>
    public static class Template
    {
        public static WxJsonResult SendTemplateMessage<T>(string accessToken, string openId, string templateId, string topcolor, T data)
        {
            const string urlFormat = "https://api.weixin.qq.com/cgi-bin/message/template/send?access_token={0}";
            var msgData = new TempleteModel()
            {
                template_id = templateId,
                topcolor = topcolor,
                touser = openId,
                data = data
            };
            return CommonJsonSend.Send<WxJsonResult>(accessToken, urlFormat, msgData);
        }
    }
}

OAuth2.0介面

　　OAuth介面用於安全驗證使用微信內嵌瀏覽器訪問的使用者的身份（例如獲取OpenId）

　　原始檔資料夾：Senparc.Weixin.MP/AdvancedAPIs/OAuth

　　相比其他介面OAuth2.0略微複雜，相關內容將在下一篇專門進行介紹：《Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十二）：OAuth2.0說明》

系列教程索引

地址：http://www.cnblogs.com/szw/archive/2013/05/14/weixin-course-index.html

Senparc.Weixin.MP SDK 微信公眾平臺開發教程（八）：通用介面說明
2014-05-24
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十）：多客服介面說明
2014-06-02
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（九）：自定義選單介面說明
2014-05-24
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十二）：OAuth2.0說明
2014-06-02
OAuth
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（三）：微信公眾平臺開發驗證
2013-07-20
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（五）：使用Senparc.Weixin.MP SDK
2013-11-08
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（四）：Hello World
2013-11-08
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十五）：訊息加密
2014-12-03
加密
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（六）：瞭解MessageHandler
2013-11-08
C#微信公眾平臺開發—高階群發介面
2014-11-19
C#
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（二十）：使用選單訊息功能
2019-03-09
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十四）：請求訊息去重
2014-12-02
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十六）：AccessToken自動管理機制
2015-07-06
微信公眾平臺開發（十一）功能整合
2014-02-13
微信公眾平臺開發JS-SDK開發（影像介面例項）
2017-11-03
JS
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十九）：MessageHandler 的未知型別訊息處理
2017-10-27
型別
微信公眾平臺SDK for node
2017-07-23
微信公眾平臺完整開發教程 by ZTalk
2014-03-26
Senparc.Weixin.MP SDK 微信公眾平臺開發教程（七）：解決使用者上下文（Session）問題
2013-11-08
Session
***wechat-php-sdk微信公眾平臺php開發包
2016-12-20
PHP
微信公眾平臺介面API
2016-09-12
API
1.PHP微信公眾平臺開發（一）配置介面
2019-05-11
PHP
微信公眾平臺開發介面PHPSDK完整版
2014-03-15
PHP
微信公眾平臺開發入門
2020-11-04
微信公眾平臺JSSDK分享介面開發（PHP實現）
2015-11-17
JSPHP
微信公眾平臺通用介面API指南
2015-12-24
API
PHP微信公眾平臺開發視訊
2020-04-04
PHP
最新微信公眾平臺js sdk整合PHP版
2015-01-22
JSPHP
微信公眾平臺開發（六）翻譯功能開發
2013-07-29
微信公眾平臺開發之店鋪類
2019-05-11
基於 PHP 的微信公眾平臺開發
2017-05-18
PHP
2.PHP微信公眾平臺開發（二）公眾平臺示例程式碼分
2019-05-11
PHP
微信公眾介面開發介紹
2014-04-30
微信公眾平臺開發（四）簡單回覆功能開發
2013-07-03
微信公眾平臺搭建與開發揭祕.pdf
2016-12-15
微信公眾平臺開發(77) 圖片下載
2014-01-05
微信公眾平臺開發（九）資料庫操作
2013-10-09
資料庫
6.PHP微信公眾平臺開發 - 翻譯功能開發
2019-05-11
PHP

Senparc.Weixin.MP SDK 微信公眾平臺開發教程（十一）：高階介面說明

一些共同的操作

使用者介面

分組介面

客服介面

群發介面

多媒體介面

二維碼介面

模板訊息介面

OAuth2.0介面

系列教程索引

相關文章