Importing One-to-One Messages

Last updated: 2021-08-31 16:14:01

    Feature Description

    • This API imports one-to-one chat history to IM.
    • It imports your messages from other instant messaging platforms to Tencent Cloud IM.
    • It does not trigger a callback.
    • It deduplicates the imported messages based on the From_Account, To_Account, MsgSeq, MsgRandom, and MsgTimeStamp fields. When the values of all the five fields match their counterparts, the two messages are considered duplicates, regardless of their contents.
    • Imported messages will not be overwritten by the same messages from later imports.
    • For one-to-one messages, the MsgSeq field is specified by the user when the message is sent. Its value can be repeated. It is not generated by the backend and not globally unique. For group chat messages, the value of the MsgSeq field is generated by the backend, and each group maintains its respective MsgSeq which increases strictly from 1. For one-to-one messages, the historical messages of the same conversation are sorted by timestamp first, and then the historical messages of the same second are sorted by MsgSeq.

    API Calling Description

    Sample request URL

    https://xxxxxx/v4/openim/importmsg?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.

    Parameter Description
    https The request protocol is HTTPS, and the request method is POST.
    xxxxxx The country/region where your SDKAppID is located.
  • China: console.tim.qq.com
  • Singapore: adminapisgp.im.qcloud.com
  • v4/openim/importmsg Request API
    sdkappid SDKAppID assigned by the IM console when an app is created
    identifier App admin account. For more information, please see the App Admin section in Login Authentication.
    usersig Signature generated in the app admin account. For details on how to generate the signature, please see Generating UserSig.
    random A random 32-bit unsigned integer ranging from 0 to 4294967295

    Maximum call frequency

    200 calls per second

    Sample requests

    • Importing real-time messages
      {
       "SyncFromOldSystem": 1, // Imports real-time messages and marks them as unread
       "From_Account": "lumotuwe1", // Account of the sender
       "To_Account": "lumotuwe2", // Account of the recipient
       "MsgSeq": 827092, // Sequence number of the message
       "MsgRandom": 1287657, // A random number assigned to the message
       "MsgTimeStamp": 1556178721, // UNIX timestamp in seconds
       "MsgBody": [ // Message body. This is a text message
           {
               "MsgType": "TIMTextElem", // Text message element
               "MsgContent": {
                   "Text": "hi, beauty"
               }
           }
       ],
       "CloudCustomData": "your cloud custom data"
      }
      
    • Importing historical messages
      {
       "SyncFromOldSystem": 2, // Imports historical messages and marks them as read
       "From_Account": "lumotuwe1", // Account of the sender
       "To_Account": "lumotuwe2", // Account of the recipient
       "MsgSeq": 827092, // Sequence number of the message
       "MsgRandom": 1287657, // A random number assigned to the message
       "MsgTimeStamp": 1556178721, // UNIX timestamp in seconds
       "MsgBody": [ // Message body. This is a text message
           {
               "MsgType": "TIMTextElem", // Text message element
               "MsgContent": {
                   "Text": "hi, beauty" // Message content
               }
           }
       ],
       "CloudCustomData": "your cloud custom data"
      }
      

    Request fields

    Field Type Required Description
    SyncFromOldSystem Integer Yes Valid values: 1, 2
    1: imports real-time messages and marks them as unread.
    2: imports historical messages and marks them as read.
    From_Account String Yes UserID of the sender, which is used to specify the message sender
    To_Account String Yes UserID of the recipient
    MsgSeq Integer No Sequence number of the message. The backend will use this field to deduplicate messages and sort messages in the same second. For details, see Feature Description. If this field is left empty, the backend will enter a random number.
    MsgRandom Integer Yes A number randomly generated and assigned to the message. The backend will use this field to deduplicate messages. For details, see Feature Description.
    MsgTimeStamp Integer Yes UNIX timestamp in seconds. It marks the time when the message was sent and is used to deduplicate messages. For details, see Feature Description.
    MsgBody Object Yes Message body. For details on formats, please see Message Formats. (Note: a message can contain multiple message elements, in which case MsgBody is an array.)
    MsgType String Yes TIM message object type. Valid values:
    • TIMTextElem (text message)
    • TIMLocationElem (location message)
    • TIMFaceElem (emoji message)
    • TIMCustomElem (custom message)
    • TIMSoundElem (voice message)
    • TIMImageElem (image message)
    • TIMFileElem (file message)
    • TIMVideoFileElem (video message)
    MsgContent Object Yes Different message object types (MsgType) have different formats (MsgContent). For details, see Message Formats.
    CloudCustomData String No Custom message data. It is saved in the cloud and will be sent to the peer end. Such data can be pulled after the app is uninstalled and reinstalled.

    Sample response

    {
     "ActionStatus" : "OK",
     "ErrorInfo" : "",
     "ErrorCode" : 0
    }
    

    Response fields

    Field Type Description
    ActionStatus String Request result. OK: successful; FAIL: failed
    ErrorCode Integer Error code. 0: successful; other values: failed
    ErrorInfo String Error information

    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:

    Error Code Description
    90001 Failed to parse the JSON request. Make sure the format is valid.
    90002 The MsgBody in the JSON request does not meet message format requirements or it is not an array. For more information, see the Message Element TIMMsgElement section in Message Formats.
    90003 The To_Account field is missing in the JSON request or it is not a string.
    90005 The MsgRandom field is missing in the JSON request or it is not an integer.
    90006 The MsgTimeStamp field is missing in the JSON request or it is not an integer.
    90007 The MsgBody field in the JSON request is not an array. Change it to an array.
    90008 The From_Account field is missing in the JSON request or it is not an integer.
    90009 The request requires app admin permissions.
    90010 The JSON request does not meet message format requirements. For more information, see the Message Element TIMMsgElement section in Message Formats.
    90011 The number of recipients exceeded 500. Try to reduce the number of accounts in To_Account.
    90012 The account specified in To_Account does not exist or is not registered. Make sure the account has been imported to IM and is correct.
    90026 The offline retention time of the message is incorrect. Messages cannot be retained offline for more than 7 days.
    90030 The SyncFromOldSystem field is missing in the JSON request or it is not an integer.
    90048 The requested account does not exist.
    90992 Internal service error. Try again. If this error code is returned for all requests and third-party callback is enabled, make sure the app server returns the callback results to the IM backend normally.
    91000 Internal service error. Try again.
    93000 The JSON packet exceeds the maximum size of 8 KB.

    Debugging Tool

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

    References
    Importing Group Messages (v4/group_open_http_svc/import_group_msg)