--- title: 发送系统通知普通消息 --- App 下指定用户可以向其他用户发送系统通知消息。单次最多向 100 个用户发送消息。属于落地通知？。 - 支持发送即时通讯服务预定义的消息类型（见[消息类型概述]）。消息的类型（`objectName` 字段）决定了消息是否支持离线推送通知，以及客户端在收到该消息后，是否展示在聊天界面、会话列表，是否存入本地数据库。 - 支持发送客户自定义类型的消息。客户端在收到自定义消息后，是否展示在聊天界面、会话列表，是否存入本地数据库取决于客户端注册的自定义消息类型定义。 - 系统通知消息只能通过即时通讯服务端 API 进行发送，会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。 例如，对于一般的 App 业务通知来说，假设发送一条文本消息（`objectName` 为 `RC:TxtMsg`，属于客户端 SDK 会存储的内置消息类型，且可触发离线推送），效果如下： - 客户端如果在线，会即时收到一条消息，所在会话的 Target ID 为调用接口时传入的 `fromUserId`，会话类型为系统会话（类型为 SYSTEM）。 - 客户端如果离线，消息会触发服务端远程推送，客户端如已集成并启用推送服务，则会收到推送通知。 ## 请求方法 **POST**： https://[数据中心域名](../base-url.md)/message/system/publish.json **频率限制**： 每秒钟限发送 100 条消息，每次最多同时向 100 人发送，如：一次发送 100 人时，视为 100 条消息。 **签名规则**： 所有服务端 API 请求均需要进行规则校验，详见 [API 请求签名](../auth.md)。 ## 正文参数 HTTP 请求正文数据格式为 `application/x-www-form-urlencoded`，支持以下 HTTP 表单参数： | 参数 | 类型 | 必传 | 说明 | |------------------|---------|-----|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | fromUserId | String | 是 | 发送人用户 ID。

**注意**：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。 | | toUserId | String | 是 | 接收用户 ID，提供多个本参数可以实现向多用户发送系统消息，上限为 100 人。 | | objectName | String | 是 | 接受内置消息类型（见[消息类型概述](../message-about/about-message-types.md)）或自定义消息的消息类型值。

**注意**：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。 | | content | String | 是 | 所发送消息的内容，单条消息最大 128k。 | | pushContent | String | 否 | 指定收件人离线时触发的远程推送通知中的通知内容。**注意**：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。 | | pushData | String | 否 | iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 `appData`（**提示**：`rc` 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 `appData`。 | | isPersisted | Int | 否 | 是否需要为收件人在历史消息云端存储服务中存储此条消息。`0` 表示不存储；`1` 表示存储。默认值为 `1`，存储（系统消息是否存入服务端历史消息也依赖**单群聊消息云端存储服务**）。此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。

一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外：
  1. 如果消息属于内置消息类型，客户端 SDK 会根据消息类型本身的存储属性标识判断是否存入本地数据库。详见[消息类型概述](../message-about/about-message-types.md)。
  2. 如果消息属于自定义消息类型，则客户端 SDK 会根据该类型在客户端上注册时的存储属性标识判断是否需要存入本地数据库。
  3. 如果消息属于客户端 App 上未注册自定义消息类型（例如客户端使用的 App 版本过旧），则客户端 SDK 会根据当前参数值确定是否将消息存储在本地。但因消息类型未注册，客户端无法解析显示该消息。
| | contentAvailable | Int | 否 | 针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看[知识库文档](https://help.rongcloud.cn/t/topic/855)。1 表示为开启，0 表示为关闭，默认为 0 | | disablePush | Boolean | 否 | 是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。 | | pushExt | String | 否 | 配置消息的推送通知，如推送通知的标题等。`disablePush` 属性为 `true` 时此属性无效。具体请查看下方 **`pushExt` 参数说明**。 | - **`pushExt` 参数说明** | pushExt 参数 | 类型 | 必传 | 说明 | |:------------------------------------|-------:|:----|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | title | String | 否 | 通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。 | | templateId | String | 否 | 推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送，未匹配成功时使用默认内容进行推送，模板内容在“控制台-自定义推送文案”中进行设置。详情请查看 [自定义多语言推送模板](../push/push-template.md)。 | | forceShowPushContent | Number | 否 | 是否越过客户端配置，强制在推送通知内显示通知内容（`pushContent`）。默认值 `0` 表示不强制，`1` 表示强制。

**说明**：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置`forceShowPushContent` 为 `1` 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。 | | pushConfigs | Array | 否 | 按厂商设置不同推送属性。支持的推送通道值为 `MI`（小米）、`HONOR`（荣耀）、`HW`（华为）、`OPPO`、`VIVO`、`APNs`、`FCM`。 | | pushConfigs.HONOR.importance | String | 否 | 荣耀通知栏消息优先级，取值： | | pushConfigs.HONOR.image | String | 否 | 荣耀推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 | | pushConfigs.HW.channelId | String | 否 | 华为推送通知渠道的 ID，详细请参见 [华为自定义通知渠道](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/android-custom-chan-0000001050040122)。更多通知渠道信息，请参见 [Android 官方文档](https://developer.android.com/training/notify-user/channels)。 | | pushConfigs.HW.importance | String | 否 | 华为通知栏消息优先级，取值： | | pushConfigs.HW.image | String | 否 | 华为推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 | | pushConfigs.HW.category | String | 否 | 华为推送通道的消息自分类标识，category 取值必须为大写字母，例如 `IM`。App 根据华为要求完成[自分类权益申请](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835#section893184112272) 或 [申请特殊权限](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/faq-0000001050042183#section037425218509) 后可传入该字段有效。详见华为推送官方文档[消息分类标准](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835)。该字段优先级高于控制台为 App Key 下的**应用标识**配置的华为推送 Category。 | | pushConfigs.MI.channelId | String | 否 | 小米推送通知渠道的 ID，详细请参见 [小米推送消息分类新规](https://dev.mi.com/console/doc/detail?pId=2422#_4)。 | | pushConfigs.MI.large_icon_uri | String | 否 | 小米推送自定义通知栏消息的右侧图标 URL，若不设置，则不展示通知栏右侧图标。 | | pushConfigs.OPPO.channelId | String | 否 | OPPO 推送通知渠道的 ID，详细请参见 [OPPO PUSH 通道升级说明](https://open.oppomobile.com/new/developmentDoc/info?id=11227)。 | | pushConfigs.VIVO.classification | Number | 否 | VIVO 推送服务的消息类别。可选值 `0`（运营消息，默认值） 和 `1`（系统消息）。该参数对应 VIVO 推送服务的 `classification` 字段，见 [VIVO 推送消息分类说明](https://dev.vivo.com.cn/documentCenter/doc/359)。该字段优先级高于控制台为 App Key 下的**应用标识**配置的 VIVO 推送通道类型。 | | pushConfigs.VIVO.category | String | 否 | VIVO 推送服务的消息二级分类。例如 `IM`（即时消息）。该参数对应 VIVO 推送服务的 `category` 字段。详细的 category 取值请参见 [VIVO 推送消息分类说明](https://dev.vivo.com.cn/documentCenter/doc/359) 。如果指定 `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](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc) 字段。在 iOS 15 及以上版本中，系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知（例如余额变化）无法及时被用户感知的情况，可考虑设置该字段。 | | pushConfigs.FCM.channelId | String | 否 | FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见[安卓官方文档](https://developer.android.com/guide/topics/ui/notifiers/notifications?hl=zh-cn#ManageChannels)。 | | pushConfigs.FCM.collapse_key | String | 否 | 适用于 Android 平台。可以折叠的一组消息的标识符，以便在可以恢复传递时仅发送最后一条消息。 | | pushConfigs.FCM.imageUrl | String | 否 | 适用于 Android 平台。FCM 推送自定义的通知栏消息右侧图标 URL，如果不设置，则不展示通知栏右侧图标。 | | pushConfigs.OHOS.category | String | 否 | 鸿蒙系统场景化推送的通知消息类别，例如 IM。完成[自分类权益申请](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/push-apply-right-V5#section16708911111611)后，用于标识通知消息类型，不同的通知消息类型影响消息展示和提醒方式。字段取值见[请求提参数说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/push-scenariozed-api-request-param-V5#section17371529101117)。| | pushConfigs.OHOS.image | String | 否 | 通知右侧大图标 URL，URL 使用的协议必须是 HTTPS 协议，取值样例为：`https://example.com/image.png`。
**说明**：支持图片格式为png、jpg、jpeg、bmp，图片长宽建议小于 128*128 像素，若超过 49152 像素，则图片不展示。| - **`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"} }, { "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" } } ] } ``` ## 请求示例 ```http POST /message/system/publish.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&toUserId=2191&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=hello ``` ## 返回结果 HTTP 响应正文包含具有以下结构的 JSON 对象： | 返回值 | 返回类型 | 说明 | |:-------|:---------|:--------------------------| | code | Number | 返回码，200 为正常。 | | messageUIDs | Array | 返回 messageUID 列表 | | messageUIDs[i].userId | String | 接收方用户 ID， 和请求 toUserId 对应 | | messageUIDs[i].messageUID | String | 发送给对应接收方的消息的唯一 ID | ## 返回结果示例 ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "code": 200, "messageUIDs": [ { "userId": "uid1", "messageUID": "XXXX-JJJJ-KKK-LLLL" }, { "userId": "uid2", "messageUID": "XXXX-JJJJ-KKK-LLKL" } ] } ``` [用户内容类消息格式]: ../message-about/objectname.md [消息类型概述]: ../message-about/about-message-types.md