服务端 API v2
  • API概览
  • 快速开始
  • 调用方式
  • 房间信令接口
  • 混流接口
  • 媒体服务接口
  • 媒体文件接口
  • 音视频流审核接口
  • 场景服务接口
  • 回调说明
  • 全局返回码
  • 使用 Postman 调试

推送自定义消息

更新时间:2022-11-14 10:34

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 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表请参考 调用方式 - 公共请求参数

参数 类型 是否必选 描述
RoomId
String
房间 ID。
FromUserId
String
发送方用户 ID(该用户不会接收消息,无需登录房间)。
ToUserId[]
Array of String
自定义消息目的用户 ID,最大支持 10 个目的用户 ID。
如果没有此字段,自定义消息广播给房间内所有用户;如果有此字段,自定义消息只推送到目的用户。
示例:ToUserId[]=123&ToUserId[]=456
MessageContent
String
自定义消息内容,长度不能超过 1024 个字节。

使用时,请对该参数内容进行 UrlEncode。

用户客户端如果使用上述 FromUserId 登录房间,而服务端使用该 FromUserId 发送请求时,会导致该客户端无法收到服务端消息。

4 请求示例

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
&<公共请求参数>

5 响应参数

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

6 响应示例

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

7 返回码

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

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