Importing Group Messages

Last updated: 2020-03-11 17:42:44

PDF

Feature Description

  • This API is used to import group messages without triggering callbacks or delivering notifications.
  • When your app needs to be migrated to Instant Messaging (IM) from another instant messaging system, you can use this API to import existing group message data.

API Calling Description

Applicable group types

Group Type Support This RESTful API
Private Yes
Public Yes
ChatRoom Yes
AVChatRoom No (see description below)
BChatRoom No (see description below)

IM provides the preceding five built-in group types. For details, see Group Systems.

AVChatRoom and BChatRoom groups do not support importing group messages. If you attempt to import group messages for these groups, error 10007 returns. This feature is not provided for both types of groups because they normally do not require historical messages.

Request URL example

https://console.tim.qq.com/v4/group_open_http_svc/import_group_msg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table lists and describes only the parameters to be modified when this API is called. For details on other parameters, see RESTful API Overview.

Parameter Description
v4/group_open_http_svc/import_group_msg The request API.
sdkappid The SDKAppID assigned by the IM console when an app is created.
identifier This must be the app admin account. For details, see App Admins.
usersig The signature generated by the app admin account. For details, see Generating UserSig.
random Enter a random 32-bit unsigned integer ranging from 0 to 4294967295.

Maximum calling frequency

The maximum calling frequency is 200 times per second.

Request packet example

Imports group messages in batches. A single request can import up to 20 messages.
After messages are imported through this API, the unread message count for all members will be 0. If you want to retain the unread message count, you need to import group members or set the unread message count for members after importing all messages.
The messages must be imported in ascending order by timestamp, and the timestamp of imported messages must be earlier than the current time and later than the group creation time and the creation time of the latest message in the group. Otherwise, the import will fail.

{
    "GroupId": "@TGS#2C5SZEAEF",
    "MsgList": [
        {
            "From_Account": "leckie", // Specified message sender
            "SendTime":1448357837,
            "Random": 8912345, // Message random number (optional)
            "MsgBody": [ // Message body, which consists of an element array. For details, see the TIMMessage message object.
                {
                    "MsgType": "TIMTextElem", // Text
                    "MsgContent": {
                        "Text": "red packet"
                    }
                },
                {
                    "MsgType": "TIMFaceElem", // Emoji
                    "MsgContent": {
                        "Index": 6,
                        "Data": "abc\u0000\u0001"
                    }
                }
            ]
        },
        {
            "From_Account": "peter", // Specified message sender
            "SendTime":1448357837,
            "MsgBody": [ // Message body, which consists of an element array. For details, see the TIMMessage message object.
                {
                    "MsgType": "TIMTextElem", // Text
                    "MsgContent": {
                        "Text": "red packet"
                    }
                }
            ]
        }

    ]
}

Request packet fields

Field Type Attribute Description
GroupId String Required The ID of the group to which messages are to be imported.
MsgList String Required The list of messages to be imported.
From_Account String Required The specified message sender.
SendTime Integer Required The message sending time.
Random Integer Required A 32-bit random number. If the random numbers of two messages created within five minutes are the same, the later message will be discarded as a repeated message.
MsgBody Object Required The TIM message. For details, see TIMMsgElement Object Definitions.
MsgType String Required The TIM message object type. Supported message objects are TIMTextElem (text messages), TIMFaceElem (emoji messages), TIMLocationElem (location messages), and TIMCustomElem (custom messages).
MsgContent Object Required The TIM message object. For details, see TIMMsgElement Object Definitions.

Response packet example

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "ImportMsgResult": [
        {
            "Result": 0,
            "MsgSeq": 1,
            "MsgTime": 1449454106
        },
        {
            "Result": 0,
            "MsgSeq": 2,
            "MsgTime": 1449454116
        },
        {
            "Result": 0,
            "MsgSeq": 3,
            "MsgTime": 1449454106
        },
        {
            "Result": 0,
            "MsgSeq": 4,
            "MsgTime": 1449454116
        }
    ]
}

Response packet fields

Field Type Description
ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
ErrorInfo String Error information.
ErrorCode Integer The error code. 0: succeeded. Other values: failed.
ImportMsgResult Array The message import result.
Result Integer The result of importing a single message.
  • 0: the message was imported successfully.
  • 10004: the sending time of the message is invalid.
  • 80001: the message contains illegal words and therefore cannot be stored.
  • 80002: the message content exceeds the maximum length of 8,000 bytes. To correct it, adjust the message length.
MsgSeq Integer The sequence number allocated to the message.
MsgTime Integer The message timestamp.

Error Codes

Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information, respectively.
For common error codes (60000 to 79999), see Error Codes.
The following table describes the error codes specific to this API.

Error Code Description
10004 A parameter is invalid. To correct it, check whether request parameters are correct based on the error description.
10007 Operation permissions are insufficient. For example, an ordinary member in a public group attempts to remove a member from the group, but only the app admin has the permission to do so.
10010 The group does not exist or has been dismissed.
10015 The group ID is invalid. To correct it, check whether the group ID is correct.
10020 The message content is too long. Currently, the maximum message length is 8,000 bytes. To correct it, adjust the message length.

API Commissioning Tool

Use the online commissioning tool for RESTful APIs to commission this API.

References