Senparc.Weixin.MP SDK 微信公眾平台開發教程（十一）：高級接口說明

    這里所說的高級接口是指面向通過認證的服務號開通的高級功能。

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

• 用戶接口
• 分組接口
• 客服接口（有別於之前介紹的多客服）
• 群發接口
• 多媒體接口
• 二維碼接口
• 模板消息接口（不是所有賬號都可開通）
• 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

1. Senparc.Weixin.MP SDK 微信公眾平台開發教程（一）：微信公眾平台注冊
2. Senparc.Weixin.MP SDK 微信公眾平台開發教程（二）：成為開發者
3. Senparc.Weixin.MP SDK 微信公眾平台開發教程（三）：微信公眾平台開發驗證
4. Senparc.Weixin.MP SDK 微信公眾平台開發教程（四）：Hello World
5. Senparc.Weixin.MP SDK 微信公眾平台開發教程（五）：使用Senparc.Weixin.MP SDK
6. Senparc.Weixin.MP SDK 微信公眾平台開發教程（六）：了解MessageHandler
7. Senparc.Weixin.MP SDK 微信公眾平台開發教程（七）：解決用戶上下文（Session）問題
8. Senparc.Weixin.MP SDK 微信公眾平台開發教程（八）：通用接口說明
9. Senparc.Weixin.MP SDK 微信公眾平台開發教程（九）：自定義菜單接口說明
10. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十）：多客服接口說明
11. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十一）：高級接口說明
12. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十二）：OAuth2.0說明
13. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十三）：地圖相關接口說明
14. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十四）：請求消息去重
15. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十五）：消息加密
16. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十六）：AccessToken自動管理機制
17. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十七）：個性化菜單接口說明
18. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十八）：Web代理功能
19. Senparc.Weixin.MP SDK 微信公眾平台開發教程（十九）：MessageHandler 的未知類型消息處理
20. Senparc.Weixin.MP SDK 微信公眾平台開發教程（二十）：使用菜單消息功能
21. Senparc.Weixin.MP SDK 微信公眾平台開發教程（二十一）：在小程序中使用 WebSocket （.NET Core）
22. Senparc.Weixin.MP SDK 微信公眾平台開發教程（二十二）：如何安裝 Nuget(dll) 后使用項目源代碼調試