跳到主要内容

发送超级群消息

提示
  • 如果您的应用/环境在 2022.10.13 日及以后开通超级群服务，超级群业务中会包含一个 ID 为 RCDefault 的默认频道。如果发消息时不指定频道 ID，则该消息会发送到 RCDefault 频道中。客户端 SDK 在获取 RCDefault 频道的历史消息时，需要传入该频道 ID。
  • 如果您的应用/环境在 2022.10.13 日前已开通超级群服务，在发送消息时如果不指定频道 ID，则该消息不属于任何频道。客户端 SDK 获取历史消息时，如果不传入频道 ID，可获取不属于任何频道的消息。即时通讯服务支持客户调整服务至最新行为。该行为调整将影响客户端、服务端收发消息、获取会话、清除历史消息、禁言等多个功能。如有需要，请提交工单咨询详细方案。

应用下的用户可以向应用下的单个超级群或多个超级群发送消息。通过 Server API 发送超级群消息时，终端用户在线状态下，发送者也会接收该消息，同时保存到该用户的历史消息中。

超级群消息发送成功后支持修改消息内容，详见修改超级群消息。

请求方法​

POST： https://数据中心域名/message/ultragroup/publish.json

频率限制： 每秒钟限发送 100 条超级群消息。单个频道每秒钟最多发送 20 条；不传频道参数时（busChannel），往指定群中发消息限每秒钟 20 条。请注意，如果一次向 3 个超级群发送消息，视为发送 3 条消息。

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

正文参数​

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

参数类型必传说明
fromUserIdString是发送人用户 ID，通过 Server API 非群成员也可以向群组中发送消息。

注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。
toGroupIdsString[]是接收群 ID，提供多个本参数可以实现向多群发送消息，最多不超过 3 个超级群。
toUserIdsString[]否发送超级群定向消息时，接收消息的群成员用户 ID 列表。列表之外的其他超级群用户无法收到该定向消息。注：仅当toGroupIds 传入单个超级群 ID 时有效。
objectNameString是消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
contentString是所发送消息的内容。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。
pushContentString否指定收件人离线时触发的远程推送通知中的通知内容。注意：对于部分消息类型，该字段是否有值决定了是否触发远程推送通知。
  • 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中的用户内容类消息格式，可不填写该字段，远程推送通知默认使用服务端预置的推送通知内容。
  • 如果消息类型（objectName 字段）为即时通讯服务预定义消息类型中通知类、信令类（"撤回命令消息" 除外），且需要支持远程推送通知，则必须填写 pushContent，否则收件人不在线时无法收到远程推送通知。如无需触发远程推送，可不填该字段。
  • 如果消息类型为自定义消息类型，且需要支持远程推送通知，则必须填写 pushContent 字段，否则收件人不在线时无法收到远程推送通知。
  • 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段留空禁用远程推送通知。
pushDataString否iOS 平台收到推送消息时，可从 payload 中获取 APNs 推送数据，对应字段名为 appData（提示：rc 字段中默认携带了消息基本信息）。Android 平台收到推送消息时对应字段名为 appData。
isPersistedInt否是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储。

一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外：
  1. 如果消息属于内置消息类型，客户端 SDK 会根据消息类型本身的存储属性标识判断是否存入本地数据库。详见消息类型概述。
  2. 如果消息属于自定义消息类型，则客户端 SDK 会根据该类型在客户端上注册时的存储属性标识判断是否需要存入本地数据库。
  3. 如果消息属于客户端 App 上未注册自定义消息类型（例如客户端使用的 App 版本过旧），则客户端 SDK 会根据当前参数值确定是否将消息存储在本地。但因消息类型未注册，客户端无法解析显示该消息。
isCountedInt否用户未在线时是否计入未读消息数。0 表示为不计数、1 表示为计数，默认为 1。
isMentionedInt否是否为 @ 消息，不传时默认为非 @ 消息（效果等于传 0）。如果需要发送 @ 消息，必须指定为 1，且必须在消息内容字段（content）内部携带 @ 相关信息（mentionedInfo，可参考下方请求示例）。关于 mentionedInfo 结构的详细说明，参见如何发送 @ 消息。
contentAvailableInt否针对 iOS 平台，对 SDK 处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
pushExtObject否配置消息的推送通知，如推送通知的标题等。具体请查看下方 pushExt 参数说明。
busChannelString否频道 Id，发消息时会对群 ID 下的频道 ID 做合法性校验，如果群 ID 下无此频道 ID 则服务端不会下发此条消息。支持大小写英文字母、数字的组合方式，不支持特殊字符，最长为 20 个字符。
expansionBoolean否是否为可扩展消息，默认为 false，设为 true 时终端在收到该条消息后，可对该条消息设置扩展信息
extraContentObject否仅在 expansion 为 true 时有效。

自定义的消息扩展信息，该字段接受 JSON 字符串格式的键值对（key-value pairs）。请注意区别于消息体内的 extra 字段，extraContent 的值在消息发送后可修改，修改方式请参见服务端 API 接口文档消息扩展，或参考各客户端「消息扩展」接口文档。

KV 详细要求：以 Key、Value 的方式进行设置，如：{"type":"3"}。Key 最大 32 个字符，支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式，不支持汉字。Value 最大 4096 个字符。单次可设置最多 100 对 KV 扩展信息，单条消息最多可设置 300 对 KV 扩展信息。
quoteString否引用消息信息，具体请查看下方 quote 参数说明。

  • pushExt 参数说明

    pushExt 参数支持设置消息推送通知的标题、推送内容模板、是否强制通知及推送 ChannelID 等。pushExt 为 JSON 结构请求时需要做转义处理。

    pushExt 参数类型必传说明
    titleString否通知栏显示标题，最长不超过 50 个字符，默认情况下通知标题单聊会话显示用户名称，群聊会话显示群名称。
    templateIdString否推送模板 ID，设置后根据目标用户通过 SDK 设置的语言环境，匹配模板中设置的语言内容进行推送，未匹配成功时使用默认内容进行推送，模板内容在“控制台-自定义推送文案”中进行设置。详情请查看 自定义多语言推送模板。
    forceShowPushContentNumber否是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。

    说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent 为 1 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。
    pushConfigsArray否按厂商设置不同推送属性。支持的推送通道值为 MI（小米）、HONOR（荣耀）、HW（华为）、OPPO、VIVO、APNs、FCM。
    pushConfigs.HONOR.importanceString否荣耀通知栏消息优先级，取值：
    • NORMAL（服务与通讯类消息）
    • LOW（咨询营销类消息）。若资讯营销类消息发送时带图片，图片不会展示。
    pushConfigs.HONOR.imageString否荣耀推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。
    • URL 使用的协议必须是 HTTPS 协议，取值样例：https://example.com/image.png。
    • 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。
      超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    pushConfigs.HW.channelIdString否华为推送通知渠道的 ID，详细请参见 华为自定义通知渠道。更多通知渠道信息，请参见 Android 官方文档。
    pushConfigs.HW.importanceString否华为通知栏消息优先级，取值：
    • NORMAL（默认值，重要信息）
    • LOW
    pushConfigs.HW.imageString否华为推送自定义通知栏消息右侧的大图标 URL，若不设置，则不展示通知栏右侧图标。
    • URL 使用的协议必须是 HTTPS 协议，取值样例：https://example.com/image.png。
    • 图标文件须小于 512KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp。
      超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    pushConfigs.HW.categoryString否华为推送通道的消息自分类标识，category 取值必须为大写字母，例如 IM。App 根据华为要求完成自分类权益申请 或 申请特殊权限 后可传入该字段有效。详见华为推送官方文档消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。
    pushConfigs.MI.channelIdString否小米推送通知渠道的 ID，详细请参见 小米推送消息分类新规。
    pushConfigs.MI.large_icon_uriString否小米推送自定义通知栏消息的右侧图标 URL，若不设置，则不展示通知栏右侧图标。
    • 国内版仅 MIUI12 以上版本支持，以下版本均不支持；国际版支持。
    • 图片要求：大小 120 * 120px，格式为 png 或者 jpg 格式。
    pushConfigs.MI.templateIdString否小米推送模板 ID，从小米推送运营平台获取。设置后，推送中的 title 和 pushContent 对小米推送不生效。若未设置，系统将使用控制台配置的 App Key 级默认模板。
    pushConfigs.MI.templateParamObject否小米推送模板参数，Key/Value 格式，最多 9 个 Key。Key 需与模板预配置参数格式一致，单条消息 Key 不能重复。Value 要求：1～128 字符，不能为纯空格，不支持 emoji 及特殊符号（Unicode Other Symbol 类，即 \p{So}），不支持未分配的 Unicode 字符。
    pushConfigs.OPPO.channelIdString否OPPO 推送通知渠道的 ID，详细请参见 OPPO PUSH 通道升级说明。
    pushConfigs.OPPO.categoryString否推送内容分类。详见OPUSH消息分类细则。
    pushConfigs.OPPO.notify_levelNumber否通知提醒类型，1 通知栏、2 通知栏+锁屏、16 通知栏+锁屏+横幅+震动+铃声；设置 category 后此字段有效。详见OPUSH消息分类细则。
    pushConfigs.VIVO.classificationNumber否vivo 推送通道类型。0：运营消息。1：系统消息。默认使用 App Key 在控制台 vivo 推送中设置的推送通道类型。详见 vivo 官方文档消息分类功能说明。
    pushConfigs.APNs.thread-idString否iOS 平台通知栏分组 ID。相同的 thread-id 推送分一组，单组超过 5 条推送会折叠展示。
    pushConfigs.APNs.apns-collapse-idString否适用于 iOS 平台。设置后设备收到有相同 ID 的消息，会合并成一条。
    仅支持 iOS 10.0 及以上版本。
    pushConfigs.APNs.richMediaUriString否适用于 iOS 平台。iOS 推送自定义的通知栏消息右侧图标 URL，需要 App 自行解析 richMediaUri 并实现展示。仅支持 iOS 10.0 及以上版本。
    pushConfigs.APNs.interruption-levelString否适用于 iOS 15 及之后的系统。取值为 passive，active（默认），time-sensitive，或 critical，取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中，系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知（例如余额变化）无法及时被用户感知的情况，可考虑设置该字段。
    pushConfigs.FCM.channelIdString否FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见安卓官方文档。
    pushConfigs.FCM.collapse_keyString否适用于 Android 平台。可以折叠的一组消息的标识符，以便在可以恢复传递时仅发送最后一条消息。
    pushConfigs.FCM.imageUrlString否适用于 Android 平台。FCM 推送自定义的通知栏消息右侧图标 URL，如果不设置，则不展示通知栏右侧图标。
    • 图片的大小上限为 1MB。
    • 要求控制台 FCM 推送配置为证书与通知消息方式。
    pushConfigs.OHOS.categoryString否鸿蒙系统场景化推送的通知消息类别，例如 IM。完成自分类权益申请后，用于标识通知消息类型，不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明。
    pushConfigs.OHOS.imageString否通知右侧大图标 URL，URL 使用的协议必须是 HTTPS 协议，取值样例为：https://example.com/image.png。
    说明：支持图片格式为png、jpg、jpeg、bmp，图片长宽建议小于 128*128 像素，若超过 49152 像素，则图片不展示。
    pushConfigs.MEIZU.noticeMsgTypeNumber否魅族推送消息类型定义。
    1：私信消息;
    2：公信消息。
    详见魅族推送消息分类说明。

  • pushExt 结构示例

    JSON
    {
       "title":"you have a new message.",
       "templateId":"123456",
       "forceShowPushContent":0,
       "pushConfigs": [
           {
               "HW": {
                 "channelId": "hw-123",
                 "importance": "NORMAL",
                 "image":"https://example.com/image.png"
               }
           },
           {
               "MI": {
                 "channelId": "mi-123",
                 "large_icon_uri":"https://example.com/image.png",
                 "templateId": "your_template_id",
                 "templateParam": {
                   "keywords1": "参数值1",
                   "keywords2": "参数值2"
                 }
               }
           },
           {
               "OPPO": {
                    "channelId": "oppo-123",
                    "notify_level": 2,
                    "category": "IM"
               }
           },
           {
               "VIVO" : {"classification": "0"}
           },
           {
               "APNs": {
                   "thread-id": "123",
                   "apns-collapse-id":"123456",
                   "richMediaUri":"https://example.com/image.png"
               }
           },
           {
               "FCM": {
                "channelId":"rongcloud_channelid",
                "collapse_key":"1234",
                "imageUrl":"https://example.com/image.png"
                }
           },
           {
               "OHOS": {
                 "category": "IM",
                 "image":"https://example.com/image.png"
               }
           },
           {
               "MEIZU": {
                 "noticeMsgType": 1
               }
           }
       ]
    }

  • quote 参数说明

    quote 参数类型必传说明
    msgUIDString是引用的原消息 ID
    objectNameString是消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。

    注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
    fromUserIdString是原消息的发送者 ID

  • quote 结构示例

    JSON
    {
       "msgUID":"XXXX-JJJJ-KKK-LLLL",
       "objectName":"RC:TxtMsg",
       "fromUserId":"userId1"
    }

请求示例​

HTTP
POST /message/ultragroup/publish.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/json

{
    "fromUserId":"why456",
    "objectName":"RC:TxtMsg",
    "content":"{\"content\":\"hh0217890\",\"mentionedInfo\":{\"type\":2,\"userIdList\":[\"123\",\"456\"],\"mentionedContent\":\"有人@你\"}}",
    "toGroupIds":["why66-ultra"],
    "isPersisted":1,
    "isMentioned":1}
}

返回结果​

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

返回值返回类型说明
codeNumber返回码，200 为正常。
messageUIDsArray返回 messageUID 列表
messageUIDs[i].groupIdString群组ID， 和请求 toGroupIds 对应
messageUIDs[i].messageUIDString发送给对应群组的消息的唯一 ID

返回结果示例​

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

{
    "code": 200,
    "messageUIDs": [
        {
            "groupId": "2191",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "groupId": "2192",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}