文档中心
服务端 API v2
房间信令接口
推送自定义消息

推送自定义消息

更新时间：2023-07-12 22:00

1 描述

调用本接口在房间内推送自定义消息，即向同一房间内指定的单个或多个用户发送信令消息。

当房间人数小于 500 人时，向同一房间内所有用户发自定义消息，房间内所有用户基本都能收到消息。
当房间人数大于 500 人后，该房间升级为大房间，此时：
- 若对升级大房间后进来的某个用户发自定义消息，将不会成功。
- 若对升级大房间之前进来的某个用户发消息，会成功。
- 若对房间内所有用户发自定义消息，将不再可靠。
- 除非所有人退出房间，重新创建房间，才可恢复正常。

客户端接收消息使用 ZEGO SDK 回调接口：

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

2 接口原型

请求方法：GET
请求地址：https://rtc-api.zego.im/?Action=SendCustomCommand
传输协议：HTTPS
调用频率限制（同一个 AppID 下所有房间）：100 次/秒（测试环境：10 次/秒）

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式中的 “2.1 公共请求参数”。

参数	类型	是否必选	描述
RoomId	String	是	房间 ID。
FromUserId	String	是	发送方用户 ID。
ToUserId[]	Array of String	否	自定义消息目的用户 ID，最大支持 10 个目的用户 ID。如果不填写该参数，自定义消息广播给房间内所有用户；如果填写了该参数，自定义消息只推送到目的用户。示例：ToUserId[]=user1&ToUserId[]=user2
MessageContent	String	是	自定义消息内容，长度不能超过 1024 个字节。使用时，请对该参数内容进行 UrlEncode。

在服务端通过某个 FromUserId 发送消息时，使用相同 FromUserId 的客户端不会收到该条消息，即发送方不能接收到自己发送的消息。
如果开发者需要让房间内的所有用户都收到消息，调用本接口时，应传入该房间用户之外的 FromUserId。
使用的 FromUserId 无需登录该房间，即可直接发送消息。

4 请求示例

https://rtc-api.zego.im/?Action=SendCustomCommand
&RoomId=room
&FromUserId=userA
&ToUserId[]=user1&ToUserId[]=user2
&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
&<公共请求参数>

5 响应参数

参数	类型	描述
Code	Int32	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。
Data	Object	响应数据。
└ FailUsers	Array of Object	处理失败的目标用户 ID 列表。
└ Uid	String	用户 ID。
└ Code	Int32	失败的错误码（不在线：50003）。

6 响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "3005402395393320157",
    "Data": {
        "FailUsers": [{
            "Uid": "1111",
            "Code": 50003
        }]
    }
}

7 返回码

以下仅列出了常见的接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
50003	查找用户在线信息失败。	请确认请求用户 UserId 是否在线。
50011	用户列表长度过长。	请检查请求包中的用户个数是否超过限制。
50012	消息长度超过限制。	请检查参数长度是否超过限制。
50013	发送自定义消息失败。	请重试，或联系 ZEGO 技术支持处理。