跳到主要内容

发送单聊模板消息

应用下的用户可向其他用户发送单聊模板消息。通过您自定义的模板，可实现一次向多个用户发送不同的消息内容。例如，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 对象：

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

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

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
valuesArray of objects是为消息内容（content）、推送通知内容（pushContent）、推送数据（pushData）中的标识位（标识位示例：{d}）提供对应的值。
contentString是所发送消息的内容，单条消息最大 128k。
  • 内置消息类型：将消息内容体 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。
isIncludeSenderInt否是否向发件人客户端同步已发消息。1 表示同步，默认值为 0，即不同步。注意，仅设置该参数无法确保发件人客户端一定能获取到该条已发消息，您可能还需要启用其他服务。详见发件人客户端如何同步已发消息。
verifyBlacklistInt否是否过滤发送人黑名单列表，0 为不过滤、 1 为过滤，默认为 0 不过滤。
isPersistedInt否是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储（依赖单群聊消息云端存储服务）。

此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。

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

  • pushExt 参数说明

    pushExt 参数支持设置消息推送通知的标题、推送内容模板、是否强制通知及推送 ChannelID 等。pushExt 为 JSON 结构请求时需要做转义处理。

    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.MI.channelIdString否小米推送通知渠道的 ID，详细请参见 小米推送消息分类新规。
    pushConfigs.MI.large_icon_uriString否小米推送自定义通知栏消息的右侧图标 URL，若不设置，则不展示通知栏右侧图标。
    • 国内版仅 MIUI12 以上版本支持，以下版本均不支持；国际版支持。
    • 图片要求：大小 120 * 120px，格式为 png 或者 jpg 格式。
    pushConfigs.OPPO.channelIdString否OPPO 推送通知渠道的 ID，详细请参见 OPPO PUSH 通道升级说明。
    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 像素，则图片不展示。

  • 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 对象：

返回值返回类型说明
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": "2193",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "userId": "2192",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}