----关于腾讯 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 类进行创建,请参考如下代码:
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 类,创建及访问示例如下:
TCAcount tca = new TCAcount();
string SDKAppId=tca.SDKAppId;
string SDKAppIdSecret=tca.SDKAppIdSecret;
(4) 用到两个时间戳函数,代码如下:
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(需要验证) 仅当创建支持申请加群的群组时,该字段有效。社群目前不支持此字段 |
实现代码如下:
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 = "{"GroupId": ""+GroupId+"","Silence": "+Silence+","MemberList": [ {"Member_Account": ""+Account+""}]}";settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random); WebService ws = new WebService(); string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", 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"关闭 |
实现代码如下:
//修改群基础资料
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 == "" ? "" : ", "Name":"" + Name + """;
string intro = Introduction == "" ? "" : ", "Introduction":"" + Introduction + """;
string faceurl = FaceUrl == "" ? "" : ", "FaceUrl":"" + FaceUrl + """;
string joinoption = ApplyJoinOption == "" ? "" : ", "ApplyJoinOption":"" + ApplyJoinOption + """;string content = "{\"GroupId\":\""+GroupId+"\""+name+intro+faceurl+joinoption+"}"; settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random); WebService ws = new WebService(); string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", 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 | 指定群成员的禁言时间,单位为秒。 |
实现代码如下:
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 == "" ? "" : ", "Role":""+Role+""";
string msgflag = MsgFlag == "" ? "" : ", "MsgFlag":"" + MsgFlag + """;
string namecard = NameCard == "" ? "" : ", "NameCard":"" + NameCard + """;
string shutuptime = ShutUpTime == -1 ? "" : ", "ShutUpTime":" + ShutUpTime + "";string content = "{\"GroupId\":\""+GroupId+"\", \"Member_Account\":\""+Account+"\""+role+msgflag+namecard+shutuptime+"}"; settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random); WebService ws = new WebService(); string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content); return resultStr;
}
获取被禁言群成员列表
GetGroupShuttedList 方法可获取根据群组 ID 获取群组中被禁言的用户列表。其关键属性方法说明如下:
序号 | 参数 | 类型 | 说明 |
---|---|---|---|
1 | GroupId | string | 要获取操作的群组 ID |
实现代码如下:
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 = "{\"GroupId\":\"" + GroupId + "\"}"; settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random); WebService ws = new WebService(); string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content); return resultStr;
}
解散群组
DestoryGroup 方法可解散指定ID的群组。其关键属性方法说明如下:
序号 | 参数 | 类型 | 说明 |
---|---|---|---|
1 | GroupId | string | 要解散的群组ID |
实现代码如下:
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 = "{"GroupId": "" + GroupId + ""}";settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random); WebService ws = new WebService(); string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content); return resultStr;
}
小结
腾讯云 IM REST API 提供了非常丰富与完善的管理功能列表,在这里我们仅是以满足自身应用需要而提取的常用帐户管理功能,更多详情请参照如下链接:
REST API 接口列表 | 腾讯云
本文代码仅供您参考使用,您可以参照官方文档开发出更加贴合自身需求的应用,感谢您的阅读,希望本文能够对您有所帮助。