跳到主要内容

发送消息

IMKit 内置会话页面已实现了发送各类型消息的功能和 UI（部分消息类型需要插件支持）。当您在自定义页面需要发送消息时，可使用 IMKit 核心类 IMCenter 下发送消息的方法。这些方法除了提供发送消息的功能外，还会触发 IMKit 内置页面的更新。

IMKit 支持发送普通消息和媒体类消息（参考消息介绍），普通消息父类是 MessageContent，媒体消息父类是 MediaMessageContent。发送媒体消息和普通消息本质的区别为是否有上传数据过程。

重要

  • 请务必使用 IMKit 核心类 IMCenter 下发送消息的方法，否则不会触发页面刷新。发送普通消息使用 sendMessage 方法，发送媒体消息使用 sendMediaMessage 方法。
  • 客户端 SDK 发送消息存在频率限制，每秒最多只能发送 5 条消息。

发送普通消息​

发送消息前需要构造 Message 消息对象。消息的 content 字段中必须包含普通消息内容（即 MessageContent 的子类），如文本消息（TextMessage）。

接口​

Java
IMCenter.getInstance().sendMessage(message, pushContent, pushData, callback);

参数说明​

参数类型说明
messageMessage要发送的消息体。详见消息介绍 中对 Message 的结构说明。
pushContentString修改或指定远程消息推送通知栏显示的内容。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
  • 如果希望使用融云默认推送通知内容，可以填 null。注意自定义消息类型无默认值。
  • 如果要为该条消息指定个性化的离线推送通知，必须在以上任一处向融云提供 pushContent 字段内容。
  • 如果您自定义的消息类型需要离线推送服务，必须在以上任一处向融云提供 pushContent 字段内容，否则用户无法收到离线推送通知。
pushDataString远程推送附加信息。如果设置该字段，用户在收到远程推送消息时，能通过 io.rong.push.notification.PushNotificationMessage#getPushData()方法获取。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
callbackISendMessageCallback发送消息的回调

示例代码​

Java
String targetId = "会话 Id";
ConversationType conversationType = ConversationType.PRIVATE;
TextMessage messageContent = TextMessage.obtain("消息内容");

Message message = Message.obtain(targetId, conversationType, messageContent);

IMCenter.getInstance().sendMessage(message, null, null, new IRongCallback.ISendMessageCallback() {

        @Override
        public void onAttached(Message message) {

        }

        @Override
        public void onSuccess(Message message) {

        }

        @Override
        public void onError(Message message, RongIMClient.ErrorCode errorCode) {

        }
    });

sendMessage 中直接提供了用于控制推送通知内容（pushContent）和推送附加信息（pushData）的参数。如果您需要更精细地控制离线推送通知，例如标题、内容、图标、或其他第三方厂商个性化配置，请使用消息推送属性进行配置，详见自定义消息推送通知。请注意，聊天室会话不支持离线消息机制，因此也不支持离线消息转推送。

  • 如果发送的消息属于 SDK 内置消息类型，例如 TextMessage，这两个参数可设置为 null。一旦消息触发离线推送通知时，融云服务端会使用各个内置消息类型默认的 pushContent 值。关于各类型消息的默认推送通知内容，详见用户内容类消息格式。
  • 如果消息类型为自定义消息类型，且需要支持离线推送通知，则必须向融云提供 pushContent 字段，否则用户无法收到离线推送通知。
  • 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段留空。
  • Message 的推送属性配置 MessagePushConfig 的 pushContent 和 pushData 会覆盖此处配置，并提供更多配置能力，例如自定义推送通知的标题。详见自定义消息推送通知。

发送媒体消息​

媒体消息 Message 对象的 content 字段必须传入 MediaMessageContent 的子类对象，表示媒体消息内容。例如图片消息（ImageMessage）、GIF 消息（GIFMessage）等。其他内置媒体消息类型包括文件消息（FileMessage）、位置消息（LocationMessage）、高清语音消息（HQVoiceMessage）、小视频消息（SightMessage），建议先集成相应的 IMKit 插件。

图片消息内容（ImageMessage）支持设置为发送原图。

Java
String targetId = "目标 ID";
ConversationType conversationType = ConversationType.PRIVATE;
Uri localUri = Uri.parse("file://图片的路径");//图片本地路径，接收方可以通过 getThumUri 获取自动生成的缩略图 Uri
boolean mIsFull = true; //是否发送原图
ImageMessage mediaMessageContent = ImageMessage.obtain(localUri, mIsFull);

Message message = Message.obtain(targetId, conversationType, mediaMessageContent);

发送媒体消息需要使用 sendMediaMessage 方法。SDK 会为图片、小视频等生成缩略图，根据默认压缩配置进行压缩，再将图片、小视频等媒体文件上传到融云默认的文件服务器（文件存储时长），上传成功之后再发送消息。图片消息如已设置为发送原图，则不会进行压缩。

Java
IMCenter.getInstance().sendMediaMessage(message, null, null, new IRongCallback.ISendMediaMessageCallback() {
    @Override
    public void onProgress(Message message, int i) {

    }

    @Override
    public void onCanceled(Message message) {

    }

    @Override
    public void onAttached(Message message) {

    }

    @Override
    public void onSuccess(Message message) {

    }

    @Override
    public void onError(final Message message, final RongIMClient.ErrorCode errorCode) {

    }
});

sendMediaMessage 中直接提供了用于控制推送通知内容（pushContent）和推送附加信息（pushData）的参数。如果您需要更精细地控制离线推送通知，例如标题、内容、图标、或其他第三方厂商个性化配置，请使用消息推送属性进行配置，详见自定义消息推送通知。请注意，聊天室会话不支持离线消息机制，因此也不支持离线消息转推送。

  • 如果发送的消息属于 SDK 内置的媒体消息类型，例如 ImageMessage，这两个参数可设置为 null。一旦消息触发离线推送通知时，融云服务端会使用各个内置消息类型默认的 pushContent 值。关于各类型消息的默认推送通知内容，详见用户内容类消息格式。
  • 如果消息类型为自定义消息类型，且需要支持离线推送通知，则必须向融云提供 pushContent 字段，否则用户无法收到离线推送通知。
  • 如果消息类型为自定义消息类型，但不需要支持远程推送通知（例如通过自定义消息类型实现的 App 业务层操作指令），可将 pushContent 字段留空。
  • Message 的推送属性配置 MessagePushConfig 的 pushContent 和 pushData 会覆盖此处配置，并提供更多配置能力，例如自定义推送通知的标题。详见自定义消息推送通知。
参数类型说明
messageMessage要发送的消息体。消息的 content 字段必须为媒体消息内容 MediaMessageContent。详见消息介绍 中对 Message 的结构说明。
pushContentString修改或指定远程消息推送通知栏显示的内容。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
  • 如果希望使用融云默认推送通知内容，可以填 null。注意自定义消息类型无默认值。
  • 如果要为该条消息指定个性化的离线推送通知，必须在以上任一处向融云提供 pushContent 字段内容。
  • 如果您自定义的消息类型需要离线推送服务，必须在以上任一处向融云提供 pushContent 字段内容，否则用户无法收到离线推送通知。
pushDataString远程推送附加信息。如果设置该字段，用户在收到远程推送消息时，能通过 io.rong.push.notification.PushNotificationMessage#getPushData()方法获取。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
callbackISendMediaMessageCallback发送多媒体消息的回调

发送多媒体消息并且上传到自己的服务器​

SDK 支持由 App 自行处理媒体文件上传逻辑（可上传到自己的服务器），然后再发送消息，同时 SDK 会更新 UI 状态。

您需要使用 sendMediaMessage 方法发送媒体消息，在回调接口 ISendMediaMessageCallbackWithUploader 的 onAttached 回调方法中自行实现媒体文件上传，并上传成功后通知 SDK，并提供回媒体文件的远端地址。

接口​

Java
RongIM.getInstance().sendMediaMessage(message, null, null, callback);

参数说明​

参数类型说明
messageMessage发送消息的实体
pushContentString修改或指定远程消息推送通知栏显示的内容。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
  • 如果希望使用融云默认推送通知内容，可以填 null。注意自定义消息类型无默认值。
  • 如果要为该条消息指定个性化的离线推送通知，必须在以上任一处向融云提供 pushContent 字段内容。
  • 如果您自定义的消息类型需要离线推送服务，必须在以上任一处向融云提供 pushContent 字段内容，否则用户无法收到离线推送通知。
pushDataString远程推送附加信息。如果设置该字段，用户在收到远程推送消息时，能通过 io.rong.push.notification.PushNotificationMessage#getPushData()方法获取。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
callbackISendMediaMessageCallbackWithUploader发送多媒体消息并上传到自己服务器的回调。IRongCallback 中的 MediaMessageUploader 可以直接参考 IRongCoreCallback.MediaMessageUploader。

示例代码​

Java
String path = "file://图片的路径";
Uri localUri = Uri.parse(path);

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "会话 Id";
ImageMessage imageMessage = ImageMessage.obtain(localUri, localUri);

Message message = Message.obtain(targetId, conversationType, imageMessage);

RongIM.getInstance().sendMediaMessage(message, null, null, new IRongCallback.ISendMediaMessageCallbackWithUploader() {

     @Override
     public void onAttached(Message message, final MediaMessageUploader uploader) {
         /*上传图片到自己的服务器*/
         uploadImg(imgMsg.getPicFilePath(), new UploadListener() {
             @Override
             public void onSuccess(String url) {
                 // 上传成功，回调 SDK 的 success 方法，传递回图片的远端地址
                 uploader.success(Uri.parse(url));
             }


             @Override
             public void onProgress(float progress) {
                 //刷新上传进度
                 uploader.update((int) progress);
             }


             @Override
             public void onFail() {
                 // 上传图片失败，回调 error 方法。
                 uploader.error();
             }
         });
     }


     @Override
     public void onError(Message message, RongIMClient.ErrorCode errorCode) {
         //发送失败
     }


     @Override
     public void onSuccess(Message message) {
         //发送成功
     }


     @Override
     public void onProgress(Message message, int progress) {
         //发送进度
     }
 });

发送定向普通消息​

IMCenter 提供 sendDirectionalMessage 方法，支持向群组中特定的某些用户发送消息，会话中其他用户将不会收到此消息。

使用该方法发送普通定向消息前，不需要构造 Message 对象。请在 MessageContent 参数中直接传入 MessageContent 子类示例，例如文本消息（TextMessage）。

接口​

Java
IMCenter.getInstance().sendDirectionalMessage(conversationType, targetId, messageContent, userIds, pushContent, pushData, callback);

参数说明​

参数类型说明
conversationTypeConversationType会话类型，必须为 ConversationType.GROUP
targetIdString会话 Id
messageContentMessageContent消息的具体内容。只支持普通类型消息，不支持多媒体类型消息。
userIdsString[]会话中将会接收到此消息的用户列表.
pushContentString修改或指定远程消息推送通知栏显示的内容。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
  • 如果希望使用融云默认推送通知内容，可以填 null。注意自定义消息类型无默认值。
  • 如果要为该条消息指定个性化的离线推送通知，必须在以上任一处向融云提供 pushContent 字段内容。
  • 如果您自定义的消息类型需要离线推送服务，必须在以上任一处向融云提供 pushContent 字段内容，否则用户无法收到离线推送通知。
pushDataStringpush 附加信息。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
callbackIRongCallback.ISendMessageCallback发送消息的回调。

发送定向媒体消息​

IMCenter 提供 sendDirectionalMediaMessage 方法，支持向群组中特定的某些用户发送消息，会话中其他用户将不会收到此消息。

使用该方法发送普通定向消息前，不需要构造 Message 对象。请在 MessageContent 参数中直接传入 MessageContent 子类示例，例如文本消息（ImageMessage）。

接口​

Java
IMCenter.getInstance().sendDirectionalMessage(conversationType, targetId, messageContent, userIds, pushContent, pushData, callback);

参数说明​

参数类型说明
conversationTypeConversationType会话类型。必须为 ConversationType.GROUP
targetIdString会话 ID
messageContentMediaMessageContent媒体消息的具体内容。只支持多媒体型消息，不支持普通类型消息。
userIdsString[]会话中将会接收到此消息的用户列表.
pushContentString修改或指定远程消息推送通知栏显示的内容。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
  • 如果希望使用融云默认推送通知内容，可以填 null。注意自定义消息类型无默认值。
  • 如果要为该条消息指定个性化的离线推送通知，必须在以上任一处向融云提供 pushContent 字段内容。
  • 如果您自定义的消息类型需要离线推送服务，必须在以上任一处向融云提供 pushContent 字段内容，否则用户无法收到离线推送通知。
pushDataStringpush 附加信息。您也可以在 Message 的推送属性（MessagePushConfig）中配置，会覆盖此处配置，详见下文自定义消息推送通知。
callbackIRongCallback.ISendMediaMessageCallback发送消息的回调。

自定义消息推送通知​

IMKit 支持对单条消息的推送行为添加个性化配置（MessagePushConfig），但并未在 UI 上实现。如有需要，您可以在发送时拦截消息添加配置。拦截方式与为消息禁用推送通知一致。

在发送消息时，您可以通过设置消息的 MessagePushConfig 对象，对单条消息的推送行为进行个性化配置。例如：

  • 自定义推送标题、推送通知内容
  • 自定义通知栏图标
  • 添加远程推送附加信息
  • 越过接收客户端的配置，强制在推送通知内显示通知内容
  • 其他 APNs 或 Android 推送通道支持的个性化配置

相对于发送消息方法输入参数中的 pushContent 和 pushData，MessagePushConfig 中的配置具有更高优先级。发送消息时，如已配置 MessagePushConfig，则优先使用 MessagePushConfig 中的配置。

Java
Message message = Message.obtain(mTargetId, mConversationType, textMessage);
        MessagePushConfig messagePushConfig = new MessagePushConfig.Builder().setPushTitle(title)
                .setPushContent(content)
                .setPushData(data)
                .setForceShowDetailContent(forceDetail)
                .setAndroidConfig(new AndroidConfig.Builder()
                    .setNotificationId(id)
                    .setChannelIdHW(hw)
                    .setCategoryHW("IM")
                    .setChannelIdMi(mi)
                    .setChannelIdOPPO(oppo)
                    .setTypeVivo(vivo ? AndroidConfig.SYSTEM : AndroidConfig.OPERATE)
                    .setCategoryVivo("IM")
                    .build())
                .setIOSConfig(new IOSConfig(threadId, apnsId)).setTemplateId("")
                build();
        message.setMessagePushConfig(messagePushConfig);

        // 请根据消息类型调用对应的发送方法

MessagePushConfig 属性说明​

参数类型说明
disablePushTitleboolean是否屏蔽通知标题。此属性只针目标用户为 iOS 平台时有效，Android 第三方推送平台的通知标题为必填项，所以暂不支持。
pushTitleString推送标题，此处指定的推送标题优先级最高。如不设置，可参考 用户内容类消息格式 中对各内置消息类型默认推送通知标题与推送通知内容的说明。
pushContentString推送内容。此处指定的推送内容优先级最高。如不设置，可参考 用户内容类消息格式 中对各内置消息类型默认推送通知标题与推送通知内容的说明。
pushDataString远程推送附加信息。如不设置，则使用消息发送参数中设置的 pushData 值。
forceShowDetailContentboolean是否越过目标客户端的配置，强制在推送通知内显示通知内容（pushContent）。

客户端设备可通过 setPushContentShowStatus 设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。发送消息时，可设置 forceShowDetailContent 为 1 越过该配置，强制目标客户端在此条消息的推送通知中显示推送内容。
iOSConfigIOSConfigiOS 平台推送通知配置。目标端设备为 iOS 平台设备时，适用该配置。详细说明见 iOSConfig 属性说明。
androidConfigAndroidConfigAndroid 平台推送通知配置。目标端设备为 Android 平台设备时，适用该配置。详细说明见 AndroidConfig 属性说明。
templateIdString推送模板 ID。根据目标客户端用户通过 RongIMClient 中的 setPushLanguageCode 设置的语言环境，匹配模板 ID 所对应的模板中设置的语言内容进行推送。未匹配成功时使用默认内容进行推送。

模板内容在控制台 > 自定义推送文案中进行设置，具体操作请参见 配置和使用自定义多语言推送模板。

  • iOSConfig 属性说明

    参数类型说明
    threadIdStringiOS 平台通知栏分组 ID，相同的 threadId 推送分为一组（iOS10 开始支持）。
    apnsCollapseIdStringiOS 平台通知覆盖 ID，apnsCollapseId 相同时，新收到的通知会覆盖老的通知，最大 64 字节（iOS10 开始支持）。
    richMediaUriStringiOS 推送自定义的通知栏消息右侧图标 URL，需要 App 自行解析 richMediaUri 并实现展示。图片要求：大小 120 * 120px，格式为 png 或者 jpg 格式。SDK 从 5.2.4 版本开始支持携带该字段。
    interruptionLevelString适用于 iOS 15 及之后的系统。取值为 passive，active（默认），time-sensitive，或 critical，取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中，系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知（例如余额变化）无法及时被用户感知的情况，可考虑设置该字段。SDK 5.6.7 及以上版本支持该字段。

  • AndroidConfig 属性说明

    参数类型说明
    notificationIdStringAndroid 平台 Push 唯一标识，目前支持小米、华为推送平台，默认开发者不需要进行设置，当消息产生推送时，消息的 messageUId 作为 notificationId 使用。
    channelIdMiString小米推送通知渠道的 ID。详细使用方式及创建方法请参见第三方文档 小米推送消息分类新规。
    imageUrlMiString（由于小米官方已停止支持该能力，该字段已失效）小米通知类型的推送所使用的通知图片 url。图片要求：大小120 * 120px，格式为 png 或者 jpg 格式。
    此属性 5.1.7 及以上版本支持。支持 MIUI 国内版（国内版要求为 MIUI 12 及以上）和国际版。
    channelIdHWString华为推送通知渠道的 ID。详细使用方式及创建方法请参见第三方文档 华为自定义通知渠道。更多通知渠道信息，请参见 Android 官方文档。
    imageUrlHWString华为推送通知中自定义的通知栏消息右侧小图片 URL，如果不设置，则不展示通知栏右侧图片。图标文件须小于 512 KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp，超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    此属性 5.1.7 及以上版本支持。
    importanceHWString华为推送的消息提醒级别。LOW 表示通知栏消息预期的提醒方式为静默提醒，消息到达手机后，无铃声震动。NORMAL 表示通知栏消息预期的提醒方式为强提醒，消息到达手机后，以铃声、震动提醒用户。终端设备实际消息提醒方式将根据 categoryHW 字段取值、或者控制台配置的 category 字段取值，或者华为智能分类结果进行调整。SDK 5.1.3 及以上版本支持该字段。
    categoryHWString华为推送通道的消息自分类标识，默认为空。category 取值必须为大写字母，例如 IM。App 根据华为要求完成华为自分类权益申请 或 申请特殊权限 后可传入该字段有效。详见华为推送官方文档华为消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。SDK 5.4.0 及以上版本支持该字段。
    imageUrlHonorString荣耀推送通知中用户自定义的通知栏右侧大图标 URL，如果不设置，则不展示通知栏右侧图标。图标文件须小于 512 KB，图标建议规格大小：40dp x 40dp，弧角大小为 8dp，超出建议规格大小的图标会存在图片压缩或显示不全的情况。SDK 5.6.7 及以上版本支持该字段。
    importanceHonorString荣耀推送的 Android 通知消息分类，决定用户设备消息通知行为。LOW 表示资讯营销类消息。NORMAL（默认值）表示服务与通讯类消息。SDK 5.6.7 及以上版本支持该字段。
    typeVivoStringVIVO 推送服务的消息类别。可选值 0（运营消息） 和 1（系统消息）。该参数对应 VIVO 推送服务的 classification 字段，详见 VIVO 推送消息分类说明。
    categoryVivoStringVIVO 推送服务的消息二级分类。例如 IM（即时消息）。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明。如果指定二级分类 categoryVivo，必须同时指定 typeVivo（系统消息或运营消息）。请注意遵照 VIVO 官方要求，确保二级分类属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。categoryVivo 字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。SDK 5.4.2 及以上版本支持该字段。
    channelIdOPPOStringOPPO 推送通知渠道的 ID。详细使用方式及创建方法请参见第三方文档 OPPO PUSH 通道升级说明。
    channelIdFCMStringFCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见安卓官方文档。
    collapseKeyFCMStringFCM 推送的通知分组 ID。SDK 5.1.3 及以上版本支持该字段。注意，如使用该字段，请确保控制台的 FCM 推送配置中推送方式为通知消息方式。
    imageUrlFCMStringFCM 推送的通知栏右侧图标 URL。如果不设置，则不展示通知栏右侧图标。SDK 5.1.3 及以上版本支持该字段。注意，如使用该字段，请确保控制台的 FCM 推送配置鉴权方式为证书，推送方式为通知消息方式。

为消息禁用推送通知​

在接收者未上线时，融云服务端默认触发推送服务，将消息通过推送通道下发（服务端是否触发推送也会收到应用级别、用户级别免打扰设置的影响）。

有时 App 用户可能希望在发送消息时就指定该条消息不需要触发推送。IMKit 提供该能力，但并未在 UI 上实现。如有需要，可通过以下方式实现：

  1. 设置消息拦截监听器 MessageInterceptor，在 interceptOnSendMessage 回调中获取 Message 对象。返回 true 表示由 App 自行处理该消息。详见消息拦截。

  2. 将 messageConfig 的 disableNotification 属性设置为 true 禁用该条消息的推送通知。接收方再次上线时会通过融云服务端的离线消息缓存（最多缓存 7 天）自动收取单聊、群聊、系统会话消息。

    Java
    message.setMessageConfig(new MessageConfig.Builder().setDisableNotification(true).build());

  3. 调用发送消息方法重新发送消息。

最后于 更新