跳到主要内容

发送系统通知模板消息

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

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

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

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

如何配置与使用消息模板​

消息模板通过字段内容模板（带标识位），和按接收者提供的标识位定义，实现单次向多个接收者发送不同内容的效果。

定义内容模板​

发送消息时，可在 content、pushContent、pushData 字段中传入带标识位的字段内容，例如：

JSON
"toUserId":["21","22","23"],
"content":"{\"content\":\"{c}{d}\",\"extra\":\"bb\"}",
"pushContent":["hello {c}","hello {c}","hello {c}"],

上例中的 {c}、{d} 为自定义的标识位。

  • 当前支持定义模板的字段包括：content、pushContent、pushData。
  • 消息内容（content）字段仅支持插入一个模板，所有接收者共用该模板。
  • 消息推送通知内容（pushContent）、推送附加数据（ pushData）字段类型为数组，必须按照 toUserId 中的用户 ID 列表逐个定义模板。即使不在 pushContent、pushData 中使用模板标识位，或所有接收者接收相同内容，都必须按照 toUserId 中的用户 ID 列表逐个定义各自的 pushContent、pushData。

指定模板内容标识位的值​

按照收件人列表（toUserId）在 values 字段提供标识位的定义，即为各个收件人指定需要接收的个性化内容。

JSON
"values":[
    {
    "{c}":"Tom",
    "{d}":"：2"
    },
    {
    "{c}":"Jerry",
    "{d}":"：5"},
    {
    "{c}":"Rose",
    "{d}":"：10"}
    ],

上面示例中，各接收者在线时收到的消息内容如下：

  • 用户 ID 为 21 收到：Tom：2
  • 用户 ID 为 22 收到：Jerry：5
  • 用户 ID 为 23 收到：Rose：10

如果接收者离线，各自收到的推送通知的内容（pushContent）也不同，分别为 Hello Tom，Hello Jerry，Hello Rose。

提示

如 content 中定义了标识 {d} ，则在 values 中必须设置 {d} 的值，否则 {d} 会以文本方式随消息发送给用户。

请求方法​

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

频率限制： 每秒钟限 100 次。请注意，如果同时向 100 人发送消息，视为 100 条消息。

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

正文参数​

HTTP 请求正文数据格式为 application/json，包含具有以下结构的 JSON 对象：

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

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

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
valuesArray of objects是为消息内容（content）、推送通知内容（pushContent）、推送数据（pushData）中的标识位（标识位示例：{d}）提供对应的值。
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[]否指定收件人离线时触发的远程推送通知中的通知内容。注意：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。支持定义模板标识位，使用 values 中的值进行替换。
  • 如果消息类型（objectName 字段）为即时通讯服务预定义的消息类型，填写该字段后，离线推送通知中显示模板定义的推送内容，而非消息类型的默认推送内容。
  • 如果消息类型为自定义消息类型，且需要支持远程推送通知，则必须填写 pushContent 字段，否则收件人不在线时无法收到远程推送通知。
  • 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段对应数组传空值禁用离线推送。
pushDataString[]否iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 appData（提示：rc 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 appData。
contentAvailableInt否针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
disablePushBoolean否是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
disableUpdateLastMsgBoolean否禁止更新会话最后一条消息。 当该参数为 false 时，发送的该条消息都会进入会话列表; 为 true 时，不会更新到会话列表的消息内容。
注：此参数仅对存储在客户端的消息有效。

请求示例​

HTTP
POST /message/system/publish_template.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
    "fromUserId":"fromuser",
    "objectName":"RC:TxtMsg",
    "content":"{\"content\":\"{c}{d}{e}\",\"extra\":\"bb\"}",
    "toUserId":["21","22"],
    "values":[{"{c}":"1","{d}":"2","{e}":"3"},{"{c}":"4","{d}":"5","{e}":"6"}],
    "pushContent":["push{c}","push{c}"],
    "pushData":["pushd","pushd{e}"]
}

上面示例中用户 ID 为 21 的用户，收到信息为 123，上面示例中用户 ID 为 22 的用户，收到信息为 456。

返回结果​

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