Documentation
Server APIs v2
Room signaling
Send a custom message

Send a Custom Message

Last updated：2023-10-20 15:09

1 Description

Sends a custom signaling message to one or more specified users in a room.

On the client side, the ZEGO Express SDK will trigger the following callback when it receives a Custom Message:

Platform	ZEGO Express SDK callback
iOS/macOS	onIMRecvCustomCommand
Android	onIMRecvCustomCommand
Windows	onIMRecvCustomCommand
Web	IMRecvCustomCommand

2 Request method and endpoint

Request method: GET
Request endpoint: https://rtc-api.zego.im/?Action=SendCustomCommand
Transmission protocol: HTTPS
Rate limit (Rooms with the same AppID): 100 requests/second (Testing environment: 10 requests/second)

3 Request parameters

Not requiring the message sender to be online or in the current room.
When specifying the recipient userID, the message will fail to send if the userID is not in the room.

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 Server APIs public request parameters.

Parameter	Type	Required	Description
RoomId	String	Yes	Room ID.
FromUserId	String	Yes	User ID of the message sender.
ToUserId[]	Array of String	No	User IDs of the message recipients. The maximum number of User IDs allowed is 10. If this field is not included in the request, the custom message will be sent to all the other users in the room. If this field is included in the request, Example: ToUserId[]=123&ToUserId[]=456, then only these 2 users will receive the message.
MessageContent	String	Yes	Message content, with a maximum length of 1024 bytes.

4 Request example

https://rtc-api.zego.im/?Action=SendCustomCommand
&RoomId=123321
&FromUserId=123
&ToUserId[]=123&ToUserId[]=456
&MessageContent=%E6%8E%A8%E9%80%81%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BF%A1%E6%81%AF-%E6%96%B0%E6%8E%A5%E5%8F%A3
&<Public Request Parameters>

5 Response parameters

Parameter	Type	Description
Code	Number	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.

6 Response example

{
    "Code":0,
    "Message":"success",
    "RequestId":"3005402395393320157"
}

7 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 solution
104	The room does not exist. (the detection logic is the same as the return codes 5024 and 50001.) Please check the RoomId.
206	The rate limit (requests per second) has exceeded the limit. Please adjust the frequency of your requests or contact ZEGOCLOUD technical support.
5018	Room status does not match. Please try again later.
5024	The room does not exist. (the detection logic is the same as the return codes 104 and 5001.) Please check the RoomId.
50001	The room does not exist. (the detection logic is the same as the return codes 104 and 5024.) When there are no users in a room, the room will be automatically destroyed by the server. When there is only one user in a room and the user exits or is kicked out of the room, the room will be automatically destroyed by the server. When a room's heartbeat request times out by 100 seconds, the room will be destroyed by the server.
50002	User does not exist. Please check the UserId.
50003	Failed to query the user's online info. Please check whether the user is online based on the UserId.
50004	Failed to read the user info. Please check whether the user is online based on the UserId.
50009	Moderation failed. Please try again later or contact ZEGOCLOUD technical support.
50011	The number of recipients of the custom message has exceeded the limit.
50012	The length of the custom message has exceeded the limit.
50013	Failed to send custom messages. Please contact ZEGOCLOUD technical support.