发送全量用户落地通知

App 用户可以向 App 下全部用户发送系统会话消息，该功能称为「全量用户落地通知」。

• 支持发送即时通讯服务预定义的消息类型（见消息类型概述）。消息的类型（objectName 字段）决定了消息是否支持离线推送通知，以及客户端在收到该消息后，是否展示在聊天界面、会话列表，是否存入本地数据库。
• 支持发送客户自定义类型的消息。客户端在收到自定义消息后，是否展示在聊天界面、会话列表，是否存入本地数据库取决于客户端注册的自定义消息类型定义。
• 只能通过即时通讯服务端 API 进行发送，会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。
• 全量用户通知消息默认不存入即时通讯服务端历史消息记录。因此，客户端如果获取服务端的系统会话历史消息记录，其中不包含全量落地通知的消息。如需存储，参见全量用户通知服务配置。

例如，对于一般的 App 业务通知来说，假设发送一条文本消息（objectName 为 RC:TxtMsg，属于客户端 SDK 会存储的内置消息类型，且可触发离线推送），效果如下：

• 客户端如果在线，会即时收到一条消息，所在会话的 Target ID 为调用接口时传入的 fromUserId，会话类型为系统会话（类型为 SYSTEM）。
• 客户端如果离线，消息会触发服务端远程推送，客户端如已集成并启用推送服务，则会收到推送通知。

提示

广播消息在客户端使用定时拉取机制接收。发送消息后，最长 3 分钟内可收到此条消息。

开通服务

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

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

请求方法

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

频率限制： 每小时限发送 2 次，每天（自然日）最多发送 3 次。即时通讯服务端的消息处理默认为每秒钟 2000 条，即每秒钟可以向 2000 个目标用户下发消息。

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

正文参数

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

参数	类型	必传	说明
fromUserId	String	是	发送人用户 ID。 注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。
objectName	String	是	消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。 注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
content	String	是	所发送消息的内容，单条消息最大 128k。 内置消息类型：将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见消息类型概述中各内置消息类型的消息内容格式。 例如，文本消息内容 JSON 结构体内部包含 content 字段（此为 JSON 结构体内的 key 值，注意区分），则需要将 {"content":"Hello world!"} 序列化后的结果作为此处 content 字段的值。 自定义消息类型（objectName 字段必须指定为自定义消息类型）：如果发送自定义消息，该参数可自定义格式，不限于 JSON。
pushContent	String	否	指定收件人离线时触发的远程推送通知中的通知内容。注意：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中的用户内容类消息格式，可不填写该字段，远程推送通知默认使用服务端预置的推送通知内容。 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中通知类、信令类（"撤回命令消息" 除外），且需要支持远程推送通知，则必须填写 pushContent，否则收件人不在线时无法收到远程推送通知。如无需触发远程推送，可不填该字段。 如果消息类型为自定义消息类型，且需要支持远程推送通知，则必须填写 pushContent 字段，否则收件人不在线时无法收到远程推送通知。 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段留空禁用远程推送通知。
pushData	String	否	iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 appData（提示：rc 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 appData。
contentAvailable	Int	否	针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
pushExt	String	否	配置消息的推送通知，如推送通知的标题等。具体请查看下方 pushExt 参数说明。
disableUpdateLastMsg	Boolean	否	禁止更新会话最后一条消息。 当该参数为 false 时，发送的该条消息都会进入会话列表; 为 true 时，不会更新到会话列表的消息内容。 注：此参数仅对存储在客户端的消息有效。

• pushExt 参数说明

  pushExt 参数支持设置消息推送通知的标题、推送内容模板、是否强制通知及推送 ChannelID 等。pushExt 为 JSON 结构请求时需要做转义处理。

  pushExt 参数	类型	必传	说明
  title	String	否	通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。
  templateId	String	否	推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送，未匹配成功时使用默认内容进行推送，模板内容在“控制台-自定义推送文案”中进行设置。详情请查看 自定义多语言推送模板。
  forceShowPushContent	Number	否	是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。 说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent 为 1 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。
  pushConfigs	Array	否	按厂商设置不同推送属性。支持的推送通道值为 MI（小米）、HONOR（荣耀）、HW（华为）、OPPO、VIVO、APNs、FCM。
  pushConfigs.HONOR.importance	String	否	荣耀通知栏消息优先级，取值： NORMAL（服务与通讯类消息） LOW（咨询营销类消息）。若资讯营销类消息发送时带图片，图片不会展示。
  pushConfigs.HONOR.image	String	否	荣耀推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 URL 使用的协议必须是 HTTPS 协议，取值样例：https://example.com/image.png。 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。 超出建议规格大小的图标会存在图片压缩或显示不全的情况。
  pushConfigs.HW.channelId	String	否	华为推送通知渠道的 ID，详细请参见 华为自定义通知渠道。更多通知渠道信息，请参见 Android 官方文档。
  pushConfigs.HW.importance	String	否	华为通知栏消息优先级，取值： NORMAL（默认值，重要信息） LOW
  pushConfigs.HW.image	String	否	华为推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 URL 使用的协议必须是 HTTPS 协议，取值样例：https://example.com/image.png。 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。 超出建议规格大小的图标会存在图片压缩或显示不全的情况。
  pushConfigs.HW.category	String	否	华为推送通道的消息自分类标识，category 取值必须为大写字母，例如 IM。App 根据华为要求完成自分类权益申请 或 申请特殊权限 后可传入该字段有效。详见华为推送官方文档消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。
  pushConfigs.MI.channelId	String	否	小米推送通知渠道的 ID，详细请参见 小米推送消息分类新规。
  pushConfigs.MI.large_icon_uri	String	否	小米推送自定义通知栏消息的右侧图标 URL，若不设置，则不展示通知栏右侧图标。 国内版仅 MIUI12 以上版本支持，以下版本均不支持；国际版支持。 图片要求：大小 120 * 120px，格式为 png 或者 jpg 格式。
  pushConfigs.OPPO.channelId	String	否	OPPO 推送通知渠道的 ID，详细请参见 OPPO PUSH 通道升级说明。
  pushConfigs.OPPO.category	String	否	推送内容分类。详见OPUSH消息分类细则。
  pushConfigs.OPPO.notify_level	Number	否	通知提醒类型，1 通知栏、2 通知栏+锁屏、16 通知栏+锁屏+横幅+震动+铃声；设置 category 后此字段有效。详见OPUSH消息分类细则.
  pushConfigs.VIVO.classification	Number	否	VIVO 推送服务的消息类别。可选值 0（运营消息，默认值） 和 1（系统消息）。该参数对应 VIVO 推送服务的 classification 字段，见 VIVO 推送消息分类说明。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
  pushConfigs.VIVO.category	String	否	VIVO 推送服务的消息二级分类。例如 IM（即时消息）。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ，必须同时传入与当前二级分类匹配的 classification 字段的值（系统消息场景或运营消息场景）。请注意遵照 VIVO 官方要求，确保二级分类（category）取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
  pushConfigs.APNs.thread-id	String	否	iOS 平台通知栏分组 ID。相同的 thread-id 推送分一组，单组超过 5 条推送会折叠展示。
  pushConfigs.APNs.apns-collapse-id	String	否	适用于 iOS 平台。设置后设备收到有相同 ID 的消息，会合并成一条。 仅支持 iOS 10.0 及以上版本。
  pushConfigs.APNs.richMediaUri	String	否	适用于 iOS 平台。iOS 推送自定义的通知栏消息右侧图标 URL，需要 App 自行解析 richMediaUri 并实现展示。仅支持 iOS 10.0 及以上版本。
  pushConfigs.APNs.interruption-level	String	否	适用于 iOS 15 及之后的系统。取值为 passive，active（默认），time-sensitive，或 critical，取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中，系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知（例如余额变化）无法及时被用户感知的情况，可考虑设置该字段。
  pushConfigs.FCM.channelId	String	否	FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见安卓官方文档。
  pushConfigs.FCM.collapse_key	String	否	适用于 Android 平台。可以折叠的一组消息的标识符，以便在可以恢复传递时仅发送最后一条消息。
  pushConfigs.FCM.imageUrl	String	否	适用于 Android 平台。FCM 推送自定义的通知栏消息右侧图标 URL，如果不设置，则不展示通知栏右侧图标。 图片的大小上限为 1MB。 要求控制台 FCM 推送配置为证书与通知消息方式。
  pushConfigs.OHOS.category	String	否	鸿蒙系统场景化推送的通知消息类别，例如 IM。完成自分类权益申请后，用于标识通知消息类型，不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明。
  pushConfigs.OHOS.image	String	否	通知右侧大图标 URL，URL 使用的协议必须是 HTTPS 协议，取值样例为：https://example.com/image.png。 说明：支持图片格式为png、jpg、jpeg、bmp，图片长宽建议小于 128*128 像素，若超过 49152 像素，则图片不展示。
  pushConfigs.MEIZU.noticeMsgType	Number	否	魅族推送消息类型定义。 1：私信消息; 2：公信消息。 详见魅族推送消息分类说明。

• pushExt 结构示例

  JSON

  {
     "title":"you have a new message.",
     "templateId":"123456",
     "forceShowPushContent":0,
     "pushConfigs": [
         {
             "HW": {
               "channelId": "hw-123",
               "importance": "NORMAL",
               "image":"https://example.com/image.png"
             }
         },
         {
             "MI": {
               "channelId": "mi-123",
               "large_icon_uri":"https://example.com/image.png"
             }
         },
         {
             "OPPO": {
                  "channelId": "oppo-123",
                  "category": "IM",
                  "notify_level": 2
               }
         },
         {
             "VIVO" : {"classification": "0"}
         },
         {
             "APNs": {
                 "thread-id": "123",
                 "apns-collapse-id":"123456",
                 "richMediaUri":"https://example.com/image.png"
             }
         },
         {
             "FCM": {
              "channelId":"rongcloud_channelid",
              "collapse_key":"1234",
              "imageUrl":"https://example.com/image.png"
              }
         },
         {
             "OHOS": {
               "category": "IM",
               "image":"https://example.com/image.png"
             }
         },
         {
             "MEIZU": {
               "noticeMsgType": 1
             }
         }
     ]
  }

请求示例

HTTP

POST /message/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&pushContent=thisisapush&pushData=%7B%22pushData%22%3A%22hello%22%7D

返回结果

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

返回值	返回类型	说明
code	Number	返回码，200 为正常。
messageUID	String	广播消息 ID。

返回结果示例

HTTP

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

{
    "code": 200,
    "messageUID": "XXXX-JJJJ-KKK-LLLL"
}