跳到主要内容

发送系统通知模板消息

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

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

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

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

如何配置与使用消息模板

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

定义内容模板

发送消息时,可在 contentpushContentpushData 字段中传入带标识位的字段内容,例如:

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

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

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

指定模板内容标识位的值

按照收件人列表(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 TomHello JerryHello 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所发送消息的内容,单条消息最大 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
contentAvailableInt针对 iOS 平台,对 SDK 处于后台暂停状态时为静默推送,是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码,且能够马上执行。详情请查看知识库文档。1 表示为开启,0 表示为关闭,默认为 0
disablePushBoolean是否为静默消息,默认为 false,设为 true 时终端用户离线情况下不会收到通知提醒。

请求示例

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