SendPeerMessage

POST

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

Send 1v1 one-to-one messages, supporting sending messages to a single user or batch sending to multiple users.

The target client will receive one-to-one message notifications through the ZIM SDK callback interface.

Note

After enabling the content moderation feature, messages sent by the server will be moderated by default. If messages sent by the server do not need to be moderated, please contact ZEGOCLOUD Technical Support for configuration.

iOS	Android	macOS	Windows
peerMessageReceived	onPeerMessageReceived	peerMessageReceived	onPeerMessageReceived

Web	Mini Program	Flutter	React Native
peerMessageReceived	peerMessageReceived	onPeerMessageReceived	peerMessageReceived

Unity3D	uni-app \| uni-app x	HarmonyOS
OnReceivePeerMessage	peerMessageReceived	peerMessageReceived

Note

The users corresponding to the parameters FromUserId and ToUserId have logged in to the ZIM service by calling the login method on the client, or the developer has registered the relevant userID by calling the server-side API.

Note

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

If the sender's SDK version (for version information, please refer to Release notes) is lower than 2.0.0, the ZIM server only supports Command type messages with MessageType 2, and does not support other types. To provide developers with a better experience, ZEGOCLOUD recommends that developers use the latest version of the SDK.

If the sender requests to send a text message with MessageType 1, the sender's corresponding client (SDK version needs to be 2.7.0 or above) will also receive the message.

For sending and receiving custom messages with MessageType 200, the SDK version of the sender's and receiver's corresponding clients needs to be 2.8.0 or above.

If the receiver's SDK version is in the [2.0.0, 2.8.0) range, they can receive custom messages, but the message type will be displayed as unknown and the message content cannot be obtained. To obtain this message, please upgrade the SDK to version 2.8.0 or above.

If the receiver's SDK version is 1.x.x, they will not be able to receive custom messages, nor will they receive unknown messages.

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [SendPeerMessage]

API prototype parameter

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

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.

application/json

Body

required

FromUserId stringrequired

Possible values: <= 32 characters

Sender user ID.

ToUserId string[]required

Possible values: <= 100

Receiver's user ID list, supporting up to 100 user IDs.

Note

The list cannot contain userIDs identical to FromUserId, meaning the sender cannot send messages to themselves.

MessageType numberrequired

Message type. For applicable types for one-to-one conversations, please refer to MessageBody description.

Priority int32required

Possible values: [1, 2, 3]

Message priority (for details, please refer to Basic Concepts Introduction - Message Priority), with the following values:

1: Low.
2: Medium.
3: High.

MessageBody objectrequired

Message content. For specific parameter format, please refer to MessageBody description.

SubMsgType number

Specific custom type. The value is defined by you, with a value range of [0,200]. This parameter only needs to be assigned when MessageType is a custom message

SearchedContent string

Search field for custom messages. This field can only be filled in when MessageType is a custom message, with a default maximum length of 64 bytes. This field applies to the client. Unless this field is filled in, the associated custom message cannot be searched through the client.

SenderUnaware number

When sending messages through this server-side API, whether the client corresponding to FromUserId in the request parameters can perceive this sending:

0: (default) Can perceive.
1: Unperceived.

SendMsgOptions object

Optional configuration items.

NoUnread boolean

Whether this message will increase the receiver's unread message count.

false: (default value) will.
true: will not.

Responses

application/json

Schema
Example (from schema)

Schema

Code number

Return code.

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

Note

When you initiate a request to send messages to multiple users simultaneously:

If you only need to successfully send messages to 1 or more users, Code will return 0, indicating success. In this case, please refer to the specific information in ErrorList to confirm the operation result and understand whether sending messages to some users failed.

If sending messages to all users fails, Code will return the relevant return code. For details, please refer to Return codes.

Code / SubCode	Note	Suggested Solution
660000011	The number of users exceeds the limit, and the input user list is too large.	Please check the input user list.
660000025	Sending a signaling message encoded in base64 fails after IsBase64 is passed in MessageBody.	Please confirm: Please confirm whether IsBase64 needs to be 1, i.e., whether to send a binary type signaling message. Please confirm whether the message content is encoded in base64.
660400001	The input message size exceeds the limit.	Please check the input message size.

Message string

Return information.

RequestId string

Request ID.

ErrorList object[]

Failed list.

Code is 0:
ErrorList is empty, indicating that all one-to-one messages are successfully sent.
ErrorList is not empty, indicating that some one-to-one messages failed to send. Please refer to SubCode for handling.
Code is not 0:
ErrorList is empty, indicating that parameter error, interface frequency limit, or system error occurred.
ErrorList is not empty, indicating that all one-to-one messages failed to be sent.

Array[

UserId string

The target UserID of the message that failed to be sent.

SubCode number

Specific return code for failed message sending. For the complete return codes, please refer to the Code description or Return codes.

]

SuccList object[]

The list of users to whom messages were successfully accepted.

Array[

UserId string

User ID.

MsgId string

Message ID. Globally unique.

MsgSeq number

Message Seq. When the message type is a signaling message, this field is empty. Can be used for Recall a one-to-one message.

]

AuditInfos object[]

Audit structure array. When the array is not empty, it indicates that there are messages that failed the audit, and you can view the reason for the audit failure through this structure.

Array[

Index number

This parameter may have the following situations:

When you have enabled the ZIM content moderation service and have not rejected the message through the message not sent yet callback:

For combined messages, this parameter indicates the index of the Item that failed the audit in the combined message, starting from 0.
For other types of messages, this parameter is always 0.

When you reject this message after receiving the message not sent yet callback, this parameter is always 0 regardless of the message type.

Reason string

Rejection reason.

]

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

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

SendPeerMessage

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

Request

Query Parameters

Body

Responses​

Responses