Documentation
In-app Chat
Server APIs
Send one-to-one messages

Send one-to-one messages

Last updated：2022-04-02 17:12

Description

Send one-to-one messages, support sending messages to a single user, or to multiple users in batches.

Rate limit: 20 requests/second.

The client will receive notifications of one-to-one messages through the event callback of the ZIM SDK.

Platform	Callback
iOS/macOS	zim:receivePeerMessage:fromUserID:
Android	onReceivePeerMessage
Windows	onReceivePeerMessage
Web	receivePeerMessage

Request method and endpoint

Request method: POST
Request endpoint: https://zim-api.zego.im/?Action=SendPeerMessage
Transmission protocol: HTTPS

Request parameters

Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Accessing Server APIs - Public parameters.

Parameter	Type	Required	Description
FromUserId	String	Yes	The ID of the user who send the message.
ToUserId	Array of String	Yes	The list of user IDs of the recipient, up to 100 user IDs are supported.
MessageType	Number	Yes	Message type, the values are as follows: 1: Text message. 2: Command message (signaling message). It's deliverability can't be guranteed because this is not stored in the cloud.
Priority	Number	Yes	Message priority, the values are as follows: 1: Low. 2: Medium. 3: High.
MessageBody	Object	Yes	Message content.

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

The format of MessageBody varies according to the value of MessageType. The following table shows the details:

MessageType	MessageBody format	Type	Required	Description
1 (Text message)	Message	String	Yes	Text message content, it is 2 KB by default. Size limit: 32 KB. For a larger configuration, contact ZEGOCLOUD Technical Support.
	ExtendedData	String	No	Extension field.
	OfflinePush	Object	No	Offline notification.
	└ Enable	String	No	Enable or disable the offline notifications: 0: Enable (by default). 1: Disable
	└ Title	String	Yes (required only when the OfflinePush is filled)	The title of the offline notification. Maximum number of characters: 20
	└ Content	String	Yes (required only when the OfflinePush is filled)	The offline notification content. Maximum number of characters: 50
	└ Payload	String	No	The action after receiving the offline notification.
2 (Command/Signaling message)	Message	String	Yes	Message content, it is 2 KB by default. Size limit: 32 KB. For a larger configuration, contact ZEGOCLOUD Technical Support.
2 (Command/Signaling message)	ExtendedData	String	No	Extension field.

The ZIM Server only supports the Command message type (the MessageType is 2) if the version of the SDK you are using is earlier than 2.0.0.

For a better development experience, we recommend you use the latest version of SDK.

Sample request

A sample URL request:

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

Request message 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	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.
ErrorList	Array of String	The error list. Error info will returned through this field.

Sample response

{
    "Code":0,
    "Message":"success",
    "RequestId":"343649807833778782",
    "ErrorList": [
        {
            "UserId": "id4",
            "SubCode": 1
        }
    ] 
}

Return codes

Listed below are the return codes related to this API. For the complete list of return codes, see Return codes.

Return code	Possible cause and solutions
660000011	The number of users has exceeded the limit. Please check the user lsit.
660400001	The length of message has exceeded the limit. Please check the message size.

ZEGO UIKits

Cloud Communications Products

Low-Code Products

AIGC

Supporting Services