C# 实现腾讯云 IM 常用 REST API 之会话管理

初九之潜龙勿用

发布于 2024-06-20 13:31:58

510

发布于 2024-06-20 13:31:58

关于腾讯 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

查询账号会话总未读数

GetC2C_UnreadMsgNum方法可以在 IM 应用系统内查询特定账号的单聊总未读数（包含所有的单聊会话）或者单个单聊会话的未读数。其关键属性方法说明如下：

序号	参数	类型	说明
1	To_Account	string	要查询的用户 UserID
2	Peer_Account	string[]	要查询的单聊会话对端的用户 UserId 若要查询单个会话的未读数，该字段必填该数组最大大小为10 注：如果传递null，则表示管理员查询未读的单聊消息的总数。只填 To_Account 即可。

现代码如下：

public string GetC2C_UnreadMsgNum(string To_Account, string[] Peer_Account)
{
                    ArrayList data = new ArrayList();
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/openim/get_c2c_unread_msg_num?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 peer = "";
                    if (Peer_Account!=null)
                    {
                        foreach(string peeraccount in Peer_Account)
                        {
                            peer += "\"" + peeraccount + "\",";
                        }
                        if (peer != "")
                        {
                            peer = ",\"Peer_Account\":[" +peer.Substring(0, peer.Length - 1)+"]";
                        }
                    }
                    string content = "{\"To_Account\":\"" + To_Account+"\"" + peer + "}";
                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
                }

查询单聊会话消息记录

GetRoamMsg 方法使管理员可以在 IM 应用系统内按照时间范围，以会话其中一方的角度查询单聊会话的消息记录。其关键属性方法说明如下：

序号	参数	类型	说明
1	From_Account	string	会话其中一方的 UserID，以该 UserID 的角度去查询消息。
2	To_Account	string	会话的另一方 UserID
3	MaxCnt	int	请求的消息条数
4	MinTime	string	请求的消息时间范围的最小值（单位：秒）
5	MaxTime	string	请求的消息时间范围的最大值（单位：秒）
6	LastMsgKey	string	上一次拉取到的最后一条消息的 MsgKey，续拉时需要填写该字段

现代码如下：

public string GetRoamMsg(string From_Account,string To_Account,int MaxCnt,string MinTime,string MaxTime,string LastMsgKey)
{
                    ArrayList data = new ArrayList();
                    TCAcount tca = new TCAcount("turing");
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/openim/admin_getroammsg?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 mintime = GetTimeStamp(DateTime.Parse(MinTime));
                    string maxtime = GetTimeStamp(DateTime.Parse(MaxTime));
                    if (LastMsgKey != "")
                    {
                        LastMsgKey = ",\"LastMsgKey\": \"" + LastMsgKey + "\"";
                    }
                    string content = "{\"From_Account\":\"" + From_Account + "\",\"To_Account\":\"" + To_Account + "\",\"MaxCnt\":" + MaxCnt.ToString() + ",\"MinTime\":"+mintime+",\"MaxTime\":"+maxtime+LastMsgKey+"}";
                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}

下载最近会话记录

get_history 方法可使管理员获取最近7天中某天某小时的所有单发或群组消息记录的下载地址。其关键属性方法说明如下：

序号	参数	类型	说明
1	yyyymmddhh	string	需要下载的消息记录的时间段（北京时间）。2015120121表示获取2015年12月1日21:00 - 21:59的消息的下载地址。该字段需精确到小时。每次请求只能获取某天某小时的所有单发或群组消息记录
2	chattype	string	消息类型，C2C 表示单发消息， Group 表示群组消息，默认为"C2C"

实现代码如下：

public string get_history(string yyyymmddhh,string chattype= "C2C")
{
                    ArrayList data = new ArrayList();
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/open_msg_svc/get_history?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 = "{\"ChatType\":\"" + chattype + "\",\"MsgTime\":\"" + yyyymmddhh + "\"}";

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

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}