logo
ConsoleSign Up
Document
Client API
Server API
In-app Chat
Overview
Release Notes
Accessing Server APIs
Call API Online
Connect to ZEGOCLOUD Document MCP Serverlink
User
Room
Group
Message
Call invitation
Conversation
Bot
ZIMAudio
Callbacks
Return codes
Debugging guide of server API operations
Privacy policylink
On this page

QueryPeerMsg

POST

https://zim-api.zego.im/

By calling this API, you can pull the message list of a one-on-one conversation for a specified user in pages.

Note
The users corresponding to the parameters FromUserId and ToUserId must be logged in or registered.
QPS Limit
20 times/s

Request

Query Parameters

    Action stringrequired

    Possible values: [QueryPeerMsg]

    API prototype parameter

    https://zim-api.zego.im/?Action=QueryPeerMsg

    AppId uint32required

    💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

    SignatureNonce stringrequired

    💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

    Timestamp int64required

    💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

    SignatureVersion stringrequired

    Possible values: [2.0]

    Default value: 2.0

    💡Public parameter. Signature version number.

    Signature stringrequired

    💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

Body

required
    FromUserId stringrequired

    Possible values: <= 32 characters

    To query the one-on-one conversation message list between user A and user B, fill in user A's UserID here (who has logged in to the ZIM service by calling the login method on the client, or has completed registration by calling the server-side API).

    Note

    FromUserId only supports numbers, English characters, and "'!', '#', '$', '%', '&', '(', ')', '+', '', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'".

    ToUserId stringrequired

    Possible values: <= 32 characters

    Fill in user B's UserID here.

    Limit number

    Possible values: >= 1 and <= 100

    Default value: 10

    Number of messages to retrieve at a time, value range is (0, 100], default is 10.

    • When the value is ≤ 0, it is corrected to 10.
    • When the value is > 100, it is corrected to 100.
    Next number

    Pagination flag. Fill in 0 for the first time, and then fill in the Next value returned last time. When the returned Next is 0, it means the message list has been fully retrieved.

    For example, if the current one-on-one conversation has 250 messages, when calling this API to query:

    • First call: Set Limit to 100, Next to 0, to query messages 1-100; the Next value in the returned result is num1.
    • Second call: Set Limit to 100, Next to num1, to query messages 101-200; the Next value in the returned result is num2.
    • Third call: Set Limit to 100, Next to num2, to query messages 201-250; the query is complete, and the Next value in the returned result is 0.
    WithEmptyMsg number

    Possible values: [0, 1]

    Default value: 0

    Whether the returned result includes recalled messages and messages deleted on the server.

    • 0: Default value, not included.
    • 1: Included.

Responses​

OK
Schema
    Code number

    Return code.

    The following only lists the return codes related to the API business logic. For the complete return codes, please refer to Return codes.

    Return codeDescriptionSuggested Solution
    660000002Input parameter error.Please check the input parameters.
    660300005The API call frequency exceeds the AppID-level limit.Please try again later.
    660500002FromUserId is not registered.Please check if FromUserId is correct.
    Message string

    Description of the request result.

    RequestId string

    Request ID.

    Next number

    Pagination flag.

    • Non-zero: Indicates there are still messages not returned. You need to set this field to the request parameter Next to pull more messages.
    • Zero: Indicates the complete message list has been returned.

    Note

    Apart from the above description, this field has no association with the list information. Please do not base any other logic on this.

    List object[]
    Message list. Results are returned in descending order by MsgTime.
  • Array[
    • Sender string

    Message sender ID.

    MsgType number

    Message type:

    • 1: Text.
    • 10: Combined.
    • 11: Image.
    • 12: File.
    • 13: Audio.
    • 14: Video.
    • 200: Custom.
    SubMsgType number

    Specific custom type. The value is filled in by the user when sending a custom message, with a value range of [0,200]. This parameter is only meaningful when MsgType is 200 (custom type).

    MsgBody object

    Message content.

    • When MsgType is 1 (text type) or 200 (custom type), MsgBody is the message content passed in when sending the message, 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 this JSON string and obtain the data of each field in the message according to the corresponding structure:
    • When MsgType is 11, 12, 13, 14 (multimedia message), please refer to the multimedia message parameter description of the MsgBody JSON string parsing result.
    • When MsgType is 10 (combined message), please refer to the combined message parameter description of the MsgBody JSON string parsing result.
    oneOf
    md5 stringrequired

    MD5 value of the file.

    file_name stringrequired

    File name.

    file_size stringrequired

    File size in bytes (B).

    download_url stringrequired

    Download URL.

    media_duration string

    Audio/video duration in seconds (s).

    origin_image_width integer

    🏞️If it is an image message, this property is included. Width of the original image in pixels (px).

    origin_image_height integer

    🏞️If it is an image message, this property is included. Height of the original image in pixels (px).

    large_image_download_url string

    🏞️If it is an image message, this property is included. Large image download URL.

    large_image_width integer

    🏞️If it is an image message, this property is included. Width of the large image in pixels (px).

    large_image_height integer

    🏞️If it is an image message, this property is included. Height of the large image in pixels (px).

    thumbnail_download_url string

    🏞️If it is an image message, this property is included. Thumbnail download URL.

    thumbnail_width integer

    🏞️If it is an image message, this property is included. Width of the thumbnail in pixels (px).

    thumbnail_height integer

    🏞️If it is an image message, this property is included. Height of the thumbnail in pixels (px).

    video_first_frame_download_url string

    🎬If it is a video message, this property is included. Download URL of the video first frame image.

    video_first_frame_width integer

    🎬If it is a video message, this property is included. Width of the video first frame image in pixels (px).

    video_first_frame_height integer

    🎬If it is a video message, this property is included. Height of the video first frame image in pixels (px).

    MsgId number

    Message ID, which can be used to determine the uniqueness of the message.

    MsgSeq number

    Message Seq.

    Payload string

    Message extension field.

    MsgTime number

    Time when the server received the message, Unix timestamp in milliseconds (ms).

    IsEmpty number

    Whether it is an empty message.

    • 0: Not empty.
    • 1: Message has been deleted or expired.
    • 2: Message has been recalled.
  • ]

Previous

Query conversation list

Next

Query message list from a group conversation

On this page

Back to top