跳到主要内容

发送单聊普通消息

应用下的用户可向其他用户发送单聊消息。

  • 单次支持向单个或多个用户发送单聊消息，单次最多向 1000 个用户发送消息。
  • 通过该接口发送的消息，默认不会向消息发件人客户端同步，也不会存入发件用户的历史消息记录。如需同步，请参见 isIncludeSender 参数用法。

请求方法​

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

频率限制： 每分钟限发送 6000 条信息。请注意，如果一次发送给 1000 人，视为 1000 条消息。另见已知问题 1。

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

正文参数​

HTTP 请求正文数据格式为 application/x-www-form-urlencoded，支持以下 HTTP 表单参数：

参数类型必传说明
fromUserIdString是发送人用户 ID。

注意：发送消息所使用的用户 ID 必须已获取过用户 Token，否则消息一旦触发离线推送，通知内无法正确显示发送者的用户信息。
toUserIdString是接收用户 ID，可以实现向多人发送消息，每次上限为 1000 人。
objectNameString是消息类型，接受内置消息类型（见消息类型概述）或自定义消息的消息类型值。

注意：在自定义消息时，消息类型不可以 "RC:" 开头，以免与系统内置消息类型重名；消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息，否则 SDK 收到该消息后将无法解析。
contentString是所发送消息的内容，单条消息最大 128k。
  • 内置消息类型：将消息内容体 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。
isIncludeSenderInt否是否向发件人客户端同步已发消息。1 表示同步，默认值为 0，即不同步。注意，仅设置该参数无法确保发件人客户端一定能获取到该条已发消息，您可能还需要启用其他服务。详见发件人客户端如何同步已发消息。
countInt否仅目标用户为 iOS 设备有效，Push 时用来控制桌面角标未读消息数，只有在 toUserId 为一个用户 ID 时有效，客户端获取远程推送内容时为 badge。具体参见 iOS 客户端文档「APNs 推送开发指南」目录下的集成 APNs 远程推送。为 -1 时不改变角标数，传入相应数字表示把角标数改为指定的数字，最大不超过 9999。
verifyBlacklistInt否是否过滤接收用户黑名单列表，0 表示为不过滤、 1 表示为过滤，默认为 0。
isPersistedInt否是否需要为收件人在历史消息云端存储服务中存储此条消息。0 表示不存储；1 表示存储。默认值为 1，存储（依赖单群聊消息云端存储服务）。

此属性不影响离线消息功能，用户未在线时都会转为离线消息?存储。

提示：一般情况下（第 1、2 种情况），客户端是否存储消息不依赖此参数。以下第 3 种情况属于例外：
  1. 如果消息属于内置消息类型，客户端 SDK 会根据消息类型本身的存储属性标识判断是否存入本地数据库。详见消息类型概述。
  2. 如果消息属于自定义消息类型，则客户端 SDK 会根据该类型在客户端上注册时的存储属性标识判断是否需要存入本地数据库。
  3. 如果消息属于客户端 App 上未注册自定义消息类型（例如客户端使用的 App 版本过旧），则客户端 SDK 会根据当前参数值确定是否将消息存储在本地。但因消息类型未注册，客户端无法解析显示该消息。
contentAvailableInt否仅目标用户为 iOS 设备时有效，应用处于后台暂停状态时为静默推送，是 iOS7 之后推出的一种推送方式。允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0。
expansionBoolean否是否为可扩展消息，默认为 false，设为 true 时终端在收到该条消息后，可对该条消息设置扩展信息。

移动端 SDK 4.0.3 版本、Web 端 3.0.7 版本支持此功能。
extraContentObject否仅在 expansion 为 true 时有效。

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

KV 详细要求：以 Key、Value 的方式进行设置，如：{"type":"3"}。Key 最大 32 个字符，支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式，不支持汉字。Value 最大 4096 个字符。单次可设置最多 100 对 KV 扩展信息，单条消息最多可设置 300 对 KV 扩展信息。
disablePushBoolean否是否为静默消息，默认为 false，设为 true 时终端用户离线情况下不会收到通知提醒。
pushExtString否配置消息的推送通知，如推送通知的标题等。disablePush 属性为 true 时此属性无效。具体请查看下方 pushExt 参数说明。

  • 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.OPPO.channelIdString否OPPO 推送通知渠道的 ID，详细请参见 OPPO PUSH 通道升级说明。
    pushConfigs.VIVO.classificationNumber否VIVO 推送服务的消息类别。可选值 0（运营消息，默认值） 和 1（系统消息）。该参数对应 VIVO 推送服务的 classification 字段，见 VIVO 推送消息分类说明。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
    pushConfigs.VIVO.categoryString否VIVO 推送服务的消息二级分类。例如 IM（即时消息）。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ，必须同时传入与当前二级分类匹配的 classification 字段的值（系统消息场景或运营消息场景）。请注意遵照 VIVO 官方要求，确保二级分类（category）取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
    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 像素，则图片不展示。

  • pushExt 结构示例

    {
       "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"
               }
           },
           {
               "OPPO": {"channelId": "oppo-123"}
           },
           {
               "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"
               }
           }
       ]
    }

请求示例​

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

content=%7B%22content%22%3A%22hello%22%2C%22extra%22%3A%22helloExtra%22%7D&fromUserId=2191&toUserId=2193&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=%7B%22pushData%22%3A%22hello%22%7D&count=4&verifyBlacklist=0&isPersisted=1&isIncludeSender=0&disablePush=false&expansion=false

返回结果​

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

返回值返回类型说明
codeNumber返回码，200 为正常。
messageUIDsArraymessageUID 列表
messageUIDs[i].userIdString接收方用户 ID， 和请求中的 toUserId 对应
messageUIDs[i].messageUIDString发送给对应接收用户的消息的唯一 ID

返回结果示例​

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

{
    "code": 200,
    "messageUIDs": [
        {
            "userId": "2193",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "userId": "2192",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}
最后于 更新