发送单聊模板消息
应用下的用户可向其他用户发送单聊模板消息。通过您自定义的模板，可实现一次向多个用户发送不同的消息内容。例如，App 可以向应用中不同用户发送消息告知已获得的积分。
- 单次最多向 1000 个用户发送单聊模板消息。
- 支持通过模板字段区分不同用户收到的离线推送通知内容。如有需要，请在
pushContent中按照toUserId中的用户 ID 列表逐个定义推送内容。 - 通过该接口发送的消息，默认不会向消息发件人客户端同步，也不会存入发件用户的历史消息记录。如需同步，请参见
isIncludeSender参数用法。
如何配置与使用消息模板
消息模板通过字段内容模板（带标识位），和按接收者提供的标识位定义，实现单次向多个接收者发送不同内容的效果。
定义内容模板
发送消息时，可在 content、pushContent、pushData 字段中传入带标识位的字段内容，例如：
"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 字段提供标识位的定义，即为各个收件人指定需要接收的个性化内容。
"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/private/publish_template.json
频率限制： 每分钟限发送 6000 条信息。请注意，如果一次发送给 1000 人，视为 1000 条消息。
签名规则： 所有服务端 API 请求均需要进行规则校验，详见 API 请求签名。
正文参数
HTTP 请求正文数据格式为 application/json，包含具有以下结构的 JSON 对象：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| fromUserId | String | 是 | 发送人用户 ID。 注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。 |
| toUserId | String[] | 是 | 接收用户 ID，提供多个本参数可以实现向多人发送消息，上限为 1000 人。 |
| objectName | String | 是 | 消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。 注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。 |
| values | Array of objects | 是 | 为消息内容（content）、推送通知内容（pushContent）、推送数据（pushData）中的标识位（标识位示例：{d}）提供对应的值。 |
| content | String | 是 | 所发送消息的内容，单条消息最大 128k。
|
| pushContent | String[] | 是 | 指定收件人离线时触发的远程推送通知中的通知内容。注意：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。支持定义模板标识位，使用 values 中的值进行替换。
|
| pushData | String[] | 否 | iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 appData（提示：rc 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 appData。 |
| isIncludeSender | Int | 否 | 是否向发件人客户端同步已发消息。1 表示同步，默认值为 0，即不同步。注意，仅设置该参数无法确保发件人客户端一定能获取到该条已发消息，您可能还需要启用其他服务。详见发件人客户端如何同步已发消息 。 |
| verifyBlacklist | Int | 否 | 是否过滤发送人黑名单列表，0 为不过滤、 1 为过滤，默认为 0 不过滤。 |
| isPersisted | Int | 否 | 是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储（依赖单群聊消息云端存储服务）。此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。 提示：一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外：
|
| contentAvailable | Int | 否 | 仅目标用户为 iOS 设备时有效，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到 通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0 |
| expansion | Boolean | 否 | 是否为可扩展消息，默认为 false，设为 true 时终端在收到该条消息后，可对该条消息设置扩展信息。 |
| disablePush | Boolean | 否 | 是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。 |
| pushExt | Object | 否 | 配置消息的推送通知，如推送通知的标题等。disablePush 属性为 true 时此属性无效。具体请查看下方 pushExt 参数说明。 |
-
pushExt参数说明pushExt参数支持设置消息推送通知的标题、推送内容模板、是否强制通知及推送ChannelID等。pushExt为 JSON 结构请求时需要做转义处理。pushExt 参数 类型 必传 说明 title String 否 通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。 templateId String 否 推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送。未匹配成功时使用默认内容进行推送。模板内容在“控制台-自定义推送文案”中进行设置。详见自定义多语言推送模板。 forceShowPushContent Number 否 是否越过客户端配置，强制在推送通知内显示通知内容（ pushContent）。默认值0表示不强制，1表示强制。
说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent为1越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。pushConfigs Array 否 按厂商设置不同推送属性。支持的推送通道值为 MI（小米）、HONOR（荣耀）、HW（华为）、OPPO、VIVO、APNs、FCM。pushConfigs.HONOR.importance String 否 荣耀通知栏消息优先级，取值： - NORMAL（服务与通讯类消息）
- LOW（咨询营销类消息）。若资讯营销类消息发送时带图片，图片不会展示。
pushConfigs.HONOR.image String 否 荣耀推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 - URL 使用的协议必须是 HTTPS 协议，取值样例：
https://example.com/image.png。 - 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。
超出建议规格大小的图标会存在图片压缩或显示不全的情况。
pushConfigs.HW.channelId String 否 华为推送通知渠道的 ID，详细请参见 华为自定义通知渠道。更多通知渠道信息，请参见 Android 官方文档。 pushConfigs.HW.importance String 否 华为通知栏消息优先级，取值： - NORMAL（默认值，重要信息）
- LOW
pushConfigs.HW.image String 否 华为推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。 - URL 使用的协议必须是 HTTPS 协议，取值样例：
https://example.com/image.png。 - 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。
超出建议规格大小的图标会存在图片压缩或显示不全的情况。
pushConfigs.MI.channelId String 否 小米推送通知渠道的 ID，详细请参见 小米推送消息分类新规。 pushConfigs.MI.large_icon_uri String 否 小米推送自定义通知栏消息的右侧图标 URL，若不设置，则不展示通知栏右侧图标。 - 国内版仅 MIUI12 以上版本支持，以下版本均不支持；国际版支持。
- 图片要求：大小 120 * 120px，格式为 png 或者 jpg 格式。
pushConfigs.OPPO.channelId String 否 OPPO 推送通知渠道的 ID，详细请参见 OPPO PUSH 通道升级说明。 pushConfigs.VIVO.classification Number 否 VIVO 推送服务的消息类别。可选值 0（运营消息，默认值） 和1（系统消息）。该参数对应 VIVO 推送服务的classification字段，见 VIVO 推送消息分类说明。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。pushConfigs.VIVO.category String 否 VIVO 推送服务的消息二级分类。例如 IM（即时消息）。该参数对应 VIVO 推送服务的category字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定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 字段。在 iOS 15 及以上版本中，系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知（例如余额变化）无法及时被用户感知的情况，可考虑设置该字段。pushConfigs.FCM.channelId String 否 FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见安卓官方文档。 pushConfigs.FCM.collapse_key String 否 适用于 Android 平台。可以折叠的一组消息的标识符，以便在可以恢复传递时仅发送最后一条消息。 pushConfigs.FCM.imageUrl String 否 适用于 Android 平台。FCM 推送自定义的通知栏消息右侧图标 URL，如果不设置，则不展示通知栏右侧图标。 - 图片的大小上限为 1MB。
- 要求控制台 FCM 推送配置为证书与通知消息方式。
pushConfigs.OHOS.category String 否 鸿蒙系统场景化推送的通知消息类别，例如 IM。完成自分类权益申请后，用于标识通知消息类型，不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明。 pushConfigs.OHOS.image String 否 通知右侧大图标 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/private/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":["pushdata","{c}{e}"],
"verifyBlacklist":0,
"disablePush":false,
"expansion":false
}
上面示例中用户 ID 为 21 的用户，收到信息为 123，上面示例中用户 ID 为 22 的用户，收到信息为 456。
提示
如 content 中定义了标识 {d} ，则在 values 中需要对 {d} 进行设置，否则 {d} 会以文本方式随消息一起发送给用户。toUserId、values、pushContent、pushData 的数量必须相等。
返回结果
HTTP 响应正文包含具有以下结构的 JSON 对象：
| 返回值 | 返回类型 | 说明 |
|---|---|---|
| code | Number | 返回码，200 为正常。 |
| messageUIDs | Array | 返回 messageUID 列表 |
| messageUIDs[i].userId | String | 接收方用户 ID， 和请求 toUserId 对应 |
| messageUIDs[i].messageUID | String | 发送给对应接收方的消息的唯一 ID |
返回结果示例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"messageUIDs": [
{
"userId": "2193",
"messageUID": "XXXX-JJJJ-KKK-LLLL"
},
{
"userId": "2192",
"messageUID": "XXXX-JJJJ-KKK-LLKL"
}
]
}