跳到主要内容

发送标签用户通知

App 用户可以向 App 下携带指定标签的用户发送系统会话消息,该功能称为「标签用户通知」。

该功能使用 /push.json 接口。

  • 用户标签需要通过设置用户标签批量设置用户标签 接口进行添加或移除。
  • 支持发送即时通讯服务预定义的消息类型(见消息类型概述)。消息的类型(objectName 字段)决定了消息是否支持离线推送通知,以及客户端在收到该消息后,是否展示在聊天界面、会话列表,是否存入本地数据库。
  • 支持发送客户自定义类型的消息。客户端在收到自定义消息后,是否展示在聊天界面、会话列表,是否存入本地数据库取决于客户端注册的自定义消息类型定义。
  • 只能通过即时通讯服务端 API 进行发送,会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。

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

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

开通服务

使用标签用户通知功能前,请确认已为当前 App Key 开通相关服务。详见全量用户通知服务配置

如未开通服务,Server API 将返回 1009 错误。注意,在未开通服务时,如果连续请求导致 API 请求频率超过限制,Server API 会返回 HTTP 429 Too Many Requests 错误(错误码为 1008)。

请求方法

POST: https://数据中心域名/push.json

调用频率:共享 /push.json 的限频配额,即每小时限发送 2 次,每天(自然日)最多发送 3 次。即时通讯服务端按标签推送的处理能力为每秒钟 1500 条,即每秒钟可以向 1500 个目标用户下发消息。如需超过此限制,请联系商务。

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

正文参数

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

参数类型必传说明
platformString[]目标操作系统,iOS、Android 最少传递一个。如果需要给两个系统推送消息时,则需要全部填写,发送时如目标用户在 Web 端登录也会收到此条消息。
fromuseridString发送人用户 ID。

注意:发送消息所使用的用户 ID 必须已获取过用户 Token,否则消息一旦触发离线推送,通知内无法正确显示发送者的用户信息。
audienceObject推送条件。支持按用户 ID 推送,按用户标签推送(tagtag_or)、按应用包名推送(packageName)和按指定平台全部推送(is_to_all)。注意:如果推送条件中 is_to_alltrue,则忽略其他推送条件。
audience.useridString[]用户 ID 数组。如果 userid 有值,则 platformtagtagItems 均无效。如果 is_to_alltrue,则当前参数无效。每次发送时最多发送 1000 个用户。
audience.tagString[]用户标签,每次发送时最多发送 20 个标签,标签之间为 AND 的关系,is_to_all 为 true 时参数无效。
audience.tag_orString[]用户标签,每次发送时最多发送 20 个标签,标签之间为 OR 的关系,is_to_all 为 true 时参数无效,tag_or 同 tag 参数可以同时存在。
audience.is_to_allBoolean是否全部推送,false 表示按 tag 、tag_or 或 userid 条件推送,true 表示向所有用户推送,tag、tag_or 和 userid 条件无效。
message.contentString所发送消息的内容,单条消息最大 128k。

内置消息以 JSON 方式进行数据序列化,消息中可选择是否携带用户信息。您可以在内置消息类型( 见消息类型概述)中找到消息结构示例。

如果 objectName 为自定义消息类型,该参数可自定义格式,不限于 JSON。
message.objectNameString消息类型,接受内置消息类型(见消息类型概述)或自定义消息的消息类型值。

注意:在自定义消息时,消息类型不可以 “RC:” 开头,以免与系统内置消息类型重名;消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息,否则 SDK 收到该消息后将无法解析。
notificationObject按操作系统类型推送通知内容,如 platform 中设置了给 iOS 和 Android 系统推送消息,而在 notification 中只设置了 iOS 的推送内容,则 Android 的推送内容为最初 alert 设置的内容。
notification.titleString通知栏显示标题,最长不超过 50 个字符。
notification.forceShowPushContentInt是否越过客户端配置,强制在推送通知内显示通知内容(pushContent)。默认值 0 表示不强制,1 表示强制。

说明:客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时,可通过设置forceShowPushContent1 越过该配置,强制客户端针在此条消息的推送通知中显示推送内容。
notification.alertString推送通知内容。注意,如果此处 notification.alert 不传,则必须在 notification.ios.alertnotification.android.alert 分别指定 iOS 和 Android 下的推送通知内容,否则无法正常推送。一旦指定了各平台推送内容,则推送内容以对应平台系统的 alert 为准。如果都不填写,则无法发起推送。
notification.iosObject设置 iOS 平台下的推送及附加信息。详细查看 ios 参数结构说明
notification.androidObject设置 Android 平台下的推送及附加信息。详细查看 android 参数结构说明
notification.harmonyOSObject设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明
  • notification.ios 参数结构说明

    参数类型必传说明
    titleString通知栏显示的推送标题,仅针对 iOS 平台,支持 iOS 8.2 及以上版本。该属性优先级高于 notification.title
    contentAvailableInt针对 iOS 平台,静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码,且能够马上执行。详情请查看知识库文档。1 表示为开启,0 表示为关闭,默认为 0
    alertString推送通知内容,传入后默认的推送通知内容失效。
    badgeint应用角标,仅针对 iOS 平台;不填时,表示不改变角标数;为 0 或负数时,表示 App 角标上的数字清零;否则传相应数字表示把角标数改为指定的数字,最大不超过 9999,参数在 ios 节点下设置,详细可参考“设置 iOS 角标数 HTTP 请求示例”。
    thread-idStringiOS 平台通知栏分组 ID,相同的 thread-id 推送分一组,单组超过 5 条推送会折叠展示
    apns-collapse-idStringiOS 平台,从 iOS10 开始支持,设置后设备收到有相同 ID 的消息,会合并成一条
    categoryStringiOS 富文本推送的类型开发者自己定义,自己在 App 端进行解析判断,与 richMediaUri 一起使用,当设置 category 后,推送时默认携带 mutable-content 进行推送,属性值为 1。
    richMediaUriStringiOS 富文本推送内容的 URL,与 category 一起使用。
    interruption-levelString适用于 iOS 15 及之后的系统。取值为 passiveactive(默认),time-sensitive,或 critical,取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中,系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知(例如余额变化)无法及时被用户感知的情况,可考虑设置该字段。
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。
  • notification.android 结构说明

    参数类型必传说明
    alertStringAndroid 平台下推送通知内容,传入后默认的推送通知内容失效。
    honor.importanceString荣耀通知栏消息优先级,取值:
    • NORMAL(服务与通讯类消息)
    • LOW(咨询营销类消息)。若资讯营销类消息发送时带图片,图片不会展示。
    honor.imageString荣耀推送自定义通知栏消息右侧的大图标 URL,若不设置,则不展示通知栏右侧图标。
    • URL 使用的协议必须是 HTTPS 协议,取值样例:https://example.com/image.png
    • 图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp。
      超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    hw.channelIdString华为推送通知渠道的 ID。详见自定义通知渠道
    hw.importanceString华为推送通知栏消息优先级,取值 NORMAL、LOW,默认为 NORMAL 重要消息。
    hw.imageString华为推送自定义的通知栏消息右侧大图标 URL,如果不设置,则不展示通知栏右侧图标。URL 使用的协议必须是 HTTPS 协议,取值样例:https://example.com/image.png。图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp,超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    hw.categoryString华为推送通道的消息自分类标识,category 取值必须为大写字母,例如 IM。App 根据华为要求完成自分类权益申请申请特殊权限 后可传入该字段有效。详见华为推送官方文档消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。
    mi.channelIdString小米推送通知渠道的 ID。详见小米推送消息分类新规
    mi.large_icon_uriString小米推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。国内版仅 MIUI12 以上版本支持,以下版本均不支持;国际版支持。图片要求:大小120 * 120px,格式为 png 或者 jpg 格式。
    oppo.channelIdStringoppo 推送通知渠道的 ID。详见推送私信通道申请
    vivo.classificationStringVIVO 推送服务的消息类别。可选值 0(运营消息,默认值) 和 1(系统消息)。该参数对应 VIVO 推送服务的 classification 字段,见 VIVO 推送消息分类说明 。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
    vivo.categoryStringVIVO 推送服务的消息二级分类。例如 IM(即时消息)。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ,必须同时传入与当前二级分类匹配的 classification 字段的值(系统消息场景或运营消息场景)。请注意遵照 VIVO 官方要求,确保二级分类(category)取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
    fcm.channelIdStringGoogle FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道,然后才能收到具有此频道 ID 的任何通知。更多信息请参见 Android 官方文档
    fcm.collapse_keyStringGoogle FCM 推送中可以折叠的一组消息的标识符,以便在可以恢复传递时仅发送最后一条消息。
    fcm.imageUrlStringGoogle FCM 推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。
    • 图片的大小上限为 1MB。
    • 要求控制台 FCM 推送配置为证书通知消息方式
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。
  • notification.harmonyOS 结构说明

    参数类型必传说明
    alertString鸿蒙平台下推送消息内容,传入后默认的推送消息内容失效。
    ohos.categoryString鸿蒙系统场景化推送的通知消息类别。完成自分类权益申请后,用于标识通知消息类型,不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明
    ohos.imageString通知右侧大图标URL,URL使用的协议必须是HTTPS协议,取值样例:https://example.com/image.png
    说明:支持图片格式为png、jpg、jpeg、bmp,图片长宽建议小于 128128 像素,若超过 49152 像素,则图片不展示。
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。

请求示例

POST /push.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1585127132438
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/json

{
"platform":["ios","android"],
"fromuserid": "fromuseId1",
"audience":{
"tag":["女","年轻"],
"tag_or":["北京","上海"],
"userid":["123","456"],
"is_to_all":false
},
"message": {
"content": "{\"content\":\"1111\",\"extra\":\"aa\"}",
"objectName": "RC:TxtMsg"
},
"notification":{
"title":"标题",
"forceShowPushContent":0,
"alert":"this is a push",
"ios":
{
"alert": "override alert",
"thread-id":"223",
"apns-collapse-id":"111",
"extras": {"id": "1","name": "2"}
},
"android": {
"alert": "override alert",
"hw":{
"channelId":"NotificationKanong",
"importance": "NORMAL",
"image":"https://example.com/image.png"
},
"mi":{
"channelId":"rongcloud_kanong",
"large_icon_uri":"https://example.com/image.png"
},
"oppo":{
"channelId":"rc_notification_id"
},
"vivo":{
"classification":"0"
},
"extras": {"id": "1","name": "2"}
},
"harmonyOS": {
"ohos":{
"category":"IM",
"image":"https://example.com/image.png"
},
"extras": {"id": "1","name": "2"}
}
}
}

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

返回值返回类型说明
codeNumber返回码,200 为正常。
idString推送唯一标识,和 messageUID 一致。
messageUIDString返回消息 ID。

返回结果示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"code": 200,
"id": "XXXX-JJJJ-KKK-LLLL",
"messageUID": "XXXX-JJJJ-KKK-LLLL"
}