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 | |
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 | |
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 |
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