Docs Overview/
Pulling Historical Official Account Messages/

Pulling Historical Official Account Messages

Background

Chat's Official Account messages are sorted by Seq, which is assigned according to the order in which the server receives the Official Account messages. Earlier messages have a smaller Seq, and later ones have a larger Seq.
Chat generates a MsgKey for each Official Account message, in the format of "Seq_1_ServerTime".
If users want to pull all messages from a Official Account, they need to provide the LastMsgKey of the message. There is no need to fill in the LastMsgKey for the first pull, as the Server will automatically return the latest messages. For subsequent pulls, fill in the LastMsgKey with the LastMsgKey returned from the last request.
If the returned message's IsPlaceMsg is 1, it means that the message of this Seq has either expired, failed to store, or has been deleted.

Feature Overview

App administrators can use this interface to pull historical messages from the official account.

API Calling Description

Sample request URL

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

Request parameters

The table below only lists the parameters modified when calling this API and their descriptions. For more details on the parameters, please refer to RESTful API Overview.
Parameter
Description
xxxxxx
The dedicated domain for the country/region where your SDKAppID is located:
China: console.tim.qq.com
Singapore :adminapisgp.im.qcloud.com
Seoul : adminapikr.im.qcloud.com
Frankfurt :adminapiger.im.qcloud.com
Silicon Valley :adminapiusa.im.qcloud.com
Jakarta :adminapiidn.im.qcloud.com
v4/official_account_open_http_svc/official_account_msg_get_simple
Request API
sdkappid
SDKAppID assigned by the Chat console when an app is created
identifier
You must be an App admin account. For more details, see App Admins
usersig
The Signature generated by the App admin account. For details, see Generating UserSig
random
A random 32-bit unsigned integer ranging from 0 to 4294967295
contenttype
Request format fixed value: json

Maximum calling frequency

200 queries/sec.

Sample request packets

Basic form Pulling the official account's historical messages returns the latest ReqMsgNumber messages from the official account.
{
  "Official_Account": "@TOA#_15ERQPAER",    //Pull messages from the official account user
  "ReqMsgNumber": 2      //Number of messages to pull
}
Continue pulling by LastMsgKey Returns messages earlier than the specified LastMsgKey.
{
  "Official_Account": "@TOA#_15ERQPAER",
  "LastMsgKey": "71_1_1698741698",       // Continuation MsgKey
  "ReqMsgNumber": 2
}

Request packet fields

Field
Type
Attribute
Description
Official_Account
String
Mandatory
Official account user whose historical messages are to be pulled
LastMsgKey
String
Optional
The MsgKey of the last message fetched last time. This field must be filled for continuation pulling. See the method of filling above in Sample
ReqMsgNumber
Integer
Optional
Number of requested messages
WithRecalledMsg
Integer
Optional
Whether to pull messages that have been revoked, filling in 1 indicates the need to pull messages after revocation; by default, messages after revocation are not pulled

Sample response packets

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "Official_Account": "@TOA#_15ERQPAER",
    "IsFinished": 1,
    "LastMsgKey": "71_1_1698741698"
    "RspMsgList": [
        {
            "From_Account": "144115197276518801",
            "IsPlaceMsg": 0,
            "MsgBody": [
                {
                    "MsgContent": {
                        "Data": "\b\u0001\u0010\u0006\u001A\u0006Cat's Eye",
                        "Desc": "MIF",
                        "Ext": ""
                    },
                    "MsgType": "TIMCustomElem"
                },
                {
                    "MsgContent": {
                        "Data": "",
                        "Index": 15
                    },
                    "MsgType": "TIMFaceElem"
                }
            ],
            "MsgSeq": 71,
            "MsgKey" :"71_1_1698741698"
            "MsgTimeStamp": 1698741698
        },
        {
            "From_Account": "144115198339527735",
            "IsPlaceMsg": 0,
            "MsgBody": [
                {
                    "MsgContent": {
                        "Data": "\b\u0001\u0010\u0006\u001A\u000FWatermelon Sister.",
                        "Desc": "MIF",
                        "Ext": ""
                    },
                    "MsgType": "TIMCustomElem"
                },
                {
                    "MsgContent": {
                        "Text": "Report"
                    },
                    "MsgType": "TIMTextElem"
                }
            ],
            "MsgSeq": 72,
            "MsgKey" :"72_1_1698741700"
            "MsgTimeStamp": 1698741700
        }
    ]
}

Response packet field description

Field
Type
Description
ActionStatus
String
Processed Request Result:
OK: Indicates successful processing
FAIL: Indicates failure
ErrorInfo
String
Error message
ErrorCode
Integer
Error Identifier:
0: Indicates success
Non-zero: Indicates failure
Official_Account
String
Official Account Users in the Request
IsFinished
Integer
Whether all messages in the request range have been returned
When all messages in the request range are successfully returned, the value is 1
When the message length is too long or the range is too large (exceeding 20), resulting in the inability to return all messages, the value is 0
When all messages before the request range have expired, the value is 2
RspMsgList
Array
The returned message list
IsPlaceMsg
Integer
Whether it is a hollow message, when the message is deleted or expired:
If MsgBody is empty, this field is 1
For a recalled message, this field is 2
MsgKey
String
This tag identifies the message, which can be used for recalling Official Account Messages
MsgSeq
Integer
Message seq, used to identify unique messages, the smaller the value, the earlier it is sent
MsgTimeStamp
Integer
Timestamp when the message was sent (in seconds), server time
MsgBody
Object / Array
Message Content, for details please refer to the Message Content MsgBody

Error codes

Unless a network error occurs (such as a 502 error), the HTTP return code for this interface is always 200. The real error code and error message are indicated by ErrorCode, ErrorInfo in the response body. Common error codes (60000 to 79999) can be found in the Error Codes document. The private error codes for this API are as follows:
Error code
Description
10002
Internal server error, please try again
10003
Illegal Request Command Word
10004
Invalid parameter, please check if the request is correct based on the error description
10007
Insufficient Operational Permissions, the operator must be a role that is authorized to perform the corresponding operations in the Official Account
10010
Official Account User does not exist, or may have existed in the past, but is now dissolved
10015
Invalid Official Account User ID, please check if the Official Account User ID is correctly filled in

API Debugging Tool

Use the RESTful API Online Debugging Tool to debug this API.