跳到主要内容

发送在线用户广播

App 用户可以向 App 下当前在线的所有用户发送系统会话消息，该功能称为「在线用户广播」。

  • 支持发送即时通讯服务预定义的消息类型（见消息类型概述）。消息的类型（objectName 字段）决定了客户端在收到该消息后，是否展示在聊天界面、会话列表，是否存入本地数据库。
  • 支持发送客户自定义类型的消息。客户端在收到自定义消息后，是否展示在聊天界面、会话列表，是否存入本地数据库取决于客户端注册的自定义消息类型定义。
  • 只能通过即时通讯服务端 API 进行发送，会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。
提示
  • 广播消息在客户端使用定时拉取机制接收。发送消息后，最长 3 分钟内 SDK 会拉取到此条消息。
  • 处于离线状态的客户端如果在 10 分钟内上线，可以收到广播消息。如果在发送消息后 10 分钟内一直处于离线状态，则无法收到该消息。
  • 在线广播消息暂不支持撤回。

例如，App 业务端希望向当前时间点正在使用 App 的所有用户发送一条消息。假设发送一条文本消息（objectName 为 RC:TxtMsg，属于客户端 SDK 会存储的内置消息类型，且可触发离线推送），效果如下：

  • 在线用户即时收到一条消息，所在会话的 Target ID 为调用接口时传入的 fromUserId，会话类型为系统会话（类型为 SYSTEM）。
  • 离线用户在 10 分钟内上线，仍可以收到广播消息。如果在发送消息后 10 分钟内用户一直处于离线状态，则无法收到该消息。

开通服务​

使用在线用户广播功能前，请确认已为当前 App Key 开通相关服务。详见全量用户通知服务配置。

如未开通服务，Server API 将返回 1009 错误。注意，在未开通服务时，如果连续请求导致 API 请求频率超过限制，Server API 会返回 HTTP 429 Too Many Requests 错误（错误码为 1008）。

请求方法​

POST： https://数据中心域名/message/online/broadcast.json

频率限制： 每分钟限 60 次

签名规则： 所有服务端 API 请求均需要进行规则校验，详见 API 请求签名。

正文参数​

HTTP 请求正文数据格式为 application/x-www-form-urlencoded，支持以下 HTTP 表单参数：

参数类型必传说明
fromUserIdString是发送人用户 ID。
objectNameString是消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
contentString是所发送消息的内容，单条消息最大 128k。
  • 内置消息类型：将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见消息类型概述中各内置消息类型的消息内容格式。

    例如，文本消息内容 JSON 结构体内部包含 content 字段（此为 JSON 结构体内的 key 值，注意区分），则需要将 {"content":"Hello world!"} 序列化后的结果作为此处 content 字段的值。

  • 自定义消息类型（objectName 字段必须指定为自定义消息类型）：如果发送自定义消息，该参数可自定义格式，不限于 JSON。

请求示例​

POST /message/online/broadcast.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

content=%7B%22content%22%3A%22hello%22%2C%22extra%22%3A%22helloExtra%22%7D&fromUserId=2191&objectName=RC:TxtMsg

返回结果​

HTTP 响应正文包含具有以下结构的 JSON 对象：

返回值返回类型说明
codeNumber返回码，200 为正常。
msgmessageUID广播消息 ID。

返回结果示例​

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "code": 200,
    "messageUID": "XXXX-JJJJ-KKK-LLLL"
}
最后于 更新