跳到主要内容

发送系统通知普通消息

App 下指定用户可以向其他用户发送系统通知消息。单次最多向 100 个用户发送消息。属于落地通知？。

  • 支持发送即时通讯服务预定义的消息类型（见消息类型概述）。消息的类型（objectName 字段）决定了消息是否支持离线推送通知，以及客户端在收到该消息后，是否展示在聊天界面、会话列表，是否存入本地数据库。
  • 支持发送客户自定义类型的消息。客户端在收到自定义消息后，是否展示在聊天界面、会话列表，是否存入本地数据库取决于客户端注册的自定义消息类型定义。
  • 系统通知消息只能通过即时通讯服务端 API 进行发送，会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。

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

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

请求方法​

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

频率限制： 每秒钟限发送 100 条消息，每次最多同时向 100 人发送，如：一次发送 100 人时，视为 100 条消息。

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

正文参数​

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

参数类型必传说明
fromUserIdString是发送人用户 ID。

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

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
contentString是所发送消息的内容。2026 年 5 月 29 日起，新注册客户的除图片消息（RC:ImgMsg）、流式消息（RC:StreamMsg）、语音消息（RC:VcMsg）、视频消息（RC:SightMsg）、位置消息（RC:LBSMsg）、合并转发消息（RC:CombineV2Msg，RC:CombineMsg）、引用消息（RC:ReferenceMsg）外，其他消息的 content 消息体大小限制不超过 10 KB。
  • 内置消息类型：将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见消息类型概述中各内置消息类型的消息内容格式。

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

  • 自定义消息类型（objectName 字段必须指定为自定义消息类型）：如果发送自定义消息，该参数可自定义格式，不限于 JSON。
pushContentString否指定收件人离线时触发的远程推送通知中的通知内容。注意：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。
  • 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中的用户内容类消息格式，可不填写该字段，远程推送通知默认使用服务端预置的推送通知内容。
  • 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中通知类、信令类（"撤回命令消息" 除外），且需要支持远程推送通知，则必须填写 pushContent，否则收件人不在线时无法收到远程推送通知。如无需触发远程推送，可不填该字段。
  • 如果消息类型为自定义消息类型，且需要支持远程推送通知，则必须填写 pushContent 字段，否则收件人不在线时无法收到远程推送通知。
  • 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段留空禁用远程推送通知。
pushDataString否iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 appData（提示：rc 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 appData。
isPersistedInt否是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储（系统消息是否存入服务端历史消息也依赖单群聊消息云端存储服务）。此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。

一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外：
  1. 如果消息属于内置消息类型，客户端 SDK 会根据消息类型本身的存储属性标识判断是否存入本地数据库。详见消息类型概述。
  2. 如果消息属于自定义消息类型，则客户端 SDK 会根据该类型在客户端上注册时的存储属性标识判断是否需要存入本地数据库。
  3. 如果消息属于客户端 App 上未注册自定义消息类型（例如客户端使用的 App 版本过旧），则客户端 SDK 会根据当前参数值确定是否将消息存储在本地。但因消息类型未注册，客户端无法解析显示该消息。
contentAvailableInt否针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
disablePushBoolean否是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
pushExtString否配置消息的推送通知，如推送通知的标题等。disablePush 属性为 true 时此属性无效。具体请查看下方 pushExt 参数说明。
disableUpdateLastMsgBoolean否禁止更新会话最后一条消息。 当该参数为 false 时，发送的该条消息都会进入会话列表; 为 true 时，不会更新到会话列表的消息内容。
注：此参数仅对存储在客户端的消息有效。

  • pushExt 参数说明

    pushExt 参数类型必传说明
    titleString否通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。
    templateIdString否推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送，未匹配成功时使用默认内容进行推送，模板内容在“控制台-自定义推送文案”中进行设置。详情请查看 自定义多语言推送模板。
    forceShowPushContentNumber否是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。

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

返回值返回类型说明
codeNumber返回码，200 为正常。
messageUIDsArray返回 messageUID 列表
messageUIDs[i].userIdString接收方用户 ID， 和请求 toUserId 对应
messageUIDs[i].messageUIDString发送给对应接收方的消息的唯一 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"
        }
    ]
}