Feature Description

• This API is used by the app admin to query the history of a one-to-one conversation based on a specified time range.
• The one-to-one conversation to be queried is specified by From_Account and To_Account in the request. The query result contains the messages sent between both parties. The specific sender and recipient of each message are specified by From_Account and To_Account respectively.
• In most cases, if you exchange the values of From_Account and To_Account in the request, the query result will remain unchanged. However, to query a message sent via the v4/openim/sendmsg API or v4/openim/batchsendmsg API, if you set SyncOtherMachine to 2, you must specify From_Account and To_Account correctly.
  For example, you have called the v4/openim/sendmsg API to specify account A to send a message to account B and set SyncOtherMachine to 2. To query the message by calling this API, you must set From_Account to account B and To_Account to account A.
• The query result contains recalled messages indicated by the MsgFlagBits field.
• If you want to recall a message, you can first call this API to query the MsgKey of the message and then call the v4/openim/admin_msgwithdraw API to recall the message.
• The time range of message records that can be queried depends on the roaming message storage period, which is 7 days by default. You can modify the message roaming period via the IM console. Extending the message roaming period is a value-added service. For more information, see Roaming Message Storage.
• If the total size of the messages within the requested time range exceeds the upper size limit (currently 13 KB) of the response, continued pulling is needed. You can see whether all the requested messages have been pulled by checking the Complete field in the response.

API Calling Description

Sample request URL

https://xxxxxx/v4/openim/admin_getroammsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table only describes the modified parameters when this API is called. For more information on other parameters, please see RESTful API Overview.

Maximum calling frequency

200 calls per second

Sample requests and responses

For example, user1 and user2 had a conversation, and you want to query the conversation history from 2020-03-20 10:00:00 to 2020-03-20 11:00:00.

Sample request

{
   "From_Account":"user2",
   "To_Account":"user1",
   "MaxCnt":100,
   "MinTime":1584669600,
   "MaxTime":1584673200
}

Sample response

{
   "ActionStatus": "OK",
   "ErrorInfo": "",
   "ErrorCode": 0,
   "Complete": 0,
   "MsgCnt": 12, //12 messages were returned for the pull.
   "LastMsgTime": 1584669680,
   "LastMsgKey": "549396494_2578554_1584669680",
   "MsgList": [
       {
           "From_Account": "user1",
           "To_Account": "user2",
           "MsgSeq": 549396494,
           "MsgRandom": 2578554,
           "MsgTimeStamp": 1584669680,
           "MsgFlagBits": 0,
           "MsgKey": "549396494_2578554_1584669680",
           "MsgBody": [
               {
                   "MsgType": "TIMTextElem",
                   "MsgContent": {
                       "Text": "msg 1"
                   }
               }
           ],
           "CloudCustomData": "your cloud custom data"
       },
       {
           "From_Account": "user2",
           "To_Account": "user1",
           "MsgSeq": 1054803289,
           "MsgRandom": 7201,
           "MsgTimeStamp": 1584669689,
           "MsgFlagBits": 0,
           "MsgKey": "1054803289_7201_1584669689",
           "MsgBody": [
               {
                   "MsgType": "TIMTextElem",
                   "MsgContent": {
                       "Text": "msg 2"
                   }
               }
           ],
           "CloudCustomData": "your cloud custom data"
       },
       { ... } // The remaining 10 messages are not listed for simplicity.
   ]
}

In the response, "Complete": 0 indicates that not all messages generated within the time range have been pulled. Therefore, continued pulling is required.
In the continued pulling request, the value of MaxTime must be changed to the value of LastMsgTime in the response, and the LastMsgKey in the response must be entered, as shown below:

Sample continued pulling request

{
   "From_Account":"user2",
   "To_Account":"user1",
   "MaxCnt":100,
   "MinTime":1584669600,
   "MaxTime":1584669680,
   "LastMsgKey": "549396494_2578554_1584669680"
}

Sample response

{
   "ActionStatus": "OK",
   "ErrorInfo": "",
   "ErrorCode": 0,
   "Complete": 1,
   "MsgCnt": 5, // Five messages were returned for the pull.
   "LastMsgTime": 1584669601,
   "LastMsgKey": "1456_23287_1584669601",
   "MsgList": [
       {
           "From_Account": "user1",
           "To_Account": "user2",
           "MsgSeq": 1456,
           "MsgRandom": 23287,
           "MsgTimeStamp": 1584669601,
           "MsgFlagBits": 0,
           "MsgKey": "1456_23287_1584669601",
           "MsgBody": [
               {
                   "MsgType": "TIMTextElem",
                   "MsgContent": {
                       "Text": "msg 13"
                   }
               }
           ],
           "CloudCustomData": "your cloud custom data"
       },
       {
           "From_Account": "user2",
           "To_Account": "user1",
           "MsgSeq": 9806,
           "MsgRandom": 14,
           "MsgTimeStamp": 1584669602,
           "MsgFlagBits": 0,
           "MsgKey": "9806_14_1584669602",
           "MsgBody": [
               {
                   "MsgType": "TIMTextElem",
                   "MsgContent": {
                       "Text": "msg 14"
                   }
               }
           ],
           "CloudCustomData": "your cloud custom data"
       },
       { ... } // The remaining three messages are not listed for simplicity.
   ]
}

In the response, "Complete": 1 indicates that all messages generated within the time range have been pulled.
If the value of Complete in the response is 0, you need to continue pulling messages until the value of Complete becomes 1.

Request fields

Sample responses

• Response to a successful request

  {
   "ActionStatus": "OK",
   "ErrorInfo": "",
   "ErrorCode": 0,
   "Complete": 1,
   "MsgCnt": 1,
   "LastMsgTime": 1584669680,
   "LastMsgKey": "549396494_2578554_1584669680",
   "MsgList": [
       {
           "From_Account": "user1",
           "To_Account": "user2",
           "MsgSeq": 549396494,
           "MsgRandom": 2578554,
           "MsgTimeStamp": 1584669680,
           "MsgFlagBits": 0,
           "MsgKey": "549396494_2578554_1584669680",
           "MsgBody": [
               {
                   "MsgType": "TIMTextElem",
                   "MsgContent": {
                       "Text": "1"
                   }
               }
           ],
           "CloudCustomData": "your cloud custom data"
       }
   ]
  }
  

• Response to a failed request

  {
   "ActionStatus": "FAIL", 
   "ErrorInfo": "Fail to Parse json data of body, Please check it", 
   "ErrorCode": 90001
  }
  

Response fields

Error Codes

The returned HTTP status code for this API is always 200 unless a network error (such as error 502) occurs. The specific error code and details can be found in the response fields ErrorCode and ErrorInfo respectively.
For public error codes (60000 to 79999), please see Error Codes.
The following table describes the error codes specific to this API:

API Debugging Tool

Use the RESTful API online debugging tool to debug this API.

References

• Sending One-to-One Messages to One User (v4/openim/sendmsg)
• Sending One-to-One Messages to Multiple Users (v4/openim/batchsendmsg)
• Recalling One-to-One Messages (v4/openim/admin_msgwithdraw)