API 参考
圈组

云端历史消息查询

更新时间: 2024/07/17 17:57:35

网易云信 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 的消息。
toString接收者accid 实际查询结果包含双向的消息,不仅包含 from 发送给 to 的消息,也包含 to 发给 from 的消息。
begintimeString开始时间,毫秒级
endtime String截止时间,毫秒级
limit int本次查询的消息条数上限(最多100条),小于等于0,或者大于100,会提示参数错误
reverse int1按时间正序排列,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
accidString查询用户对应的accid.
begintimeString开始时间,毫秒级
endtime String截止时间,毫秒级
limit int本次查询的消息条数上限(最多100条),小于等于0,或者大于100,会提示参数错误
reverse int1按时间正序排列,2按时间降序排列。其它返回参数414错误。默认是按降序排列,即时间戳最晚的消息排在最前面。
type String查询指定的多个消息类型,类型之间用","分割,不设置该参数则查询全部类型消息格式示例: 0,1,2,3
类型支持:0:文本,1:图片,2:语音,3:视频,4:地理位置,5:通知,6:文件,10:提示,11:Robot,100:自定义
checkTeamValidBoolean 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 int1按时间正序排列,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.聊天室通知