History - Instant Messaging

Documentation

Instant Messaging

Server API

History

Update time: 2022/11/25 08:16:21

Message history

Querying message history of one-to-one chat on cloud

When querying one-to-one chat message history stored in CommsEase server, only messages within the valid time can be retrieved.

When querying peer-to-peer messages based on time period, up to 100 messages can be returned at a time;
Do not support paging. A third party should query messages by time period.
Begin time should be earlier than end time. Otherwise it will return {"desc": "bad time", "code": 414}.

Request URL

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

For information about headers in the request, see Overview

Parameters

Parameter	Type	Required	Description
from	String	Yes	Sender accid
to	String	Yes	Receiver accid
begintime	String	Yes	Start time, in milliseconds
endtime	String	Yes	Cut-off time, in milliseconds
limit	int	Yes	The maximum number of messages for this query (up to 100), parameter error would occur if the number is less than or equal to 0, or greater than 100
reverse	int	No	1 indicates arranged in ascending order of time, and 2 indicates arranged in descending order of time. Otherwise 414 parameter error would occur, the default is to arrange in descending order, that is, the message with the latest timestamp ranks first.
type	String	No	Query messages of multiple specified types, each type is separated by "," from the next, not setting this parameter indicates to query all types of messages, format examples: 0,1,2,3 Types supported: 1: Image, 2: Audio, 3: Video, 4: Location, 5: Notification, 6: File, 10: Reminder, 11: Robot, 100: Custom

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'begintime=1443599631111&endtime=1443599639999&from=zhangsan&to=lisi&limit=50' 'https://api-sg.netease.im/nimserver/history/querySessionMsg.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
   "code":200,
   "size":xxx,//number of all messages
   "msgs":[msg1,msg2,···,msgn] //Message collection, JSONArray
}

Note: see the message format returned by message history query for examples of messages returned by query.

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

Querying message history of team chat on cloud

Request URL

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

For information about headers in the request, see Overview.

When querying team chat messages history stored in CommsEase server, only messages within the saving time can be retrieved.

When querying query team messages based on time period, up to 100 messages can be returned at a time;
Do not support paging. A third party should query messages by time period.
Begintime should be earlier than endtime. Otherwise it will return {"desc": "bad time", "code": 414}.

Parameters

Parameter	Type	Required	Description
tid	String	Yes	Team ID
accid	String	Yes	Query accid corresponding to the user.
begintime	String	Yes	Start time, in milliseconds
endtime	String	Yes	Cut-off time, in milliseconds
limit	int	Yes	The maximum number of messages for this query (up to 100), parameter error would occur if the number is less than or equal to 0, or greater than 100
reverse	int	No	1 indicates arranged in ascending order of time, and 2 indicates arranged in descending order of time. otherwise 414 parameter error would occur. The default is to arrange in descending order, that is, the message with the latest timestamp ranks first.
type	String	No	Query messages of multiple specified types, each type is separated by "," from the next, not setting this parameter indicates to query all types of messages, format examples: 0,1,2,3 Types supported: 1: Image, 2: Audio, 3: Video, 4: Location, 5: Notification, 6: File, 10: Reminder, 11: Robot, 100: Custom
checkTeamValid	Boolean	No	true (default): to check if the team is valid, and if the accid belongs to a valid team member. If it is set to false, it indicates only checking if the team exists and if the accid belongs to a user who was once a team member.

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'begintime=1443599631111&endtime=1443599639999&tid=1513535&accid=zhangsan&limit=50' 'https://api-sg.netease.im/nimserver/history/queryTeamMsg.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "size":xxx,//Total number of messages
  "msgs":[msg1,msg2,···,msgn] //Message collection, JSONArray.
}

Note: see the message format returned by message history query for examples of messages returned by query.

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

Querying message history of chat room on cloud

Request URL

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

For information about headers in the request, see Overview.

1. This interface has a rate limit limit, and can be called no more than 1,200 times per minute

Parameters

Parameter	Type	Required	Description
roomid	long	Yes	Chat room ID
accid	String	Yes	User account
timetag	long	Yes	The timestamp anchor for the query, containing 13 bits. If reverse=1, timetag is the starting timestamp, if reverse=2, timetag is the ending timestamp
limit	int	Yes	The maximum number of messages for this query (up to 200), parameter error would occur if the number is less than or equal to 0, or greater than 200
reverse	int	No	1 indicates arranged in ascending order of time, and 2 indicates arranged in descending order of time. otherwise 414 parameter error would occur. Default is 2, which indicates arranged in descending order of time
type	String	No	Query messages of multiple specified types, each type is separated by "," from the next, not setting this parameter indicates to query all types of messages. Format examples: 0,1,2,3 Supported message types: 0: Text, 1: Image, 2: Audio, 3: Video, 4: Location, 5: Notification, 6: File, 10: Reminder, 11: Robot message, 100: Custom message. Each type and the next are separated with commas.

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 12345" -H "CurTime: 1459154905" -H "CheckSum: 8d3ef001b160bda737c779d75d906e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=123456&accid=zhangsan&timetag=1471234567812&limit=20&reverse=2' "https://api-sg.netease.im/nimserver/history/queryChat roomMsg.action"

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "size":xxx,//Total number of messages
    "msgs":[msg1,msg2,···,msgn] //Message collection, JSONArray.
}

Note: see the message format returned by message history query for examples of messages returned by query.

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

Message format returned by message history query

Note:

msgid (long type) is the message server ID, and msgidclient (string type) is the message client ID.
When the message is a chat room message, there is only msgid, no msgidclient, and the msgid is string. For example, "msgid": "d864".

1. Ordinary text message

json{
    "from":"test1",
    "msgid":792478,
    "sendtime":1430967883307,
    "type":0,// Text message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "msg":"hahaha"//Message content
     }
}

2. Image message

json{
    "from":"test1",
    "msgid":792502,
    "sendtime":1430978396680, //send time in ms
    "type":1,  //image message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "name":"Image sent on 2015-05-07 13:59",    //image name
        "md5":"9894907e4ad9de4678091277509361f7",  //image file md5
        "url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e",  //generated url
        "ext":"jpg",    //image suffix
        "w":6814,    //width
        "h":2332,    //Hight
        "size":388245    //Image size
    }
}

3. Voice message

json{
    "from":"test1",
    "msgid":792479,
    "sendtime":1430967899646, //send time in ms
    "type":2,  //audio message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "dur":4551, //audio duration in ms
        "md5":"87b94a090dec5c58f242b7132a530a01",  //md5
        "url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9",    //generated url
        "ext":"aac",   //audio message format, limited to aac
        "size":16420  //audio file size
    }
}

4. Video message

json{
    "from":"test1",
    "msgid":792505,
    "sendtime":1430978424249, //send time in ms
    "type":3,  //video message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "dur":8003, //video duration in ms
        "md5":"da2cef3e5663ee9c3547ef5d127f7e3e",  //md5
        "url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412", //generated url
        "w":360,    //width
        "h":480,    //Hight
        "ext":"mp4", //Video format
        "size":16420 //Video file size
    }
}

5. Geolocation message

json{
    "from":"test1",
    "msgid":792501,
    "sendtime":1430978381896, //send time in ms
    "type":4,  //geolocation message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
        "title":"No.599, Wangshang Road, Hangzhou City, Zhejiang Province, China", //Location title
        "lng":120.1908686708565, // Longitude
        "lat":30.18704515647036 // Latitude
    }
}

6. File message

json{
    "from":"test1",
    "msgid":7925061,
    "sendtime":1430978435894, //send time in ms
    "type":6, //file message
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
       "name":"BlizzardReg.ttf", //file name
       "md5":"79d62a35fa3d34c367b20c66afc2a500", //file MD5
       "url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //file URL
       "ext":"ttf", //file suffix type
       "size":91680 //size
    }
}

7. Custom message

json{
    "from":"test1",
    "msgid":792506,
    "sendtime":1430978435894, //Send time in ms.
    "type":100, //Third-party custom message.
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{ //Customized content, which needs to conform to json format.
        …
    }
}

8. Team notification

json{
    "msgid ":278703112201,
    "from":"t4", //notification initiator
    "sendtime":1430978435894, //send time in ms
    "type":5, //notification of team notification
    "fromclienttype": 2, //1：android、2:iOS、4：PC、16:WEB、32:REST、64:MAC
    "msgidclient": "3bfd9660665a14bce4ec95e1b1d3afed",
    "body":{
       "tid":4153, //Team ID
       "tname":"key1", //Team name (for certain operations)
       "ope":1, //notify the notification type (0: add to team, 1: kick from team, 2: leave the team, 3: Team profile update, 4: dismiss team, 5: joining application passed, 6: leave the team and assign team owner, 7: Add an administrator, 8: remove administrator, 9: accept the invitation to join)
       "accids":["t2"], //target object of the operation (only for targeted team members)
       "intro":"team introduction", //(Team profile change item when ope=3)
       "announcement":"team announcement", //(Team profile change item when ope=3)
       "joinmode":1, //team joining mode 0 authentication not required, 1 authentication required, (Team profile change item when ope=3)
       "config":"configuration change item for third-party server",//(Team profile change item when ope=3)
       "updatetime":1432804852021 //Notify update time to background (only available during team operation)
    }
}

9. Chat room notification

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: Member joining chat room, 302: Member leaving chat room, 303: Member blocklisted, 304: Member removed from blocklist, 305: Member muted, 306: Member unmuted, 307: Set as administrator, 308: Cancel "set as administrator", 309: Set as fixed member, 310: Unfix member, 312: Chat room information update, 313: Member kicked out, 314: New temporary mute, 315: Actively cancel temporary mute, 316: Chat room role information updated by member, 317: Change in mic-position queue, 318: Mute chat room, 319 Unmute chat room, 320 Batch changes in mic-position queue
    "data": {
      "opeNick": "display name 01",
      "operator": "user01",
      "target": ["user01"],
      "tarNick": ["display name 01"],
      "ext":"Custom extention information"
    }
  }
}

Deleting message history of a chat room on cloud

Deletes message history of a chat room on cloud

Request URL

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

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
roomid	long	Yes	Chat room ID
fromAcc	String	Yes	accid of the message sender
msgTimetag	long	Yes	Message timestamp, in milliseconds, the parameter should be set as timestamp in the original message

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 12345" -H "CurTime: 1459154905" -H "CheckSum: 8d3ef001b160bda737c779d75d906e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=123456&fromAcc=zhangsan&msgTimetag=1491234567812' "https://api-sg.netease.im/nimserver/chat room/deleteHistoryMessage.action"

Response

The data returned in the HTTP response is in JSON format.

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

Valid status codes

200, 403, 404, 414, 416, 431, 500, 514

See Status codes .

1. When querying user login and logout records based on time period, up to 100 messages can be returned at a time; 2. Do not support paging. A third party should query messages by time period.
3. This interface should be enabled upon approval by the account administrator. After that, you can query relevant messages. Do not support query of login/logout records before enabling.

Request URL

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

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	accid of the user requesting query
begintime	String	Yes	Start time, in milliseconds
endtime	String	Yes	Cut-off time, in milliseconds
limit	int	Yes	The maximum number of messages for this query (up to 100), parameter error would occur if the number is less than or equal to 0, or greater than 100
reverse	int	No	1 indicates arranged in ascending order of time, and 2 indicates arranged in descending order of time. otherwise 414 parameter error would occur. Sorted in descending order by default

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=11111&begintime=1448948957018&endtime=1448955895518&limit=50' 'https://api-sg.netease.im/nimserver/history/queryUserEvents.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{ 
  "code":200, 
  "size":xxx,//total number of records 
  "events": 
  [ 
    { 
      "accid":"t4", //user accid 
      "timestamp":1452058433412, //occurrence time, in ms 
      "eventType":2, //2 indicates login, 3 indicates logout 
      "clientIp":"8.8.8.8", //user clientip 
      "sdkVersion":12, //SDK version 
      "clientType":"IOS", //client 
      "deviceId":"a4789a14-8ef3-4a3d-9ab3-8fdc9e54f112", //Device ID, optional field
      "customTag":"Custom tag", //custom tag set upon logging in, optional field
      "code":200 //Login success status, 200 indicates success 
    }, 
    { 
      "accid":"t4", //user accid 
      "timestamp":1452058381580, //occurrence time, in ms 
      "eventType":3, //2 indicates login, 3 indicates logout 
      "clientIp":"8.8.8.8", //user clientip 
      "sdkVersion":12, //sdk version 
      "clientType":"IOS", //client 
      "deviceId":"a4789a14-8ef3-4a3d-9ab3-8fdc9e54f112", //device ID, optional field
      "customTag":"Custom tag", //custom tag set upon logging in, optional field
      "code":200 //Login success status, 200 indicates success 
    } 
  ] 
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

Query multiple broadcast messages at a time

Queries multiple broadcast messages at a time.

Request URL

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

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
broadcastId	long	No	Start ID of the query, 0 indicates to query the latest x entries, wherein x indicates the limit. The default is 0.
limit	int	No	Number of query entries, 100 in maximum. The default is 100.
type	long	No	Type of query (range), 1 indicates all, 2 indicates those with offline storage, and 3 indicates those without offline storage. The default is 1.

curl request example

curlcurl -X POST -H "appkey: fe416640c8e8a72734219e1847ad2547" -H "nonce: 12345" -H "curtime: 1459154905" -H "checksum: 8d3ef001b160bda737c779d75d906e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'type=1' "https://api-sg.netease.im/nimserver/history/queryBroadcastMsg.action"

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "msgs": [
        {
            "expireTime": 1505502793520,
            "body": "hello world 1",
            "createTime": 1505466793520,
            "isOffline": true,
            "broadcastId": 48174937359009,
            "targetOs": [
                "ios",
                "pc",
                "aos"
            ]
        },
        {
            "expireTime": 1505502292394,
            "body": "hello world 2",
            "createTime": 1505466292394,
            "isOffline": true,
            "broadcastId": 48174921356545,
            "targetOs": [
                "pc",
                "aos",
                "ios"
            ]
        }
    ]
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

Querying a broadcast message

Queries a broadcast message.

Request URL

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

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
broadcastId	long	Yes	Broadcast message ID, unique within the app.

curl request example

curlcurl -X POST -H "appkey: fe416640c8e8a72734219e1847ad2547" -H "nonce: 12345" -H "curtime: 1459154905" -H "checksum: 8d3ef001b160bda737c779d75d906e48e75fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'broadcastId=123456' "https://api-sg.netease.im/nimserver/history/queryBroadcastMsgById.action"

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "msg": {
        "expireTime": 1505502793520,
        "body": "hello world",
        "createTime": 1505466793520,
        "isOffline": true,
        "broadcastId": 48174937359009,
        "targetOs": [
            "ios",
            "pc",
            "aos"
        ]
    }
}

Valid status codes

200、403、404、414、416、431、500

See Status codes .

Was this page helpful?

Yes

Message history
Querying message history of one-to-one chat on cloud
Request URL
Parameters
curl request example
Response
Valid status codes
Querying message history of team chat on cloud
Request URL
Parameters
curl request example
Response
Valid status codes
Querying message history of chat room on cloud
Request URL
Parameters
curl request example
Response
Valid status codes
Message format returned by message history query
1. Ordinary text message
2. Image message
3. Voice message
4. Video message
5. Geolocation message
6. File message
7. Custom message
8. Team notification
9. Chat room notification
Deleting message history of a chat room on cloud
Request URL
Parameters
curl request example
Response
Valid status codes
Querying user login and logout records
Request URL
Parameters
curl request example
Response
Valid status codes
Query multiple broadcast messages at a time
Request URL
Parameters
curl request example
Response
Valid status codes
Querying a broadcast message
Request URL
Parameters
curl request example
Response
Valid status codes

Message history

Querying message history of one-to-one chat on cloud

Request URL

Parameters

curl request example

Response

Valid status codes

Querying message history of team chat on cloud

Request URL

Parameters

curl request example

Response

Valid status codes

Querying message history of chat room on cloud

Request URL

Parameters

curl request example

Response

Valid status codes

Message format returned by message history query

1. Ordinary text message

2. Image message

3. Voice message

4. Video message

5. Geolocation message

6. File message

7. Custom message

8. Team notification

9. Chat room notification

Deleting message history of a chat room on cloud

Request URL

Parameters

curl request example

Response

Valid status codes

Querying user login and logout records

Request URL

Parameters

curl request example

Response

Valid status codes

Query multiple broadcast messages at a time

Request URL

Parameters

curl request example

Response

Valid status codes

Querying a broadcast message

Request URL

Parameters

curl request example

Response

Valid status codes