跳到主要内容

发送系统通知普通消息

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

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

例如,对于一般的 App 业务通知来说,假设发送一条文本消息(objectNameRC: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所发送消息的内容,单条消息最大 128k。
  • 内置消息类型:将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见消息类型概述中各内置消息类型的消息内容格式。

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

  • 自定义消息类型objectName 字段必须指定为自定义消息类型):如果发送自定义消息,该参数可自定义格式,不限于 JSON。
pushContentString指定收件人离线时触发的远程推送通知中的通知内容。注意:对于部分消息类型,该字段是否有值决定了是否触发远程推送通知。
  • 如果消息类型(objectName 字段)为即时通讯服务预定义消息类型中的用户内容类消息格式,可不填写该字段,远程推送通知默认使用服务端预置的推送通知内容。
  • 如果消息类型(objectName 字段)为即时通讯服务预定义消息类型中通知类、信令类("撤回命令消息" 除外),且需要支持远程推送通知,则必须填写 pushContent,否则收件人不在线时无法收到远程推送通知。如无需触发远程推送,可不填该字段。
  • 如果消息类型为自定义消息类型,且需要支持远程推送通知,则必须填写 pushContent 字段,否则收件人不在线时无法收到远程推送通知。
  • 如果消息类型为自定义消息类型,但不需要支持远程推送通知(例如通过自定义消息类型实现的 App 业务层操作指令),可将 pushContent 字段留空禁用远程推送通知。
pushDataStringiOS 平台收到推送消息时,可从 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 参数说明
  • pushExt 参数说明

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

    说明:客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时,可通过设置forceShowPushContent1 越过该配置,强制客户端针在此条消息的推送通知中显示推送内容。
    pushConfigsArray按厂商设置不同推送属性。支持的推送通道值为 MI(小米)、HONOR(荣耀)、HW(华为)、OPPOVIVOAPNsFCM
    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.OPPO.channelIdStringOPPO 推送通知渠道的 ID,详细请参见 OPPO PUSH 通道升级说明
    pushConfigs.VIVO.classificationNumberVIVO 推送服务的消息类别。可选值 0(运营消息,默认值) 和 1(系统消息)。该参数对应 VIVO 推送服务的 classification 字段,见 VIVO 推送消息分类说明。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
    pushConfigs.VIVO.categoryStringVIVO 推送服务的消息二级分类。例如 IM(即时消息)。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ,必须同时传入与当前二级分类匹配的 classification 字段的值(系统消息场景或运营消息场景)。请注意遵照 VIVO 官方要求,确保二级分类(category)取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
    pushConfigs.APNs.thread-idStringiOS 平台通知栏分组 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 及之后的系统。取值为 passiveactive(默认),time-sensitive,或 critical,取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中,系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知(例如余额变化)无法及时被用户感知的情况,可考虑设置该字段。
    pushConfigs.FCM.channelIdStringFCM 推送通知渠道的 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 像素,则图片不展示。
  • pushExt 结构示例

    {
    "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"
    }
    }
    ]
    }

请求示例

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/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"
}
]
}