C# 实现腾讯云 IM 常用 REST API 之群组管理

----关于腾讯 IM REST API

REST API 是腾讯即时通信 IM 提供给服务端的一组 HTTP 后台管理接口,如消息管理、群组管理、用户管理、会话管理等等。REST API 接口较为原始,管理能力强大。另外,为了安全性,REST API 仅提供 HTTPS 接口,本文将主要介绍常用的群组管理API。

开发前准备

(1)开发前需要申请 SDK 开发者 ID 及密钥,如何获取请参照如下链接:

腾讯IM即时通信控制台

(2)调用 REST API 之前,需要生成 UserSig ,UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文,如何生成 UserSig 请参照我的文章《C# 生成腾讯云 IM 之 TLSSigAPIv2 UserSig》,通过 TLSSigAPIv2 类进行创建,请参考如下代码:

代码语言:javascript
复制
string SDKAppId="申请的SDKAppID";  
string SDKAppIdSecret="申请的SDKAppIdSecret";  
string AppAdminId="IM平台超级管理员UserID";

TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(SDKAppId),SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);

(3)SDKAppID 及 SDKAppIdSecret 的获取在后续范例中均封装为 TCAcount 类,创建及访问示例如下:

代码语言:javascript
复制
TCAcount tca = new TCAcount();
string SDKAppId=tca.SDKAppId;
string SDKAppIdSecret=tca.SDKAppIdSecret;

(4) 用到两个时间戳函数,代码如下:

代码语言:javascript
复制
public string getTimestamp(int seconds)
{
TimeSpan ts = DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0);
return Convert.ToInt64(ts.TotalSeconds + seconds).ToString();
}
public string GetTimeStamp(DateTime dtime)
{
TimeSpan tspan = dtime.ToUniversalTime() - new DateTime(1970, 1, 1, 0, 0, 0, 0);
return Convert.ToInt64(tspan.TotalSeconds).ToString();
}

(5) WebService 类实现访问 REST API URL 地址并 POST 数据,以获取返回结果 Json 的功能。具体实现请参照我的文章《C# 实现访问 Web API Url 提交数据并获取处理结果》

范例运行环境

操作系统: Windows Server 2019 DataCenter

.net版本: .netFramework4.0 或以上

开发工具:VS2019 C#

常用群组管理API

创建群组

CreateGroup 方法为 IM 应用系统创建一个群组。其关键属性方法说明如下:

序号

参数

类型

说明

1

GroupId

string

必填:群组ID

2

Owner_Account

string

群主 ID(已存在的账号)。填写后自动添加到群成员中;如果不填,群没有群主;成员使用 AVChatroom(直播群)时,必须每次调用进群操作

3

Type

string

必填:群组形态,包括 Public(陌生人社交群),Private(即 Work,好友工作群),ChatRoom(即 Meeting,会议群),AVChatRoom(直播群),Community(社群)

4

Name

string

必填:群名称,最长30字节,使用 UTF-8 编码,1个汉字占3个字节

5

Introduction

string

群简介,最长240字节,使用 UTF-8 编码,1个汉字占3个字节

6

Notification

string

群公告,最长300字节,使用 UTF-8 编码,1个汉字占3个字节

7

FaceUrl

string

群头像 URL,最长100字节

8

ApplyJoinOption

string

申请加群处理方式。包含 FreeAccess(自由加入),NeedPermission(需要验证),DisableApply(禁止加群),不填默认为 NeedPermission(需要验证) 仅当创建支持申请加群的群组时,该字段有效。社群目前不支持此字段

实现代码如下:

代码语言:javascript
复制
public string CreateGroup(string GroupId,string Owner_Account, string Type, string Name, string Introduction, string Notification, string FaceUrl, string ApplyJoinOption)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/create_group?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);
string content = "{"Owner_Account": ""+Owner_Account+"", "Type": ""+Type+"", "GroupId": ""+GroupId+"","Name": ""+Name+"","Introduction":""+Introduction+""," +
""Notification": ""+Notification+"","FaceUrl": ""+FaceUrl+"","ApplyJoinOption": ""+ApplyJoinOption+""}";

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                return resultStr;
            }</code></pre></div></div><h5 id="851269" name="%E5%A2%9E%E5%8A%A0%E7%BE%A4%E6%88%90%E5%91%98">增加群成员</h5><p>AddGroupUser 方法向指定的群中添加新成员用户。其关键属性方法说明如下:</p><div class="table-wrapper"><table><thead><tr><th style="text-align:left"><div><div class="table-header"><p>序号</p></div></div></th><th style="text-align:left"><div><div class="table-header"><p>参数</p></div></div></th><th style="text-align:left"><div><div class="table-header"><p>类型</p></div></div></th><th style="text-align:left"><div><div class="table-header"><p>说明</p></div></div></th></tr></thead><tbody><tr><td style="text-align:left"><div><div class="table-cell"><p>1</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>GroupId</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>string</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>要添加新成员的群组 ID</p></div></div></td></tr><tr><td style="text-align:left"><div><div class="table-cell"><p>2</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>Account</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>string</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>要添加的群成员 UserID</p></div></div></td></tr><tr><td style="text-align:left"><div><div class="table-cell"><p>3</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>Silence</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>string</p></div></div></td><td style="text-align:left"><div><div class="table-cell"><p>是否静默加人。0:非静默加人;1:静默加人。不填该字段默认为0</p></div></div></td></tr></tbody></table></div><p>实现代码如下:</p><div class="rno-markdown-code"><div class="rno-markdown-code-toolbar"><div class="rno-markdown-code-toolbar-info"><div class="rno-markdown-code-toolbar-item is-type"><span class="is-m-hidden">代码语言:</span>javascript</div></div><div class="rno-markdown-code-toolbar-opt"><div class="rno-markdown-code-toolbar-copy"><i class="icon-copy"></i><span class="is-m-hidden">复制</span></div></div></div><div class="developer-code-block"><pre class="prism-token token line-numbers language-javascript"><code class="language-javascript" style="margin-left:0">//增加群成员

public string AddGroupUser(string GroupId, string Account, string Silence)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/add_group_member?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);
string content = "{&#34;GroupId&#34;: &#34;"+GroupId+"&#34;,&#34;Silence&#34;: "+Silence+",&#34;MemberList&#34;: [ {&#34;Member_Account&#34;: &#34;"+Account+"&#34;}]}";

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, &#34;POST&#34;, content);
                return resultStr;

}

修改群基础资料

ModifyGroupBaseInfo 方法可修改指定群组的基础信息。其关键属性方法说明如下:

序号

参数

类型

说明

1

GroupId

string

要修改的群组 ID

2

Name

string

群名称,最长30字节,使用 UTF-8 编码,1个汉字占3个字节

3

Introduction

string

群简介,最长240字节,使用 UTF-8 编码,1个汉字占3个字节

4

FaceUrl

string

群头像 URL,最长100字节

5

ApplyJoinOption

string

申请加群处理方式。包含 FreeAccess(自由加入),NeedPermission(需要验证),DisableApply(禁止加群),不填默认为 NeedPermission(需要验证) 仅当创建支持申请加群的群组时,该字段有效。社群目前不支持此字段

6

ShutUpAllMember

string

群内群成员禁言,只有群管理员和群主以及系统管理员可以发言,"On"开启,"Off"关闭

实现代码如下:

代码语言:javascript
复制
//修改群基础资料
public string ModifyGroupBaseInfo(string GroupId, string Name, string Introduction, string FaceUrl, string ApplyJoinOption, string ShutUpAllMember)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/modify_group_base_info?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);
string name = Name == "" ? "" : ", &#34;Name&#34;:&#34;" + Name + "&#34;";
string intro = Introduction == "" ? "" : ", &#34;Introduction&#34;:&#34;" + Introduction + "&#34;";
string faceurl = FaceUrl == "" ? "" : ", &#34;FaceUrl&#34;:&#34;" + FaceUrl + "&#34;";
string joinoption = ApplyJoinOption == "" ? "" : ", &#34;ApplyJoinOption&#34;:&#34;" + ApplyJoinOption + "&#34;";

                string content = &#34;{\&#34;GroupId\&#34;:\&#34;&#34;+GroupId+&#34;\&#34;&#34;+name+intro+faceurl+joinoption+&#34;}&#34;;

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, &#34;POST&#34;, content);
                return resultStr;

} //edit_group_info

修改群成员资料

ModifyGroupUser 方法可以修改指定群成员用户的资料。其关键属性方法说明如下:

序号

参数

类型

说明

1

GroupId

string

要修改操作的群组 ID

2

Account

string

要操作的群成员UserID

3

Role

string

成员身份,Admin/Member 分别为设置/取消管理员(不允许修改群主的身份)

4

MsgFlag

string

设置的指定成员消息屏蔽类型: AcceptAndNotify 代表接收并提示消息,Discard 代表不接收也不提示消息,AcceptNotNotify 代表接收消息但不提示。

5

NameCard

string

指定成员的群名片,最大不超过50个字节。

6

ShutUpTime

int

指定群成员的禁言时间,单位为秒。

实现代码如下:

代码语言:javascript
复制
public string ModifyGroupUser(string GroupId, string Account, string Role,string MsgFlag,string NameCard,int ShutUpTime)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/modify_group_member_info?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);
string role = Role == "" ? "" : ", &#34;Role&#34;:&#34;"+Role+"&#34;";
string msgflag = MsgFlag == "" ? "" : ", &#34;MsgFlag&#34;:&#34;" + MsgFlag + "&#34;";
string namecard = NameCard == "" ? "" : ", &#34;NameCard&#34;:&#34;" + NameCard + "&#34;";
string shutuptime = ShutUpTime == -1 ? "" : ", &#34;ShutUpTime&#34;:" + ShutUpTime + "";

                string content = &#34;{\&#34;GroupId\&#34;:\&#34;&#34;+GroupId+&#34;\&#34;, \&#34;Member_Account\&#34;:\&#34;&#34;+Account+&#34;\&#34;&#34;+role+msgflag+namecard+shutuptime+&#34;}&#34;;

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, &#34;POST&#34;, content);
                return resultStr;

}

获取被禁言群成员列表

GetGroupShuttedList 方法可获取根据群组 ID 获取群组中被禁言的用户列表。其关键属性方法说明如下:

序号

参数

类型

说明

1

GroupId

string

要获取操作的群组 ID

实现代码如下:

代码语言:javascript
复制
public string GetGroupShuttedList(string GroupId)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/get_group_shutted_uin?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);

                string content = &#34;{\&#34;GroupId\&#34;:\&#34;&#34; + GroupId + &#34;\&#34;}&#34;;

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, &#34;POST&#34;, content);
                return resultStr;

}

解散群组

DestoryGroup 方法可解散指定ID的群组。其关键属性方法说明如下:

序号

参数

类型

说明

1

GroupId

string

要解散的群组ID

实现代码如下:

代码语言:javascript
复制
public string DestoryGroup(string GroupId)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/destroy_group?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
string AppAdminId = "administrator";
Random rnd = new Random();
string random = rnd.Next(0, 429496729).ToString();
TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);
string content = "{&#34;GroupId&#34;: &#34;" + GroupId + "&#34;}";

                settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                WebService ws = new WebService();

                string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, &#34;POST&#34;, content);
                return resultStr;

}

小结

腾讯云 IM REST API 提供了非常丰富与完善的管理功能列表,在这里我们仅是以满足自身应用需要而提取的常用帐户管理功能,更多详情请参照如下链接:

REST API 接口列表 | 腾讯云

本文代码仅供您参考使用,您可以参照官方文档开发出更加贴合自身需求的应用,感谢您的阅读,希望本文能够对您有所帮助。