Getting Historical Group Messages

Last updated: 2020-07-22 09:47:50


    • IM group messages are sorted by Seq, and Seq is allocated according to group messages received by the server. The value of Seq is greater for group messages sent earlier and smaller for group messages sent later.
    • To pull the full messages of a group, you do not need to specify the pull Seq during the initial pull. Instead, the server automatically returns the latest message. For subsequent pulls, enter the previously returned smallest Seq value minus 1 for the pull Seq.
    • If the value of IsPlaceMsg in the returned message is 1, it indicates that the message with this Seq has expired, failed to be stored, or was deleted.

    Feature Description

    The app admin can pull roaming messages of a group through this API.

    API Invocation Description

    Applicable group types

    Group Type Support this RESTful API
    Private Yes
    Public Yes
    ChatRoom Yes
    AVChatRoom No (see the note below)
    BChatRoom No (see the note below)

    IM supports the preceding five group types. For details on these types, see Group Systems.

    Roaming messages do not exist for AVChatRoom and BChatRoom chat rooms.

    Request URL example

    Request parameters

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

    Parameter Description
    v4/group_open_http_svc/group_msg_get_simple Request API
    sdkappid 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 invocation frequency

    The maximum invocation frequency is 200 times per second.

    Request packet examples

    • Basic format
      Pull roaming messages of a group. This returns the most recent ReqMsgNumber group messages.

        "GroupId": "@TGS#15ERQPAER",    // ID of the group whose messages are pulled
        "ReqMsgNumber": 2      // Number of messages to be pulled
    • Pulling by Seq
      Pull the roaming messages of a group based on the specified Seq.
      The Seq of the returned message is less than or equal to ReqMsgNumber of ReqMsgSeq.

        "GroupId": "@TGS#15ERQPAER",
        "ReqMsgSeq": 7803321,       // Indicates the maximum Seq of the request message. Messages with a Seq less than or equal to ReqMsgSeq will be returned.
        "ReqMsgNumber": 2

    Request packet fields

    Field Type Attribute Description
    GroupId String Required The ID of the group whose roaming messages will be pulled.
    ReqMsgNumber Integer Required The number of pulled roaming messages. At present, a maximum of 20 roaming messages are returned for a single request. Therefore, we recommend that the value is less than or equal to 20.
    ReqMsgSeq Integer Required The maximum Seq of pulled messages.

    Response packet example

        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "GroupId": "@TGS#15ERQPAER",
        "IsFinished": 1,
        "RspMsgList": [
                "From_Account": "144115197276518801",
                "IsPlaceMsg": 0,
                "MsgBody": [
                        "MsgContent": {
                            "Data": "\b\u0001\u0010\u0006\u001A\u0006MaoTong",
                            "Desc": "MIF",
                            "Ext": ""
                        "MsgType": "TIMCustomElem"
                        "MsgContent": {
                            "Data": "",
                            "Index": 15
                        "MsgType": "TIMFaceElem"
                "MsgRandom": 51083293,
                "MsgSeq": 7803321,
                "MsgTimeStamp": 1458721802
                "From_Account": "144115198339527735",
                "IsPlaceMsg": 0,
                "MsgBody": [
                        "MsgContent": {
                            "Data": "\b\u0001\u0010\u0006\u001A\u000FWatermelon Girl.",
                            "Desc": "MIF",
                            "Ext": ""
                        "MsgType": "TIMCustomElem"
                        "MsgContent": {
                            "Text": "Escalate"
                        "MsgType": "TIMTextElem",
                "MsgRandom": 235168582,
                "MsgSeq": 7803320,
                "MsgTimeStamp": 1458721797

    Response packet fields

    Field Type Description
    ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
    ErrorInfo String The error information.
    ErrorCode Integer The error code. 0: succeeded. Others: failed.
    GroupId String The group ID in the request.
    IsFinished Integer Whether all messages within the request range are returned.
  • If not all messages are returned because the messages are too long or the range is too wide (greater than 20), the value is 0.
  • If the messages are too long or the range is too wide (greater than 20) and all the messages expire, the value is 2.
  • RspMsgList Array The list of returned messages.
    From_Account String The message sender.
    IsPlaceMsg Integer Whether a message is empty. After a message is deleted or expires, MsgBody is empty and the value of this field is 1.
    MsgRandom Integer A message random value for deduplicating messages. When the client sends a message, a value is entered. If no value is entered, the server automatically generates one.
    MsgSeq Integer The message Seq for identifying a unique message. A smaller value indicates an earlier sent message.
    MsgTimeStamp Integer The message sending timestamp, which follows the server time system.
    MsgBody Array Message content. For details, see MsgBody Description.

    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
    10002 An internal server error occurred. In this case, try again.
    10003 A request command keyword is invalid.
    10004 A parameter is invalid. In this case, check whether the request is correct based on the error description.
    10007 Operation permissions are insufficient. For example, a common member in a public group tries to delete other users, but only the app admin can do so.
    10010 The group does not exist or has been dismissed.
    10015 The group ID is invalid. In this case, check whether the group ID is correct.

    API Commissioning Tool

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


    Setting the count of unread messages for members (v4/group_open_http_svc/set_unread_msg_num)

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback