发送应用包名通知

App 用户可以向 App 下指定应用包名的全部用户发送系统会话消息，该功能称为「应用包名通知」。

例如，客户通过控制台创建了一个应用，该应用下有两个客户端：学生端、教师端（通过创建两个应用包名实现），当需要给所有使用学生端或教师端的用户发送运营消息时，可使用此功能接口实现。

标签用户通知、应用包名通知与全量用户不落地通知使用同一个 /push.json 接口，共享请求结构、推送参数、返回结果和调用频率配额，通过 audience 中的筛选条件区分接收人。其中，标签用户通知与应用包名通知需传入 message，发送系统会话消息；全量用户不落地通知不传入 message，仅发送推送通知，不产生会话。

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

假设发送一条文本消息（objectName 为 RC:TxtMsg，属于客户端 SDK 会存储的内置消息类型，且可触发离线推送），效果如下：

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

提示

Web 端用户不参与按应用包名的接收人筛选：包名筛选基于已上报推送 deviceId 的客户端，仅使用 Web 端的用户不会被命中。已被命中的用户若同时在 Web 端登录，仍会在 Web 端收到该条消息。终端用户收到系统消息后，不支持消息回复功能。

开通服务

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

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

请求方法

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

调用频率：共享 /push.json 的限频配额，即每小时限发送 2 次，每天（自然日）最多发送 3 次。即时通讯服务端按应用包名推送的处理能力为每秒钟 2000 条，即每秒钟可以向 2000 个目标用户下发消息。该接口支持调整频率（可调频），可在控制台 > IM 服务 > 服务购买 > 调频服务中调整。

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

正文参数

按应用包名发送时，设置 audience.packageName，将 audience.is_to_all 设为 false，并且不要传入 audience.userid、audience.tag 或 audience.tag_or。

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

参数	类型	必传	说明
platform	String[]	是	目标操作系统，iOS、Android、HarmonyOS 最少传递一个。如果需要给三个系统推送消息时，则需要全部填写，发送时如目标用户在 Web 端登录也会收到此条消息。
fromuserid	String	是	发送人用户 ID。 注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。
audience	Object	是	接收人筛选条件。支持按用户 ID（userid）、用户标签（tag、tag_or）、应用包名（packageName）筛选，或通过 is_to_all 向指定平台的全部用户发送。
audience.userid	String[]	否	用户 ID 数组，每次最多 1000 个。is_to_all 为 false 且数组非空时，按用户 ID 发送，platform 不再限制目标平台，tag、tag_or 和 packageName 不参与接收人筛选。is_to_all 为 true 时，此参数无效。
audience.tag	String[]	否	用户标签，每次最多 20 个，标签之间为 AND 关系。与 tag_or 同时传入时，接收人需要同时满足两组标签条件。is_to_all 为 true 或 userid 非空时，此参数不参与接收人筛选。
audience.tag_or	String[]	否	用户标签，每次最多 20 个，标签之间为 OR 关系。可与 tag 同时传入。is_to_all 为 true 或 userid 非空时，此参数不参与接收人筛选。
audience.packageName	String	否	应用包名。发送系统会话消息时，仅在 is_to_all 为 false，且 userid、tag、tag_or 均为空或未传入时，按此包名筛选接收人。与 tag 或 tag_or 同时传入时，按标签筛选，不会与包名取交集。
audience.is_to_all	Boolean	否	是否向指定平台的全部用户发送，默认为 false。为 true 时，忽略 userid、tag、tag_or 和 packageName；为 false 时，按上述条件筛选接收人。
message.content	String	是	所发送消息的内容。2026 年 5 月 29 日起，新注册客户的除图片消息（RC:ImgMsg）、流式消息（RC:StreamMsg）、语音消息（RC:VcMsg）、视频消息（RC:SightMsg）、位置消息（RC:LBSMsg）、合并转发消息（RC:CombineV2Msg，RC:CombineMsg）、引用消息（RC:ReferenceMsg）外，其他消息的 content 消息体大小限制不超过 10 KB。 内置消息类型：将消息内容体 JSON 对象序列化为 JSON 字符串传入。消息内容 JSON 结构体详见消息类型概述中各内置消息类型的消息内容格式。 例如，文本消息内容 JSON 结构体内部包含 content 字段（此为 JSON 结构体内的 key 值，注意区分），则需要将 {"content":"Hello world!"} 序列化后的结果作为此处 content 字段的值。 自定义消息类型（objectName 字段必须指定为自定义消息类型）：如果发送自定义消息，该参数可自定义格式，不限于 JSON。
message.objectName	String	是	消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。 注意：在自定义消息时，消息类型不可以 “RC:” 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
message.isPersisted	Int	否	是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储（依赖单群聊消息云端存储服务）。 此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。 提示：一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外： 如果消息属于内置消息类型，客户端 SDK 会根据消息类型本身的存储属性标识判断是否存入本地数据库。详见消息类型概述。 如果消息属于自定义消息类型，则客户端 SDK 会根据该类型在客户端上注册时的存储属性标识判断是否需要存入本地数据库。 如果消息属于客户端 App 上未注册自定义消息类型（例如客户端使用的 App 版本过旧），则客户端 SDK 会根据当前参数值确定是否将消息存储在本地。但因消息类型未注册，客户端无法解析显示该消息。
message.isCounted	Int	否	是否计入未读消息数。0 表示不计数；1 表示计数，默认值为 1。 此参数仅影响服务端维护的未读数。客户端 SDK 是否将收到的消息计入本地未读数，取决于消息类型的计数属性： 内置消息类型：由消息类型本身的计数属性决定。 自定义消息类型：由客户端注册该消息类型时设置的计数属性决定。
message.disableUpdateLastMsg	Boolean	否	禁止更新会话最后一条消息。 当该参数为 false 时，发送的该条消息都会进入会话列表; 为 true 时，不会更新到会话列表的消息内容。 注：此参数仅对存储在客户端的消息有效。
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 格式。
  mi.templateId	String	否	小米推送模板 ID，从小米推送运营平台获取。设置后，推送中的 title 和 pushContent 对小米推送不生效。若未设置，系统将使用控制台配置的 App Key 级默认模板。
  mi.templateParam	Object	否	小米推送模板参数，Key/Value 格式，最多 9 个 Key。Key 需与模板预配置参数格式一致，单条消息 Key 不能重复。推送模板标题结构中，文案+变量字数不超过 50 个字符；内容结构中，文案+变量字数不超过 128 个字符；详细见小米推送模板指南。
  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 推送配置为证书与通知消息方式。
  meizu.noticeMsgType	Number	否	魅族推送消息类型定义。 1：私信消息; 2：公信消息。 详见魅族推送消息分类说明。
  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 端进行解析。

请求示例

HTTP

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":{
    "packageName":"xxx.rong.xxx",
    "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"
        },
        "meizu":{
            "noticeMsgType":1
        },
        "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

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

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