Query message list from a one-on-one conversation

Overview

You can call this operation to paginate and fetch the message list of a specific one-on-one chat for a specified user.

Request method and endpoint

Request metho`d: POST
Request URL: https://zim-api.zego.im/?Action=QueryPeerMsg
Protocol: HTTPS
QPS limit: 20 calls per second

Request parameters

The following table describes only the operation-specific request parameters and some common request parameters. For the complete list of common request parameters, see the Common request parameters section of the Accessing Server APIs topic.

Parameter	Type	Required	Description
FromUserId	String	Yes	To query the list of the one-to-one chat messages between User A and User B, fill in the UserID of user A here.
ToUserId	String	Yes	Fill in the UserID of user B here.
Limit	Number	No	The number of messages to retrieve at a time, with a value range of (0, 100], defaulting to 10. When the value ≤ 0, it is corrected to 10. When the value > 100, it is corrected to 100.
Next	Number	No	Pagination flag for pulling messages. Fill in 0 for the first time, and then fill in the Next value returned from the previous call. When the returned Next is 0, it means that the message list has been completely retrieved. For example, if there are 250 messages in the current one-on-one chat session and you call this interface to query: First call this interface, fill in 100 for Limit, and fill in 0 for Next to query the 1st to 100th messages; the Next value in the returned result is num1. Second call this interface, fill in 100 for Limit, and fill in num1 for Next to query the 101st to 200th messages; the Next value in the returned result is num2. Third call this interface, fill in 100 for Limit, and fill in num2 for Next to query the 201st to 250th messages; the query is complete, and the Next in the returned result is 0.
WithEmptyMsg	Number	No	Whether the returned result includes retracted messages and messages that have been deleted on the server. 0: Default value, not included. 1: Included.

Note

The FromUserId and ToUserId parameter can contain only digits, letters, and the following characters: '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'.

Sample request

Request URL：

https://zim-api.zego.im/?Action=QueryPeerMsg
&<Common request parameters>

https://zim-api.zego.im/?Action=QueryPeerMsg
&<Common request parameters>

Request message body：

{
"FromUserId": "u1",
"ToUserId": "u2",
"Limit": 10,
"Next": 0,
"WithEmptyMsg": 0
}

{
"FromUserId": "u1",
"ToUserId": "u2",
"Limit": 10,
"Next": 0,
"WithEmptyMsg": 0
}

Response parameters

Parameters	Type	Description
Code	Number	The return code.
Message	String	The description of the request result.
RequestId	String	The request ID.
Next	Number	Pagination flag. Not 0: indicates that there is more conversation information to be returned, and this field needs to be set to the Next; parameter in the request to fetch more conversation information. 0: indicates that the complete conversation list has been returned. Aside from the explanations mentioned above, this field has no association with the list information. Please do not base any other logic on it.
List	Array of Object	Message list. Return the results in descending order by MsgTime.
└Sender	String	Message sender ID.
└MsgType	Number	Message type: 1: Text. 11: Image. 12: Document. 13: Audio. 14: Video. 200: Custom.
└SubMsgType	Number	Specific custom type. The value is filled in by the user when sending a custom message, and the value range is [0, 200]. This parameter is only meaningful when MsgType is 200 (custom type).
└MsgBody	String	Message content. When MsgType is 1 (text) or 200 (custom), MsgBody contains the message content passed during message sending, and developers can directly read the message content. When MsgType is one of the following types, MsgBody is a JSON string. Please use URLDecode to decode the JSON string, and then parse it according to the corresponding structure to obtain the field data in the message: When MsgType is 11, 12, 13, or 14 (multimedia messages): MsgBody JSON String Parsing Result Parameters - Multimedia messages. When MsgType is 10 (multi-item messages): MsgBody JSON String Parsing Result Parameters - Multi-item messages.
└MsgId	Number	Message ID, which can be used to determine the uniqueness of the message.
└MsgSeq	Number	The message Seq.
└Payload	String	Message extension field.
└MsgTime	Number	Timestamp when the server receives the message, in Unix time format with milliseconds (ms) as the unit.
└IsEmpty	Number	Whether it is an empty message. 0: Not empty. 1: Message is deleted or has expired. 2: Message is revoked.

MsgBody JSON String Parsing Result Parameters

Multimedia messages

Click to see details

Basic Parameters

Parameter	Type	Description
md5	String	MD5 value of the file.
file_name	String	Name of the file.
file_size	String	File size, in bytes (B).
download_url	String	Download URL.
media_duration	String	Duration of audio/video, in seconds (s).

Extended Parameters for Image Messages

For image messages, the following additional parameters are provided on top of the basic parameters.

Parameter	Type	Description
origin_image_width	Int	Width of the original image, in pixels (px).
origin_image_height	Int	Height of the original image, in pixels (px).
large_image_download_url	String	URL for downloading the large image.
large_image_width	Int	Width of the large image, in pixels (px).
large_image_height	Int	Height of the large image, in pixels (px).
thumbnail_download_url	String	URL for downloading the thumbnail image.
thumbnail_width	Int	Width of the thumbnail, in pixels (px).
thumbnail_height	Int	Height of the thumbnail, in pixels (px).

Extended Parameters for Video Messages

For video messages, the following additional parameters are provided on top of the basic parameters.

Parameter	Type	Description
video_first_frame_download_url	String	URL for downloading the first frame image of the video.
video_first_frame_width	Int	Width of the video first frame image, in pixels (px).
video_first_frame_height	Int	Height of the video first frame image, in pixels (px).

Multi-Item messages

Click to see details

Parameter	Type	Description
multi_msg	Array of Object	Array of items for the multi-item message.
└ msg_type	Int	Item type: 1: Text. 11: Image. 12: File. 13: Audio. 14: Video. 200: Custom message.
└ sub_msg_type	Int	This parameter is returned only when msg_type is 200.
└ callback_content	Object	Item content. When msg_type is 1 or 200, the message content can be read directly from this parameter. For items with msg_type 11, 12, 13, or 14, refer to the section on Multimedia Message Structure for details on the fields in the message.

Sample response

{
    "Code": 0
    "Message": "success",
    "RequestId": "343649807833778782",
    "Next": 1000,
    "List": [
        {
            "Sender": "user1",
            "MsgType": 1,
            "MsgBody": "This is a message.",
            "MsgId": 971503777289036700,
            "MsgSeq": 1,
            "Payload": "Payload",
            "MsgTime": 1705895412000,
            "IsEempy": 0
        }
    ]
}

{
    "Code": 0
    "Message": "success",
    "RequestId": "343649807833778782",
    "Next": 1000,
    "List": [
        {
            "Sender": "user1",
            "MsgType": 1,
            "MsgBody": "This is a message.",
            "MsgId": 971503777289036700,
            "MsgSeq": 1,
            "Payload": "Payload",
            "MsgTime": 1705895412000,
            "IsEempy": 0
        }
    ]
}

Return codes

The following table describes only the return codes related to the business logic of the operation. For the complete list of return codes, see Return codes.

Return Code	Description	Solution
660000002	Invalid parameter.	Check the input parameter.
660300005	The QPS limit specified in `AppID` is exceeded.	Try again later.
660500002	`FromUserId` is not registered.	Check if `FromUserId` is correct.