发送标签用户通知

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

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

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

例如，对于一般的 App 业务通知来说，假设发送一条文本消息（objectName 为 RC: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 对象：

参数	类型	必传	说明
platform	String[]	是	目标操作系统，iOS、Android 最少传递一个。如果需要给两个系统推送消息时，则需要全部填写，发送时如目标用户在 Web 端登录也会收到此条消息。
fromuserid	String	是	发送人用户 ID。 注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。
audience	Object	是	推送条件。支持按用户 ID 推送，按用户标签推送（tag 、tag_or）、按应用包名推送（packageName）和按指定平台全部推送（is_to_all）。注意：如果推送条件中 is_to_all 为 true，则忽略其他推送条件。
audience.userid	String[]	否	用户 ID 数组。如果 userid 有值，则 platform、tag、tagItems 均无效。如果 is_to_all 为 true，则当前参数无效。每次发送时最多发送 1000 个用户。
audience.tag	String[]	否	用户标签，每次发送时最多发送 20 个标签，标签之间为 AND 的关系，is_to_all 为 true 时参数无效。
audience.tag_or	String[]	否	用户标签，每次发送时最多发送 20 个标签，标签之间为 OR 的关系，is_to_all 为 true 时参数无效，tag_or 同 tag 参数可以同时存在。
audience.is_to_all	Boolean	是	是否全部推送，false 表示按 tag 、tag_or 或 userid 条件推送，true 表示向所有用户推送，tag、tag_or 和 userid 条件无效。
message.content	String	是	所发送消息的内容，单条消息最大 128k。 内置消息以 JSON 方式进行数据序列化，消息中可选择是否携带用户信息。您可以在内置消息类型（ 见消息类型概述）中找到消息结构示例。 如果 objectName 为自定义消息类型，该参数可自定义格式，不限于 JSON。
message.objectName	String	是	消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。 注意：在自定义消息时，消息类型不可以 “RC:” 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
notification	Object	是	按操作系统类型推送通知内容，如 platform 中设置了给 iOS 和 Android 系统推送消息，而在 notification 中只设置了 iOS 的推送内容，则 Android 的推送内容为最初 alert 设置的内容。
notification.title	String	否	通知栏显示标题，最长不超过 50 个字符。
notification.forceShowPushContent	Int	否	是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。 说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent 为 1 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。
notification.alert	String	否	推送通知内容。注意，如果此处 notification.alert 不传，则必须在 notification.ios.alert 和 notification.android.alert 分别指定 iOS 和 Android 下的推送通知内容，否则无法正常推送。一旦指定了各平台推送内容，则推送内容以对应平台系统的 alert 为准。如果都不填写，则无法发起推送。
notification.ios	Object	否	设置 iOS 平台下的推送及附加信息。详细查看 ios 参数结构说明。
notification.android	Object	否	设置 Android 平台下的推送及附加信息。详细查看 android 参数结构说明。
notification.harmonyOS	Object	否	设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明。

• notification.ios 参数结构说明

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

• notification.android 结构说明

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

• notification.harmonyOS 结构说明

  参数	类型	必传	说明
  alert	String	否	鸿蒙平台下推送消息内容，传入后默认的推送消息内容失效。
  ohos.category	String	否	鸿蒙系统场景化推送的通知消息类别。完成自分类权益申请后，用于标识通知消息类型，不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明。
  ohos.image	String	否	通知右侧大图标URL，URL使用的协议必须是HTTPS协议，取值样例：https://example.com/image.png。 说明：支持图片格式为png、jpg、jpeg、bmp，图片长宽建议小于 128128 像素，若超过 49152 像素，则图片不展示。
  extras	JSONObject	否	附加信息，如果开发者自己需要，可以自己在 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",
            "category": "IM",
            "notify_level": 2
        },  
        "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 对象：

返回值	返回类型	说明
code	Number	返回码，200 为正常。
id	String	推送唯一标识，和 messageUID 一致。
messageUID	String	返回消息 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"
}