SendCustomCommand

GET

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

Call this interface to send custom messages in a Room, i.e., sending signaling messages to specified single or multiple users in the same Room.

Client-side message reception uses ZEGOCLOUD Express SDK callback interfaces:

Platform	ZegoExpress SDK	LiveRoom SDK
iOS/macOS	onIMRecvCustomCommand	onReceiveCustomCommand
Android	onIMRecvCustomCommand	onRecvCustomCommand
Windows	onIMRecvCustomCommand	OnRecvCustomCommand
Web	IMRecvCustomCommand	onRecvCustomCommand

Call Rate Limit

All Rooms under the same AppID: 100 times/second (test environment: 10 times/second)

Notice

When sending messages through a certain FromUserId on the server, clients using the same FromUserId will not receive this message, i.e., the sender cannot receive messages sent by themselves.
If developers need all users in the Room to receive the message, when calling this interface, a FromUserId other than the Room users should be passed in.
The FromUserId used does not need to log in to the Room to send messages directly.

Request

Query Parameters

Action stringrequired

Possible values: [SendCustomCommand]

API Prototype Parameters

https://rtc-api.zego.im?Action=SendCustomCommand

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Common parameter. A 16-character hexadecimal random string (hex-encoded 8-byte random number). For the generation algorithm, refer to the signature example.

Timestamp int64required

💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to the signature example. A maximum deviation of 10 minutes is allowed.

Signature stringrequired

💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to the signature mechanism to generate it.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

RoomId stringrequired

Room ID.

FromUserId stringrequired

Sender User ID.

ToUserId string[]

Possible values: >= 1, <= 10

Custom message destination User ID, supporting up to 10 destination User IDs. If this parameter is not filled in, the custom message is broadcast to all users in the Room; if this parameter is filled in, the custom message is only pushed to the destination users. Example: ToUserId[]=user1&ToUserId[]=user2

MessageContent stringrequired

Possible values: <= 1024 characters

Custom message content, length cannot exceed 1024 bytes. When using, URL encoding (UrlEncode) must be performed on its content.

Responses

Operation successful

application/json

Schema
Example (from schema)

Schema

Code int32

Return code. The following only lists some return codes related to interface business logic. For complete return codes, please refer to Global Return Codes.

Return Code	Description	Suggested Action
50003	Failed to find user online information.	Please confirm whether the requested UserId is online.
50011	User list length is too long.	Please check whether the number of users in the request packet exceeds the limit.
50012	Message length exceeds limit.	Please check whether the parameter length exceeds the limit.
50013	Failed to send custom message.	Please retry, or contact ZEGOCLOUD technical support for assistance.

Message string

Operation result description.

RequestId string

Request ID.

Data object

FailUsers object[]

List of target User IDs that failed to process.

Array[

Uid string

User ID.