云端历史消息查询 - IM 即时通讯

开发者中心

IM 即时通讯

服务端 API

云端历史消息查询

更新时间： 2024/03/15 14:09:52

网易云信 IM 支持用户查询云端历史消息功能，包括单聊、群聊、聊天室云端历史消息，以及云端会话列表。

单聊云端历史消息查询
群聊云端历史消息查询
聊天室云端历史消息查询
删除聊天室云端历史消息
云端会话列表查询

单聊云端历史消息查询

功能描述

查询存储在网易云信服务器中的单人聊天历史消息，只能查询在保存时间范围内的消息。

根据时间段查询点对点消息，每次最多返回 100 条。
不提供分页支持，第三方需要根据时间段来查询。
begintime 需要早于 endtime，否则会返回{"desc": "bad time", "code": 414}。

API 使用限制

单个应用默认最高调用频率：100 次/秒。如超限，将被屏蔽 10 秒。

URL

POST  https://api.netease.im/nimserver/history/querySessionMsg.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API 调用方式。
POST 请求中 Body 的设置如下：

参数	类型	必填	说明
from	String	是	发送者accid 实际查询结果包含双向的消息，不仅包含 from 发送给 to 的消息，也包含 to 发给 from 的消息。
to	String	是	接收者accid 实际查询结果包含双向的消息，不仅包含 from 发送给 to 的消息，也包含 to 发给 from 的消息。
begintime	String	是	开始时间，毫秒级
endtime	String	是	截止时间，毫秒级
limit	int	是	本次查询的消息条数上限(最多100条),小于等于0，或者大于100，会提示参数错误
reverse	int	否	1按时间正序排列，2按时间降序排列。其它返回参数414错误.默认是按降序排列，即时间戳最晚的消息排在最前面。
type	String	否	查询指定的多个消息类型，类型之间用","分割，不设置该参数则查询全部类型消息格式示例： 0,1,2,3 类型支持：0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，11:Robot，100:自定义
includeNoSenseMsg	String	否	查询结果中是否需要包含无感知消息，true：包含，false：不包含，默认为 false 无感知消息具体包括：发送消息时，被设置为发送方无感知的消息（即 msgSenderNoSense=1）发送消息时，被设置为接收方无感知的消息（即 msgReceiverNoSense=1）被单向撤回的消息被单向删除的消息以下消息，不属于无感知消息：被双向撤回的消息被双向删除的消息
excludeMsgid	String	否	结束查询的最后一条消息的 msgid（不包含在查询结果中），用于定位锚点为了保证极端场景下（两条消息的时间戳一致）不丢失消息，建议每次查询时填写该字段，定位最后一次查询到的消息。

示例

请求示例（curl）

curlcurl -X POST -H "AppKey: go9d***3mgq3" -H "Nonce: 4tg***23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9d***c55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'begintime=1443599631111&endtime=1443599639999&from=zhangsan&to=lisi&limit=50' 'https://api.netease.im/nimserver/history/querySessionMsg.action'

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
   "code":200,
   "size":xxx,//总共消息条数
   "msgs":[msg1,msg2,···,msgn] //消息集合，JSONArray
}

查询返回的消息示例参见历史消息查询返回的消息格式说明。

状态码

该接口在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

群聊云端历史消息查询

功能描述

查询存储在网易云信服务器中的群聊历史消息，只能查询在保存时间范围内的消息。

根据时间段查询群消息，每次最多返回 100 条。
不提供分页支持，第三方需要根据时间段来查询。
begintime 需要早于 endtime，否则会返回{"desc": "bad time", "code": 414}。

API 使用限制

单个应用默认最高调用频率：100 次/秒。如超限，将被屏蔽 10 秒。

URL

POST  https://api.netease.im/nimserver/history/queryTeamMsg.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API 调用方式。
POST 请求中 Body 的设置如下：

参数	类型	必填	说明
tid	String	是	群id
accid	String	是	查询用户对应的accid.
begintime	String	是	开始时间，毫秒级
endtime	String	是	截止时间，毫秒级
limit	int	是	本次查询的消息条数上限(最多100条),小于等于0，或者大于100，会提示参数错误
reverse	int	否	1按时间正序排列，2按时间降序排列。其它返回参数414错误。默认是按降序排列，即时间戳最晚的消息排在最前面。
type	String	否	查询指定的多个消息类型，类型之间用","分割，不设置该参数则查询全部类型消息格式示例： 0,1,2,3 类型支持：0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，11:Robot，100:自定义
checkTeamValid	Boolean	否	true(默认值)：表示需要检查群是否有效,accid是否为有效的群成员；设置为false则仅检测群是否存在，accid是否曾经为群成员。
includeNoSenseMsg	String	否	查询结果中是否需要包含无感知消息，true：包含，false：不包含，默认为 false 无感知消息具体包括：发送消息时，被设置为发送方无感知的消息（即 msgSenderNoSense=1）发送消息时，被设置为接收方无感知的消息（即 msgReceiverNoSense=1）被单向撤回的消息被单向删除的消息以下消息，不属于无感知消息：被双向撤回的消息被双向删除的消息
excludeMsgid	String	否	结束查询的最后一条消息的 msgid（不包含在查询结果中），用于定位锚点为了保证极端场景下（两条消息的时间戳一致）不丢失消息，建议每次查询时填写该字段，定位最后一次查询到的消息。

示例

请求示例（curl）

curlcurl -X POST -H "AppKey: go9***03mgq3" -H "Nonce: 4tg***23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9d***583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'begintime=1443599631111&endtime=1443599639999&tid=1513535&accid=zhangsan&limit=50' 'https://api.netease.im/nimserver/history/queryTeamMsg.action'

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "size":xxx,//总共消息条数
  "msgs":[msg1,msg2,···,msgn] //消息集合，JSONArray。
}

查询返回的消息示例参见历史消息查询返回的消息格式说明。

状态码

接口在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

聊天室云端历史消息查询

功能描述

查询存储在网易云信服务器中的聊天室历史消息。

API 使用限制

单个应用默认最高调用频率：1200 次/分。如超限，将被屏蔽 1 分钟。

URL

POST  https://api.netease.im/nimserver/history/queryChatroomMsg.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考API 调用方式

请求参数

POST 请求中 Headers 的设置请参考API 调用方式。
POST 请求中 Body 的设置如下：

参数	类型	必填	说明
roomid	long	是	聊天室id
accid	String	是	用户账号
timetag	long	是	查询的时间戳锚点，13位。reverse=1时timetag为起始时间戳，reverse=2时timetag为终止时间戳
limit	int	是	本次查询的消息条数上限(最多200条),小于等于0，或者大于200，会提示参数错误
reverse	int	否	1按时间正序排列，2按时间降序排列。其它返回参数414错误。默认是2按时间降序排列
type	String	否	查询指定的多个消息类型，类型之间用","分割，不设置该参数则查询全部类型消息。格式示例： 0,1,2,3 支持的消息类型：0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，11:智能机器人消息，100:自定义消息。用英文逗号分隔。

示例

请求示例（curl）

curlcurl -X POST -H "AppKey: go9dnk4***gq3" -H "Nonce: 12345" -H "CurTime: 1459154905" -H "CheckSum: 8d3ef0***75d906e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=123456&accid=zhangsan&timetag=1471234567812&limit=20&reverse=2' "https://api.netease.im/nimserver/history/queryChatroomMsg.action"

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "size":xxx,//总共消息条数
    "msgs":[msg1,msg2,···,msgn] //消息集合，JSONArray。
}

查询返回的消息示例参见历史消息查询返回的消息格式说明。

状态码

接口在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

删除聊天室云端历史消息

API 使用限制

单个应用默认最高调用频率：100 次/秒。如超限，将被屏蔽 10 秒。

URL

POST  https://api.netease.im/nimserver/chatroom/deleteHistoryMessage.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API 调用方式。
POST 请求中 Body 的设置如下：

参数	类型	必填	说明
roomid	long	是	聊天室id
fromAcc	String	是	消息发送者的accid
msgTimetag	long	是	消息的时间戳，单位毫秒，应该拿到原始消息中的时间戳为参数

示例

请求示例（curl）

curlcurl -X POST -H "AppKey: go9***3mgq3" -H "Nonce: 12345" -H "CurTime: 1459154905" -H "CheckSum: 8d3ef***6e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=123456&fromAcc=zhangsan&msgTimetag=1491234567812' "https://api.netease.im/nimserver/chatroom/deleteHistoryMessage.action"

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

状态码

接口在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

云端会话列表查询

功能描述

查询云端会话列表，需要先开通云端会话列表功能。

API 使用限制

单个应用默认最高调用频率：100 次/秒。如超限，将被屏蔽 10 秒。

URL

POST  https://api.netease.im/nimserver/history/querySessionList.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

请求参数

POST 请求中 Headers 的设置请参考API 调用方式。
POST 请求中 Body 的设置如下：

参数	类型	必填	说明
accid	String	是	账号
minTimestamp	long	否	查询的最小时间戳，单位毫秒，默认0
maxTimestamp	long	否	查询的最大时间戳，单位毫秒，默认当前时间戳
limit	int	否	最大100，默认100
needLastMsg	int	否	是否需要同步返回最后一条消息，0表示不需要，1表示需要，默认不需要

示例

请求示例（curl）

curlcurl -X POST -H "appkey: fe416***ad2547" -H "nonce: 12345" -H "curtime: 1459154905" -H "checksum: 8d3ef***8e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=acc01' "https://api.netease.im/nimserver/history/querySessionList.action"

返回示例

json"Content-Type": "application/json; charset=utf-8"
{
  "code": 200,
  "data": {
    "sessions": [
      {
        "lastMsgType": "RECALL", //表示最后一条消息是撤回
        "updateTime": 1627895970387,
        "lastMsg": {
          "deleteMsgIdClient": "39468de03f65059dee60c28558aa1b92", //被撤回消息的消息id（客户端）
          "deleteMsgCreateTime": 1627895944689, //被撤回消息的发送时间
          "from": "acc02",  //撤回操作者
          "time": 1627895970387,  //撤回操作时间
          "deleteMsgIdServer": "10252224"  //被撤回消息的消息id（服务器）
        },
        "sessionType": 1, //会话类型，1表示点对点，2表示群，3表示超大群，其中超大群最后一条消息暂不支持撤回
        "accid": "accid01"  //如果是点对点会话，则包括accid字段；如果是群和超大群，则包括tid字段
      },
      {
        "lastMsgType": "MESSAGE", //表示最后一条消息是消息
        "updateTime": 1627895899222,
        "lastMsg": {
          "msgIdClient": "742b887b50576e3562994bb616ecf4f0",  //消息id（客户端）
          "fromClientType": "WEB",  //消息发送者客户端类型
          "from": "acc03",   //消息发送者
          "time": "1627895899222",  //消息发送时间
          "body": "嘿哈嘿哈123",  //消息内容，包括body、attach、ext三个字段，本例子仅包含了body字段
          "type": 0,
          "msgIdServer": 10252222 //消息id（服务器）
        },
        "sessionType": 2, 
        "tid": 123  //如果是点对点会话，则包括accid字段；如果是群和超大群，则包括tid字段
      }
    ],
    "hasMore": false
  }
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

历史消息查询返回的消息格式说明

msgid（Long类型）为消息的服务端 ID ，msgidclient（String类型）为消息的客户端 ID。
当消息为聊天室消息时，此时只有msgid，没有msgidclient，且msgid为String类型，即"msgid": "d864"。

1.普通文本消息

json{
    "from":"test1",
    "msgid":792478,
    "sendtime":1430967883307,
    "type":0,//文本消息类型
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "msg":"哈哈哈"//消息内容
     }
}

2.图片消息

json{
    "from":"test1",
    "msgid":792502,
    "sendtime":1430978396680,   //发送时间ms
    "type":1,    //图片类型消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "name":"图片发送于2015-05-07 13:59",         //图片name
        "md5":"9894907e4ad9de4678091277509361f7",   //图片文件md5
        "url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e",    //生成的url
        "ext":"jpg",        //图片后缀
        "w":6814,       //宽，单位为像素
        "h":2332,       //高，单位为像素
        "size":388245       //图片大小
    }
}

3.语音消息

json{
    "from":"test1",
    "msgid":792479,
    "sendtime":1430967899646,   //发送时间ms
    "type":2,    //语音类型消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "dur":4551,     //语音持续时长ms
        "md5":"87b94a090dec5c58f242b7132a530a01",   //md5
        "url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9",    //生成的url
        "ext":"aac",        //语音消息格式，只能是aac格式
        "size":16420        //语音文件大小
    }
}

4.视频消息

json{
    "from":"test1",
    "msgid":792505,
    "sendtime":1430978424249,   //发送时间ms
    "type":3    //视频类型消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "dur":8003,     //视频持续时长ms
        "md5":"da2cef3e5663ee9c3547ef5d127f7e3e",   //md5
        "url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412",    //生成的url
        "w":360,    //宽
        "h":480,    //高
        "ext":"mp4",    //视频格式
        "size":16420    //视频文件大小
    }
}

5.地理位置消息

json{
    "from":"test1",
    "msgid":792501,
    "sendtime":1430978381896,   //发送时间ms
    "type":4,    //地理位置类型消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "title":"中国 浙江省 杭州市 网商路 599号",  //地理位置title
        "lng":120.1908686708565,        // 经度
        "lat":30.18704515647036         // 纬度
    }
}

6.文件消息

json{
    "from":"test1",
    "msgid":7925061,
    "sendtime":1430978435894,   //发送时间ms
    "type":6,    //文件消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
       "name":"BlizzardReg.ttf",   //文件名
       "md5":"79d62a35fa3d34c367b20c66afc2a500", //文件MD5
       "url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //文件URL
       "ext":"ttf",    //文件后缀类型
       "size":91680    //大小
    }
}

7.自定义消息

json{
    "from":"test1",
    "msgid":792506,
    "sendtime":1430978435894,   //发送时间ms
    "type":100, //第三方自定义消息
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{     //自定义的内容，需要符合json格式
        …
    }
}

8.群通知

json{
    "msgid ":278703112201,
    "from":"t4",                //通知发起者
    "sendtime":1430978435894,   //发送时间ms
    "type":5,    //群notifycation通知
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
       "tid":4153,     //群id
       "tname":"key1", //群名称 （某些操作会有）
       "ope":1,            //notify通知类型 （0:群拉人，1:群踢人，2:退出群，3:群信息更新，4:群解散，5:申请加入群成功，6:退出并移交群主，7:增加管理员，8:删除管理员，9:接受邀请进群，10：禁言群成员）
       "accids":["t2"],    //被操作的对象 （群成员操作时才有）
       "intro":"群介绍",  //（ope=3时群信息修改项）
       "announcement":"群公告", //（ope=3时群信息修改项）
       "joinmode":1,       //加入群的模式0不需要认证，1需要认证 ,（ope=3时群信息修改项）
       "config":"第三方服务器配制修改项",//（ope=3时群信息修改项）
       "updatetime":1432804852021 //通知后台更新时间 （群操作时有）
    }
}

9.聊天室通知

json{
  "msgid": "94b58bff-95ec-4cf9-91bd-4f6933d0ac3a",
  "from": "user01",
  "type": 5,
  "fromclienttype": 16, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
  "sendtime": 1567502401139,
  "body": {
    "id": 301,  //301: 成员进入聊天室,302: 成员离开聊天室,303: 成员被加黑,304: 成员被取消黑名单,305: 成员被设置禁言,306: 成员被取消禁言,307: 设置为管理员,308: 取消管理员,309: 成员设定为固定成员,310: 成员取消固定成员,312: 聊天室信息更新,313: 成员被踢,314: 新增临时禁言,315: 主动解除临时禁言,316: 成员更新聊天室内的角色信息,317: 麦序队列中有变更,318: 聊天室禁言,319: 聊天室解除禁言状态,320: 麦序队列中有批量变更
    "data": {
      "opeNick": "昵称01",
      "operator": "user01",
      "target": ["user01"],
      "tarNick": ["昵称01"],
      "ext":"自定义扩展信息"
    }
  }
}

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

单聊云端历史消息查询
功能描述
API 使用限制
URL
请求参数
示例
请求示例（curl）
返回示例
状态码
群聊云端历史消息查询
功能描述
API 使用限制
URL
请求参数
示例
请求示例（curl）
返回示例
状态码
聊天室云端历史消息查询
功能描述
API 使用限制
URL
请求参数
示例
请求示例（curl）
返回示例
状态码
删除聊天室云端历史消息
API 使用限制
URL
请求参数
示例
请求示例（curl）
返回示例
状态码
云端会话列表查询
功能描述
API 使用限制
URL
请求参数
示例
请求示例（curl）
返回示例
状态码
历史消息查询返回的消息格式说明
1.普通文本消息
2.图片消息
3.语音消息
4.视频消息
5.地理位置消息
6.文件消息
7.自定义消息
8.群通知
9.聊天室通知