Documentation
In-app Chat
Server APIs
Message related
Send a one-to-one message

Send a one-to-one message

Last updated：2024-09-19 16:00

Overview

You can call this operation to send one-to-one messages to one or more users.

After a message is sent, the client receives the notification in the following ZIM SDK callbacks.

iOS	Android	macOS	Windows
receivePeerMessage	onReceivePeerMessage	receivePeerMessage	onReceivePeerMessage
Web	Flutter	Unity3D	React Native
receivePeerMessage	onReceivePeerMessage	OnReceivePeerMessage	receivePeerMessage

Request method and endpoint

Request method: POST
Request URL: https://zim-api.zego.im/?Action=SendPeerMessage
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 Public request parameters section of the Accessing Server APIs topic.

Parameter	Type	Required	Description
FromUserId	String	Yes	The ID of the message sender.
ToUserId	Array of String	Yes	The list of IDs of message recipients. Up to 100 user IDs can be included.
MessageType	Number	Yes	The message type. For more information about one-to-one message types, see MessageBody Introduction.
Priority	Number	Yes	The message priority. Valid values: `1`: low; `2`: medium; `3`: high.
MessageBody	Object	Yes	The message content. For more information, see the Applicable types of one-to-one chat section of the MessageBody Introduction topic.
SubMsgType	Number	No (Yes if `MessageType` is `200`)	The custom message type. Value range: [0,200].
SearchedContent	String	No	The search field for a custom message. This field is valid only if `MessageType` is `200`, cannot exceed 64 bytes in length, and must be specified to search for custom messages in the client.
SenderUnaware	Number	No	Specifies whether the client of the message sender (`FromUserId`) is aware of message sending from the server. Valid values: `0`: yes, which is the default value; `1`: no.

The FromUserId and ToUserId parameters can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'.
If the version of the sending ZIM SDK is earlier than 2.0.0 (for more information about versions, see Release notes), the ZIM server supports only command messages whose MessageType is 2.
We recommend that you use the SDK of the latest version for better experience.
To receive text messages whose MessageType is 1, the version of the ZIM SDK needs to be 2.7.0 or later.
To send and receive custom messages whose MessageType is 200, the version of the ZIM SDK needs to be 2.8.0 or later.
If the version of the receiving ZIM SDK is 2.0.0 or later but earlier than 2.8.0, the ZIM SDK can receive custom messages but will identify the message type as unknown. In addition, it cannot obtain the message content. To obtain the message content, upgrade the ZIM SDK to 2.8.0 or later.
If the version of the receiving ZIM SDK is 1.x.x, the ZIM SDK cannot receive custom messages and identify the message type as unknown.

Sample request

Request URL:

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

Request body:

{
    "FromUserId": "u1",
    "ToUserId":[
        "u2",
        "u3"
    ],
    "MessageType": 1,
    "Priority": 1,
    "MessageBody": {
        "Message":"hello world",
        "ExtendedData":"s",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        }
    }
}

Response parameters

Parameter	Type	Description
Code	Number	The return code. When you request to send messages to multiple users at a time, take note of the following items: If one or more messages are successfully sent, `0` is returned. For more information, see `ErrorList`. If all messages fail to be sent, a corresponding code is returned. For more information, see Return codes.
Message	String	The description of the request result.
RequestId	String	The request ID.
ErrorList	Array of String	The list of failed results. If `Code` is `0`: If `ErrorList` is empty, all one-to-one messages are successfully sent. If `ErrorList` is not empty, some one-to-one messages fail to be sent. In this case, see `SubCode`. If `Code` is not `0`: If `ErrorList` is empty, one or more parameters are invalid, the QPS limit is exceeded, or a system error occurs. If `ErrorList` is not empty, all one-to-one messages fail to be sent.
UserID	String	The ID of the user to whom the message fails to be sent.
SubCode	Number	The code returned when the request fails.
SuccList	Array of Object	The list of the users to whom messages are successfully sent.
UserId	String	The user ID.
MsgId	String	The message ID, which is globally unique.
MsgSeq	Number	The sequence of the message. This field is empty for signaling messages and can be used to Recall a one-to-one message.

Sample response

{
    "Code":0,
    "Message":"success",
    "RequestId":"343649807833778782",
    "ErrorList": [
        {
            "UserId": "u3",
            "SubCode": 1
        }
    ],
    "SuccList": [
        {
            "UserId": "id4",
            "MsgId": "6654861479614",
            "MsgSeq": 1
        }
    ] 
}

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
660000011	Too many users are included in the list.	Check the number of users.
660000025	Failed to send the Base64-encoded signaling message when `IsBase64` is set to `1` in `MessageBody`.	Check the following items: - Check whether `IsBase64` needs to be set to `1`, that is, whether a binary signaling message needs to be sent. - Check whether the message is Base64-encoded.
660400001	The message size exceeds the limit.	Check the message size.