Query messages

Description

This API allows you to query multiple messages in a specific conversation (group conversation, one-to-one conversation).

Request method and endpoint

Request method: POST
Request URL: https://zim-api.zego.im/?Action=QueryMessagesByMsgSeq
Protocol: HTTPS
QPS limit: 20 messages per second

Warning
The frequency limit of this API is 20 messages per second, not 20 requests 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	The UserID of the user. For querying one-to-one conversation messages, fill in the UserID of any participant in the conversation. For querying group conversation messages, you can fill in the UserID of any registered user.
ConvId	String	Yes	The conversation ID. For one-to-one conversation messages, fill in the UserID of the other participant. For group conversation messages, fill in the groupID of the target group.
ConvType	Number	Yes	The conversation type: 0: one-to-one conversation. 2: Group conversation.
MsgSeqList	Array of Number	Yes	A list of message sequences to query. The list has an upper limit of 20. Note For adjustments, please contact ZEGOCLOUD technical support. MsgSeq retrieval method: If you need to query one-to-one conversation messages sent by the client, retrieve MsgSeq via the Callback on message sent. If you need to query one-to-one messages sent by the server API Send a one-to-one message, get MsgSeq from the API response data. If you need to query group conversation messages sent by the server API Send group messages, get MsgSeq from the API response data.

Sample Request

Request URL:

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

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

Request Body:

{
    "FromUserId": "user0",
    "ConvId": "user1",
    "ConvType": 0,
    "MsgSeqList": [
        1,
        2,
        3
    ]
}

{
    "FromUserId": "user0",
    "ConvId": "user1",
    "ConvType": 0,
    "MsgSeqList": [
        1,
        2,
        3
    ]
}

Response Parameters

Parameter	Type	Description
Code	Number	Return code.
Message	String	Description of the result.
RequestId	String	Request ID.
MessageList	Array of Object	List of returned messages, details in MessageList Structure.

MessageList Structure

Parameter	Type	Description
Sender	String	Message sender.
MsgType	Number	Message type: 1: Text. 10: Multi-item. 11: Image. 12: File. 13: Audio. 14: Video. 31: Revoked. 32: Tip. 200: Custom.
SubMsgType	Number	Specific custom type. The value is filled by the user when sending a custom message, and the valid range is [0, 200]. This parameter is meaningful only when MsgType is 200 (custom).
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 it. 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 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. When MsgType is 31 (message has been revoked): MsgBody JSON String Parsing Result Parameters - Revoked messages. When MsgType is 32 (Tips message): MsgBody JSON String Parsing Result Parameters - Tips messages.
MsgId	Number	Message ID, which can be used to determine the uniqueness of the message.
MsgSeq	Number	Message sequence.
Payload	String	Message extension field.
MsgTime	Number	The time when the server receives the message, in Unix timestamp format, in milliseconds (ms).
IsEmpty	Number	Whether it is an empty message: 0: Not an empty message. 1: The message has been deleted (cannot be queried or deleted by the client via the API). Therefore, other response fields are empty. 2: The message has been 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.

Revoked messages

Click to see details

Parameter	Type	Description
user_id	String	The UserID of the user who initiated the revoke.
revoke_time	Number	The revocation timestamp, in milliseconds.
msg_type	Number	The original message type.
payload	String	The extension field carried during the revocation.
msg_status	Number	The corresponding status of the revoked message: 4: Revoked by the user. 8: Revoked by the system. 12: Revoked via server API. 16: Revoked by group administrator. 20: Revoked by group owner. 24: Revoked due to failure to pass review.

Tip Messages

Click to see details

Parameter	Type	Description
type	Number	Tips message type: Group member change: 1: Group created. 2: Group dissolved. 3: User joined group. 4: Group member invited an external user. 5: Group member left. 6: User kicked out of the group. Group member profile change: 11: Group owner transferred. 12: Group member role changed. 13: Group member mute status changed. Group profile change: 30: Group name, avatar, or announcement changed. 34: Group-wide mute status changed.
op_user_info	Object	The user who triggered the Tips message (e.g., the user who created the group, the user who changed the group name).
└user_id	String	User ID.
└role	Number	User's group role: 1: Group owner. 2: Group admin. 3: Group member.
└group_member_name	String	User's group member name.
└group_member_nickname	String	User's group nickname.
target_users	Array of Object	The target users of the tip message operation (e.g., users invited to the group, users kicked out).
└user_id	String	User ID.
└role	Number	User's group role: 1: Group owner. 2: Group admin. 3: Group member.
└group_member_name	String	User's group member name.
└group_member_nickname	String	User's group nickname.
group_data_flag	Number	When type is 30, this parameter indicates the modified group profile item. 1: Group name. 2: Group announcement. 4: Group avatar.
group_notice	String	Group announcement.
group_name	String	Group name.
group_avatar	String	Group avatar.
forbid	Object of GroupForbid	When type is 34, this parameter indicates the group-wide mute object.
└is_all_forbid	Bool	Whether mute is applied to all members: false: No. true: Yes.
└forbid_role_list	Array of Number	Group member roles who are muted.
└forbid_expire_time	Number	The timestamp of mute expiration, in milliseconds.
forbid_expire_time	Number	When `type` is 13, this parameter represents the timestamp of the group member's mute expiration, in milliseconds.
role	Number	When type is 12, this parameter represents the changed group member role. 1: Group owner. 2: Group admin. 3: Group member.

Sample Response

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "MessageList": [
        {
            "Sender": "userA",
            "MsgType": 1,
            "MsgBody": "this is a message",
            "MsgId": 971503777289036700,
            "MsgSeq": 1,
            "Payload": "this is a payload",
            "MsgTime": 1705895412000,
            "IsEmpty": 0
        }
    ]
}

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "MessageList": [
        {
            "Sender": "userA",
            "MsgType": 1,
            "MsgBody": "this is a message",
            "MsgId": 971503777289036700,
            "MsgSeq": 1,
            "Payload": "this is a payload",
            "MsgTime": 1705895412000,
            "IsEmpty": 0
        }
    ]
}

Return Codes

Return Code	Description	Suggested Actions
660000001	Server error.	Please try again or contact ZEGOCLOUD Technical Support.
660000002	Missing or invalid input parameters.	Please check the input parameters.
660300005	API call frequency exceeds AppID level limit.	Please try again later or refer to the relevant documentation for frequency limits.
660700008	Error retrieving user information.	Please check if the UserID is correct.
660700015	User not registered.	Please register the user first.