---
title: 发送系统通知模板消息
---

App 下指定用户可以向其他用户发送系统通知模板消息。单次最多向 100 个用户发送消息。属于落地通知<sup><a href="/guides/glossary/imglossary#message_notify">？</a></sup>。

- 支持发送即时通讯服务预定义的消息类型（见[消息类型概述]）。消息的类型（`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`。

:::tip

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


## 请求方法

**POST**： https://[数据中心域名](../base-url.md)/message/system/publish_template.json

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

**签名规则**： 所有服务端 API 请求均需要进行规则校验，详见 [API 请求签名](../auth.md)。

## 正文参数

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

| 参数             | 类型     | 必传 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|:-----------------|:---------|:----|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| fromUserId       | String   | 是   | 发送人用户 ID。<br/><br/>**注意**：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| toUserId         | String[] | 是   | 接收用户 ID，提供多个本参数可以实现向多人发送消息，上限为 100 人。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| objectName       | String   | 是   | 接受内置消息类型（见[消息类型概述](../message-about/about-message-types.md)）或自定义消息的消息类型值。<br/><br/>**注意**：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。                                                                                                                                                                                                                                                                                                                                           |
| values           | Array of objects | 是   | 为消息内容（`content`）、推送通知内容（`pushContent`）、推送数据（`pushData`）中的标识位（标识位示例：`{d}`）提供对应的值。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| content          | String   | 是   | 所发送消息的内容，单条消息最大 128k。<ul><li>**内置消息类型**：将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见[消息类型概述](../message-about/about-message-types.md)中各内置消息类型的消息内容格式。<p>例如，文本消息内容 JSON 结构体内部包含 content 字段（此为 JSON 结构体内的 key 值，注意区分），则需要将 `{"content":"Hello world!"}` 序列化后的结果作为此处 `content` 字段的值。</p></li><li>**自定义消息类型**（`objectName` 字段必须指定为自定义消息类型）：如果发送自定义消息，该参数可自定义格式，不限于 JSON。</li></ul>                                                                                        |
| pushContent      | String[] | 否   | 指定收件人离线时触发的远程推送通知中的通知内容。**注意**：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。支持定义模板标识位，使用 `values` 中的值进行替换。<ul><li>如果消息类型（`objectName` 字段）为即时通讯服务预定义的消息类型，填写该字段后，离线推送通知中显示模板定义的推送内容，而非消息类型的默认推送内容。</li><li>如果消息类型为自定义消息类型，且需要支持远程推送通知，则必须填写 `pushContent` 字段，否则收件人不在线时无法收到远程推送通知。</li><li>如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 `pushContent` 字段对应数组传空值禁用离线推送。</li></ul> |
| pushData         | String[] | 否   | iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 `appData`（**提示**：`rc` 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 `appData`。                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| contentAvailable | Int      | 否   | 针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看[知识库文档](https://help.rongcloud.cn/t/topic/855)。1 表示为开启，0 表示为关闭，默认为 0                                                                                                                                                                                                                                                                                                                                                                                            |
| disablePush      | Boolean  | 否   | 是否为静默消息，默认为 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 对象：

| 返回值 | 返回类型 | 说明               |
|:-------|:---------|:-----------------|
| 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"
        }
    ]
}
```

<!-- links -->
[用户内容类消息格式]: ../message-about/objectname.md
[消息类型概述]: ../message-about/about-message-types.md