发送全量用户不落地通知

App 业务端可以向全部用户或指定用户群体发送「推送通知」，本质上是直接通过第三方或即时通讯服务自建的推送通道向 App 中所有用户推送一条通知。该功能只触发推送，不发送消息，不产生会话，称为「全量用户不落地通知」。

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

• 只能通过即时通讯服务端 API 进行发送。
• 「推送通知」的所有内容仅展现在通知栏。无论客户端 App 是否在前台，始终以通知形式展示在系统通知栏中。该功能不发送消息，不产生会话，因此用户无法在任何聊天会话中看到不落地通知的内容。
• 客户端不会存储不落地通知。
• 始终使用推送通道，因此不受客户端与即时通讯服务端之间的连接状态的影响。即使客户端不在前台、不在线（例如 App 被杀死），只要可正常接收推送，就可以收到不落地通知。
• 通过 audience 字段可以控制推送条件，支持按用户标签（tag）、用户 ID（userid）、应用包名（packageName）、全量用户（is_to_all）。其中用户标签需要 App 进行设置，详见设置用户标签、批量设置用户标签。

提示

• 即时通讯服务将 30 天内连接过 IM 服务的设备作为推送的目标。30 天内未打开过应用的设备，被视为应用已被卸载。
• 如果客户端设备不允许推送（断开连接时设置不允许推送），或遇到其他原因导致推送失败，则无法接收到不落地通知。

开通服务

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

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

请求方法

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

频率限制： 共享 /push.json 的限频配额，即每小时限发送 2 次，每天（自然日）最多发送 3 次。

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

正文参数

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

参数	类型	必传	说明
platform	String[]	是	目标操作系统，iOS、Android 最少传递一个。如果需要给两个系统推送消息时，则需要全部填写。
audience	Object	是	推送条件，包括：tag、userid 、packageName 、 is_to_all。
audience.tag	String[]	否	用户标签。每次发送时最多发送 20 个标签，标签之间为 AND 的关系，is_to_all 为 true 时参数无效。
audience.tag_or	String[]	否	用户标签。每次发送时最多发送 20 个标签，标签之间为 OR 的关系，is_to_all 为 true 时参数无效，tag_or 同 tag 参数可以同时存在。
audience.userid	String[]	否	用户 ID，每次发送时最多发送 1000 个用户，如果 tag 和 userid 两个条件同时存在时，则以 userid 为准，如果 userid 有值时，则 platform 参数无效，is_to_all为 true 时参数无效。
audience.packageName	String	否	应用包名，is_to_all 为 true 时，此参数无效。与 tag、tag_or 同时存在时为 And 的关系，向同时满足条件的用户推送。与 userid 条件同时存在时，以 userid 为准进行推送。
audience.is_to_all	Boolean	是	是否全部推送，false 表示按 tag 、tag_or 或 userid 条件推送，true 表示向所有用户推送，tag、tag_or 和 userid 条件无效。
notification	Object	是	按操作系统类型推送消息内容，如 platform 中设置了给 iOS 和 Android 系统推送消息，而在 notification 中只设置了 iOS 的推送内容，则 Android 的推送内容为最初 alert 设置的内容，详细查看 notification 参数结构说明。
notification.title	String	否	通知栏显示标题，最长不超过 50 个字符。
notification.forceShowPushContent	Int	否	是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。 说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent 为 1 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。
notification.alert	String	否	默认推送通知内容。如填写了 iOS 或 Android 下的 alert 时，则推送内容以对应平台系统的 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。详见推送私信通道申请。
  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"],
  "audience":{
    "tag":["女","年轻"],
    "tag_or":["北京","上海"],
    "userid":["123","456"],
    "is_to_all":true
  },
  "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 对象：

返回值	返回类型	说明
code	Number	返回码，200 为正常。
id	String	推送唯一标识。

返回结果示例

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

{"code":200,"id":"50whSR6kQiHb7YgFwQzXIb"}