会话与消息

概述

会话

与一个聊天对象（用户、群组、聊天室等）之间的聊天。我们称之为一个会话。会话是消息的载体，消息一定是从属于某个会话对象的。

消息

极光 IM 最核心的功能是消息功能。核心能力包含以下：

  • 消息的及时下发；
  • 单聊，群聊，聊天室；
  • 消息类型：文本、语音、图片、文件、位置等；
  • 保存消息记录；
  • 用户离线时保存离线消息；
  • 基于 JPush 原有的大容量稳定的长连接、大容量消息并发能力；

本地会话管理

创建单聊会话

创建单聊会话时，如果本地已存在对应会话，则不会重复创建，将直接返回本地会话对象。通过指定appkey，可以实现给其他appkey下的用户发消息。

  1.     Conversation.createSingleConversation(String username, String appkey)

参数说明

  • String username 会话对象的username.
  • String appkey 用户所属应用的appkey,如果填空则默认为本应用的appkey

创建群聊会话

创建群聊会话，如果本地已存在对应会话对象，则不会重新创建，直接返回本地会话对象。

  1.     Conversation.createGroupConversation(long groupID)

参数说明

  • long groupID 会话对象群组的groupID

获取会话列表

从本地数据库中获取会话列表，默认按照会话的最后一条消息的时间，降序排列

  1. JMessageClient.getConversationList();

参数说明

  • 无
    返回

  • List<Conversation> 会话列表。

获取单个单聊会话

获取与指定appkey下username的单聊会话信息,如果appkey为空则默认取本应用appkey下对应username用户的会话。

  1. JMessageClient.getSingleConversation(String username, String appkey);

参数说明

  • String username 目标的用户用户名。

  • String appkey 用户所属应用的appkey
    返回

  • Conversation 根据参数匹配得到的单聊会话对象。

获取单个群聊会话

  1. JMessageClient.getGroupConversation(long groupID);

参数说明

  • long groupID 目标的群的群ID。
    返回

  • Conversation 根据参数匹配得到的群聊会话对象。

删除单个单聊会话

删除与指定appkey下username的单聊的会话，同时删除掉本地聊天记录。,如果appkey为空则默认尝试删除本应用appkey下对应username的会话。

  1. JMessageClient.deleteSingleConversation(String username, String appkey);

参数说明

  • String username 目标的用户用户名。

  • String appkey 用户所属应用的appkey
    返回

  • boolean 是否删除成功。

删除单个群聊会话

  1. JMessageClient.deleteGroupConversation(long groupID);

参数说明

  • long groupID 目标群的群ID。
    返回

  • boolean 是否删除成功。

获取单个会话未读消息数

  1. conversation.getUnReadMsgCnt();

返回

  • int 当前会话的未读消息数

重置单个会话未读消息数

  1. conversation.resetUnreadCount();

返回

  • boolean true表示重置成功，其他情况下返回false.

手动设置会话未读消息数

  1. conversation.setUnReadMessageCnt(int count);

参数说明

  • int count 指定的未读消息数
    返回

  • boolean true表示设置成功，其他情况下返回false.

获取所有会话未读消息总数

  1. JMessageClient.getAllUnReadMsgCount();

返回

  • int 当前用户所有会话的未读消息总数

创建消息

创建文字消息

  1.     /**
  2.      * 创建一条单聊文本消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param username 聊天对象用户名
  7.      * @param appKey   聊天对象所属应用的appKey
  8.      * @param text     文本内容
  9.      * @return 消息对象
  10.      */
  11.     JMessageClient.createSingleTextMessage(String username, String appKey, String text)
  13.     /**
  14.      * 创建一条群聊文本信息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  15.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  16.      * 接口来创建消息
  17.      *
  18.      * @param groupID 群组的groupID
  19.      * @param text    文本内容
  20.      * @return 消息对象
  21.      */
  22.     JMessageClient.createGroupTextMessage(long groupID, String text)

创建图片消息

  1.     /**
  2.      * 创建一条单聊图片信息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param username  聊天对象的用户名
  7.      * @param appKey    聊天对象所属应用的appKey
  8.      * @param imageFile 图片文件
  9.      * @return 消息对象
  10.      * @throws FileNotFoundException
  11.      */
  12.     JMessageClient.createSingleImageMessage(String username, String appKey, File imageFile) throws FileNotFoundException
  14.     /**
  15.      * 创建一条群聊图片信息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  16.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  17.      * 接口来创建消息
  18.      *
  19.      * @param groupID   群组的groupID
  20.      * @param imageFile 图片文件
  21.      * @return 消息对象
  22.      * @throws FileNotFoundException
  23.      */
  24.     JMessageClient.createGroupImageMessage(long groupID, File imageFile) throws FileNotFoundException

创建语音消息

  1.     /**
  2.      * 创建一条单聊语音信息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param username  聊天对象的用户名
  7.      * @param appKey    聊天对象所属应用的appKey
  8.      * @param voiceFile 语音文件
  9.      * @param duration  语音文件时长
  10.      * @return 消息对象
  11.      * @throws FileNotFoundException
  12.      */
  13.     JMessageClient.createSingleVoiceMessage(String username, String appKey, File voiceFile, int duration) throws FileNotFoundException
  15.     /**
  16.      * 创建一条群聊语音信息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  17.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  18.      * 接口来创建消息
  19.      *
  20.      * @param groupID   群组groupID
  21.      * @param voiceFile 语音文件
  22.      * @param duration  语音文件时长
  23.      * @return 消息对象
  24.      * @throws FileNotFoundException
  25.      */
  26.     JMessageClient.createGroupVoiceMessage(long groupID, File voiceFile, int duration) throws FileNotFoundException

创建位置消息

  1.     /**
  2.      * 创建一条单聊地理位置消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param username  聊天对象的用户名
  7.      * @param appKey    聊天对象所属应用的appKey
  8.      * @param latitude  纬度信息
  9.      * @param longitude 经度信息
  10.      * @param scale     地图缩放比例
  11.      * @param address   详细地址信息
  12.      * @return 消息对象
  13.      */
  14.     JMessageClient.createSingleLocationMessage(String username, String appKey, double latitude, double longitude, int scale, String address)
  16.     /**
  17.      * 创建一条群聊地理位置消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  18.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  19.      * 接口来创建消息
  20.      *
  21.      * @param groupId   群组groupID
  22.      * @param latitude  纬度信息
  23.      * @param longitude 经度信息
  24.      * @param scale     地图缩放比例
  25.      * @param address   详细地址信息
  26.      * @return 消息对象
  27.      */
  28.     JMessageClient.createGroupLocationMessage(long groupId, double latitude, double longitude, int scale, String address)

创建文件消息

  1.     /**
  2.      * 创建一条单聊file消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param userName 聊天对象的用户名
  7.      * @param appKey   聊天对象所属应用的appKey
  8.      * @param file     发送的文件
  9.      * @param fileName 指定发送的文件名称,如果不填或为空，则默认使用文件原名。
  10.      * @return 消息对象
  11.      * @throws FileNotFoundException
  12.      */
  13.     JMessageClient.createSingleFileMessage(String userName, String appKey, File file, String fileName) throws FileNotFoundException, JMFileSizeExceedException
  15.     /**
  16.      * 创建一条群聊file消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  17.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  18.      * 接口来创建消息
  19.      *
  20.      * @param groupID  群组groupID
  21.      * @param file     发送的文件
  22.      * @param fileName 指定发送的文件名称,如果不填或为空，则默认使用文件原名。
  23.      * @return 消息对象
  24.      * @throws FileNotFoundException
  25.      */
  26.     JMessageClient.createGroupFileMessage(long groupID, File file, String fileName) throws FileNotFoundException, JMFileSizeExceedException

创建自定义消息

  1.     /**
  2.      * 创建一条单聊自定义消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param username  聊天对象username
  7.      * @param appKey    聊天对象所属应用的appKey
  8.      * @param valuesMap 包含自定义键值对的map.
  9.      * @return 消息对象
  10.      */
  11.     JMessageClient.createSingleCustomMessage(String username, String appKey, Map<? extends String, ? extends String> valuesMap)
  13.    /**
  14.     * 创建一条群聊自定义消息
  15.     *
  16.     * @param groupID   群组groupID
  17.     * @param valuesMap 包含了自定义键值对的map
  18.     * @return  消息对象
  19.     */
  20.     JMessageClient.createGroupCustomMessage(long groupID,
  21.     Map<? extends String, ?> valuesMap)

创建视频消息

  1.     /**
  2.      * 创建一条单聊video消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  3.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  4.      * 接口来创建消息
  5.      *
  6.      * @param userName      聊天对象用户名
  7.      * @param appKey        聊天对象所属应用appkey
  8.      * @param thumbImage    视频缩略图，可不填。
  9.      * @param thumbFormat   视频缩略图格式名
  10.      * @param videoFile     视频文件对象
  11.      * @param videoFileName 视频文件名称，如果不填或为空，则默认使用文件原名
  12.      * @param duration      视频时长
  13.      * @return 消息对象
  14.      * @throws IOException
  15.      * @since 2.6.0
  16.      */
  17.     JMessageClient.createSingleVideoMessage(String userName, String appKey, Bitmap thumbImage, String thumbFormat, File videoFile, String videoFileName, int duration) throws IOException
  19.     /**
  20.      * 创建一条群聊video消息，此方法是创建message的快捷接口，对于不需要关注会话实例的开发者可以使用此方法
  21.      * 快捷的创建一条消息。其他的情况下推荐使用{@link Conversation#createSendMessage(MessageContent)}
  22.      * 接口来创建消息
  23.      *
  24.      * @param groupID       群组groupID
  25.      * @param thumbImage    视频缩略图，可不填。
  26.      * @param thumbFormat   视频缩略图格式名
  27.      * @param videoFile     视频文件对象
  28.      * @param videoFileName 视频文件名称，如果不填或为空，则默认使用文件原名
  29.      * @param duration      视频时长
  30.      * @return 消息对象
  31.      * @throws IOException
  32.      * @since 2.6.0
  33.      */
  34.     JMessageClient.createGroupVideoMessage(long groupID, Bitmap thumbImage, String thumbFormat, File videoFile, String videoFileName, int duration) throws IOException

消息发送结果监听

消息发送完成后，会回调这里的接口通知上层。

  1. message.setOnSendCompleteCallback(BasicCallback sendCompleteCallback)

参数说明

  • BasicCallback sendCompleteCallback 回调接口

发送消息

向服务器给发送对象发送消息，并且保存到本地会话。使用默认的配置参数发送

  1. /**
  2.  * 发送消息，使用默认发送配置参数.<br/>
  3.  * 注意只有创建的消息和发送失败的消息可以被发送{@link MessageStatus}，<br/>
  4.  * 发送成功或收到的消息再次发送需调用转发接口{@link JMessageClient#forwardMessage(Message, Conversation, MessageSendingOptions, RequestCallback)}.
  5.  *
  6.  * @param message 消息对象
  7.  */
  8. JMessageClient.sendMessage(Message message);

参数说明

  • Message message 消息对象

附带控制参数的消息发送

Since 2.2.0针对此次消息发送操作，支持一些可选参数的配置，具体参数见MessageSendingOptions

  1. JMessageClient.sendMessage(Message message, MessageSendingOptions options);

参数说明

  • Message message 消息对象
  • MessageSendingOptions options 消息发送时的控制选项。

代码示例

  1. Message message = mConversation.createSendMessage(new TextContent(“Hello jmessage.”));
  2. message.setOnSendCompleteCallback(new BasicCallback() {
  3.     @Override
  4.     public void gotResult(int responseCode, String responseDesc) {
  5.         if (responseCode == 0) {
  6.             //消息发送成功
  7.         } else {
  8.             //消息发送失败
  9.         }
  10.     }
  11. });
  13. MessageSendingOptions options = new MessageSendingOptions();
  14. options.setRetainOffline(false);
  16. JMessageClient.sendMessage(message);//使用默认控制参数发送消息
  17. //JMessageClient.sendMessage(message,options);//使用自定义的控制参数发送消息

消息发送取消

Since 2.8.2

发送消息过程中如果想取消消息的发送，可调用本接口

  1.     /**
  2.      * 取消消息的发送，如果消息需要上传附件(图片、语音、文件等)，上传会中断，消息状态变为{@link MessageStatus#send_cancelled}。
  3.      * <p>
  4.      * 注意取消操作不一定会成功，通过设置的消息发送回调{@link #setOnSendCompleteCallback(BasicCallback)}来获取消息发送最终结果，
  5.      * 如果消息发送被取消的话回调中错误码为{@link cn.jpush.im.android.ErrorCode.LOCAL_ERROR#LOCAL_OPERATION_CANCELLED}代表消息发送取消。
  6.      * @since 2.8.2
  7.      */
  8.     message.cancelSend();

代码示例

  1. message.setOnSendCompleteCallback(new BasicCallback() {
  2.     @Override
  3.     public void gotResult(int responseCode, String responseMessage) {
  4.         assertEquals(ErrorCode.LOCAL_ERROR.LOCAL_OPERATION_CANCELLED, responseCode);
  5.         assertEquals(MessageStatus.send_cancelled, message.getStatus());
  6.         latch.countDown();
  7.     }
  8. });
  9. JMessageClient.sendMessage(message);
  10. // 调用发送后状态会变成send_going
  11. try {
  12.     TimeUnit.MILLISECONDS.sleep(cancelTimeInMill);
  13. } catch (InterruptedException e) {
  14.     e.printStackTrace();
  15. }
  16. message.cancelSend();

接收消息

sdk收到消息时，会上抛消息事件MessageEvent 或 OfflineMessageEvent，开发者可以通过这个事件来拿到具体的Message对象，进而执行UI刷新或者其他相关逻辑。具体事件处理方法见事件处理一节

从2.1.0版本开始接收消息的变化

2.1.0版本开始，sdk将消息下发分为在线下发和离线下发两种类型。 先明确两个概念：

  • 在线消息：im用户在线期间，所有收到的消息称为在线消息。
  • 离线消息：im用户离线期间（包括登出或者网络断开）所产生的消息，会暂存在极光服务器上。当用户再次上线，sdk会将这部分消息拉取下来，这部分消息就称为离线消息。
    有了这两个概念的区分之后，sdk对于这两种消息的处理方式也有了不同：
版本在线消息离线消息
2.1.0之前每收到一条消息上抛一个MessageEvent和在线消息一样，有多少条离线消息就上抛多少个MessageEvent
2.1.0开始每收到一条消息上抛一个MessageEvent以会话为单位，该会话如果有离线消息，sdk就会上抛一个OfflineMessageEvent。就算同会话中有多条离线消息，sdk也只会上抛一个OfflineMessageEvent,这个Event中就包含了所有离线消息的相关信息。这样会大大减轻上层处理事件的压力。

总结

sdk升级到2.1.0版本（或以上）后，上层需要针对消息接收的处理做以下变动：

  • 除了MessageEvent之外，新增一个事件类型OfflineMessageEvent的接收,用来接收离线消息事件。
  • 对于需要消息漫游的开发者，还需增加ConversationRefreshEvent事件的接收，当会话中的漫游消息同步完成后，sdk会触发此事件通知上层刷新会话。
    代码示例：
  1.     /**
  2.     *  接收在线消息
  3.     **/
  4.     public void onEvent(MessageEvent event) {
  5.         //获取事件发生的会话对象
  6.         Conversation conversation = event.getConversation();
  7.         Message newMessage = event.getMessage();//获取此次离线期间会话收到的新消息列表
  8.         System.out.println(String.format(Locale.SIMPLIFIED_CHINESE, "收到一条来自%s的在线消息。\n", conversation.getTargetId()));
  9.     }
  12.     /**
  13.     * 接收离线消息。
  14.     * 类似MessageEvent事件的接收，上层在需要的地方增加OfflineMessageEvent事件的接收
  15.     * 即可实现离线消息的接收。
  16.     **/
  17.     public void onEvent(OfflineMessageEvent event) {
  18.         //获取事件发生的会话对象
  19.         Conversation conversation = event.getConversation();
  20.         List<Message> newMessageList = event.getOfflineMessageList();//获取此次离线期间会话收到的新消息列表
  21.         System.out.println(String.format(Locale.SIMPLIFIED_CHINESE, "收到%d条来自%s的离线消息。\n", newMessageList.size(), conversation.getTargetId()));
  22.     }
  25.     /**
  26.     * 接收消息漫游事件
  27.     * 如果在JMessageClient.init时启用了消息漫游功能，则每当一个会话的漫游消息同步完成时
  28.     * sdk会发送此事件通知上层。
  29.     **/
  30.     public void onEvent(ConversationRefreshEvent event) {
  31.         //获取事件发生的会话对象
  32.         Conversation conversation = event.getConversation();
  33.         //获取事件发生的原因，对于漫游完成触发的事件，此处的reason应该是
  34.         //MSG_ROAMING_COMPLETE
  35.         ConversationRefreshEvent.Reason reason = event.getReason();
  36.         System.out.println(String.format(Locale.SIMPLIFIED_CHINESE, "收到ConversationRefreshEvent事件,待刷新的会话是%s.\n", conversation.getTargetId()));
  37.         System.out.println("事件发生的原因 : " + reason);
  38.     }

消息附件下载取消

Since 2.8.2 下载消息附件(例如文件)时，想取消下载调用本接口

  1.     /**
  2.      * 取消下载,手动下载后可调用此接口取消下载, 注意可以自动下载的文件不可取消
  3.      * <br/>
  4.      * 是否取消成功需要根据下载的回调来判断,如果取消成功，下载回调中错误码为{@link ErrorCode.LOCAL_ERROR#LOCAL_OPERATION_CANCELLED}
  5.      * @param message 该Content所对应的消息对象
  6.      * @since 2.8.2
  7.      */
  8.     messageContent.cancelDownload(Message message);

代码示例

  1. mDownload.setOnClickListener(new View.OnClickListener() {
  2.     @Override
  3.     public void onClick(View v) {
  4.         mTv_showText.setText("");
  5.         final ProgressDialog dialog = new ProgressDialog(ShowMessageActivity.this);
  6.         dialog.setTitle("提示");
  7.         dialog.setMessage("正在下载中...");
  8.         dialog.setButton(ProgressDialog.BUTTON_NEGATIVE, "取消下载", new DialogInterface.OnClickListener() {
  9.             @Override
  10.             public void onClick(DialogInterface dialog, int which) {
  11.                 cancelDownload();
  12.                 dialog.dismiss();
  13.             }
  14.         });
  15.         dialog.setCanceledOnTouchOutside(true);
  16.         dialog.show();
  18.         if (message != null) {
  19.             FileContent content = (FileContent) message.getContent();
  20.             message.setOnContentDownloadProgressCallback(new ProgressUpdateCallback() {
  21.                 @Override
  22.                 public void onProgressUpdate(double percent) {
  23.                     mTv_showText.append("文件下载中，进度:" + percent + "\n");
  24.                 }
  25.             });
  26.         } else {
  27.             Toast.makeText(ShowMessageActivity.this, "未能获取到message对象", Toast.LENGTH_SHORT).show();
  28.         }
  29.     }
  30. });
  32. private void cancelDownload() {
  33.     if (message != null) {
  34.         message.getContent().cancelDownload(message);
  35.     }
  36. }

撤回消息

撤回会话中某条消息

Since 2.2.0由消息发送方发起调用

  1.     conversation.retractMessage(Message message, BasicCallback callback)

参数说明

  • Message message 需要被撤回的消息的消息实体
  • BasicCallback callback 回调接口

被撤回方事件通知

Since 2.2.0消息发送方发起撤回后，被撤回方会收到一条事件通知MessageRetractEvent，具体事件处理方式见事件处理一节

注意： 无论是撤回方还是被撤回方，消息被撤回后，对应message content会被替换为PromtContent类型，消息之前内容变成不可见。

转发消息

转发会话中的某条消息

  1.     /**
  2.      * 转发消息,只有发送成功或收到的消息才可转发
  3.      *
  4.      * @param message  需要转发的消息对象
  5.      * @param conv     目标会话
  6.      * @param options  消息转发时的控制选项，仅对此次发送生效, null则使用默认配置
  7.      * @param callback 回调函数
  8.      * @since 2.3.0
  9.      * @deprecated deprecated since jmessage 2.6.0 use {@link JMessageClient#forwardMessage(Message, Conversation, MessageSendingOptions, RequestCallback)} instead.
  10.      */
  11.     JMessageClient.forwardMessage(Message message, Conversation conv, MessageSendingOptions options, BasicCallback callback);
  13.     /**
  14.      * 转发消息,注意支持转发的消息{@link Message#isSupportForward()}才可转发,符合转发要求后会创建新的消息发送，
  15.      * 创建的消息会在回调中返回（无论发送是否成功），如果不符合转发要求则不会创建新消息 message返回null。<br/>
  16.      *
  17.      * @param message  需要转发的消息对象
  18.      * @param conv     目标会话
  19.      * @param options  消息转发时的控制选项，仅对此次发送生效, null则使用默认配置
  20.      * @param callback 回调函数
  21.      * @since 2.6.0
  22.      */
  23.     JMessageClient.forwardMessage(Message message, Conversation conv, MessageSendingOptions options, final RequestCallback<Message> callback);

消息已读回执

已读回执设置

消息发送方可以在发送消息时，针对单条消息设置是否需要接收方发送已读回执。默认行为为falseSince 2.3.0

  1.     messageSendingOptions.setNeedReadReceipt(boolean needReadReceipt)

参数说明

  • boolean needReadReceipt 是否需要接收方发送已读回执. true - 是,false - 否.

获取当前未发送已读回执的人数

当一条需要接收方发送已读回执的消息成功发出之后，消息发送方可以查看这条消息当前尚未发送已读回执的人数.Since 2.3.0

  1.     message.getUnreceiptCnt()

接口返回

  • int 当前尚未发送已读回执的人数.当所有接收者均已读，或者这条消息不是一条需要已读回执的消息时,返回0

获取当前已读回执详情

当一条需要接收方发送已读回执的消息成功发出之后，消息发送方可以查看这条消息当前已读回执的详情.详情中包含当前已发送已读回执和未发送已读回执的用户UserInfo列表等信息Since 2.3.0

  1.     message.getReceiptDetails(GetReceiptDetailsCallback callback)

参数说明

  • GetReceiptDetailsCallback callback 结果回调

消息接收方将消息标记为已读

对于消息接收方，可以将一条消息标记为已读，标记成功后，这条消息的已读状态会记录在本地。当这条消息是一条需要已读回执的消息时，sdk还将主动发送一个通知事件MessageReceiptStatusChangeEvent给消息发送方，通知对方这条消息的已读回执人数发生变化。注意这个已读状态只会保存在本地，当本地数据被清除，或者用户更换设备登陆之后，已读状态会被重置为false。Since 2.3.0

  1.     message.setHaveRead(BasicCallback callback)

参数说明

  • BasicCallback callback 结果回调

获取消息是否是已读状态

对于消息接收方，可以通过此接口获取到这条消息是否是已读的状态。默认所有收到的消息已读状态都为false。在成功调用message.setHaveRead(BasicCallback callback)接口后，消息的已读状态变成true注意这个已读状态只会保存在本地，当本地数据被清除，或者用户更换设备登陆之后，已读状态会被重置为false。Since 2.3.0

  1.     message.haveRead()

接口返回

  • boolean 消息的已读状态. true - 已读,false - 未读

消息回执状态变更事件

  1. MessageReceiptStatusChangeEvent

对于消息发送方发送的需要接收方发送已读回执的消息，接收方通过message.setHaveRead(BasicCallback callback)接口成功发送已读回执后，sdk会上抛这个事件通知消息发送方。发送方通过这个事件可以知道是哪个会话中的哪条消息的未回执人数发生了变化。具体处理方法见事件处理一节

回执相关代码示例：

  1. //消息发送方：
  2. //===========发送带已读回执的消息：
  3. final Message message = mConversation.createSendMessage(new TextContent(“这是一条需要对方发送已读回执的消息.”));
  4. message.setOnSendCompleteCallback(new BasicCallback() {
  5.     @Override
  6.     public void gotResult(int responseCode, String responseDesc) {
  7.         if (responseCode == 0) {
  8.             //消息发送成功
  9.             message.getUnreceiptCnt();//带回执的消息发送成功后，可以查看当前尚未发送已读回执的人数
  10.             message.getReceiptDetails(...);//获取当前已读回执详情,具体包括已读和未读用户的UserInfo列表。callback中代码略
  11.         } else {
  12.             //消息发送失败
  13.         }
  14.     }
  15. });
  16. MessageSendingOptions options = new MessageSendingOptions();
  17. options.setNeedReadReceipt(true);//针对这条消息打开已读回执功能
  18. JMessageClient.sendMessage(message,options);//使用自定义的控制参数发送消息
  19. //===========
  21. //===========消息发送方监听回执状态变化：
  22. public void onEventMainThread(MessageReceiptStatusChangeEvent event) {
  23.         Conversation conv = event.getConversation();
  24.         tv_refreshEvent.append(String.format(Locale.SIMPLIFIED_CHINESE, "\n收到MessageReceiptStatusChangeEvent事件,会话对象是%s\n", conv.getTargetId()));
  25.         for (MessageReceiptStatusChangeEvent.MessageReceiptMeta meta : event.getMessageReceiptMetas()) {
  26.             tv_refreshEvent.append(String.format(Locale.SIMPLIFIED_CHINESE,
  27.                     "回执数有更新的消息serverMsgID：%d\n当前未发送已读回执的人数：%d", meta.getServerMsgId(), meta.getUnReceiptCnt()));
  28.         }
  29. }
  30. //===========
  33. //消息接收方
  34. //===========将消息标记为已读
  35. if(!message.haveRead()){ //当消息的haveRead状态为false时，调用setHaveRead,将消息标记为已读
  36.     msg.setHaveRead(new BasicCallback() {
  37.         @Override
  38.         public void gotResult(int responseCode, String responseMessage) {
  39.             Toast.makeText(MessageReceiptActivity.this, "成功将消息标记为已读. responseCode = " + responseCode + " responseMessage =" + responseMessage, Toast.LENGTH_SHORT).show();
  40.         }
  41.     });
  42. }
  43. //===========

本地消息记录获取

任何的消息都从属某一会话，所以要获取本地消息记录，首先需要获取到会话对象conversation,进而获取该会话下的消息记录。

获取会话中所有消息

  1.     /**
  2.      * 获取会话中所有消息，消息按照时间升序排列.<br/>
  3.      *
  4.      * @return 包含会话中所有消息的List
  5.      */
  6.     conversation.getAllMessage();

按条件获取消息列表

  1.     /**
  2.      * 会话中消息按时间降序排列，从其中的offset位置，获取limit条数的消息.
  3.      *
  4.      * @param offset 获取消息的起始位置
  5.      * @param limit  获取消息的条数
  6.      * @return 符合查询条件的消息List, 如果查询失败则返回空的List。
  7.      */
  8.     conversation.getMessagesFromNewest(int offset, int limit)
  10.     /**
  11.      * 会话中消息按时间升序排列，从其中的offset位置，获取limit条数的消息.<br/>
  12.      *
  13.      * @param offset 获取消息的起始位置
  14.      * @param limit  获取消息的条数
  15.      * @return 符合查询条件的消息List, 如果查询失败则返回空的List。
  16.      */
  17.     conversation.getMessagesFromOldest(int offset, int limit);

命令透传

Since 2.3.0命令透传发送的命令后台不会为其离线保存，只会在对方用户在线的前提下将命令推送给对方。sdk收到命令之后也不会本地保存，不发送通知栏通知，整体快速响应。开发者可以通过命令透传拓展一些在线场景下的辅助功能，如：实现输入状态提示等。

发送命令透传

  1.     /**
  2.      * 发送消息透传给个人。
  3.      * 消息不会进入到后台的离线存储中去，仅当对方用户当前在线时，透传消息才会成功送达。
  4.      * 透传命令送达时，接收方会收到一个{@link CommandNotificationEvent}事件通知。
  5.      * sdk不会将此类透传消息内容本地化。
  6.      *
  7.      * @param username 目标的用户名
  8.      * @param appKey   目标的appKey, 如果传入null或空字符串，则默认用本应用的appKey
  9.      * @param msg      发送的消息内容
  10.      * @param callback 回调函数
  11.      * @since 2.3.0
  12.      */
  13.     JMessageClient.sendSingleTransCommand(String username, appkey, String cmd,  BasicCallback callback)
  15.     /**
  16.      * 发送消息透传给群。
  17.      * 消息不会进入到后台的离线存储中去，仅当对方用户当前在线时，透传消息才会成功送达。
  18.      * 透传命令送达时，接收方会收到一个{@link CommandNotificationEvent}事件通知。
  19.      * sdk不会将此类透传消息内容本地化。
  20.      *
  21.      * @param gid      群组的gid
  22.      * @param msg      发送的消息内容
  23.      * @param callback 回调函数
  24.      * @since 2.3.0
  25.      */
  26.     JMessageClient.sendGroupTransCommand(long gid, String msg, BasicCallback callback)
  28.     /**
  29.      * 发送透传消息给当前用户在其他平台已登录的设备。
  30.      * 消息不会进入到后台的离线存储中去，仅当对方用户当前在线时，透传消息才会成功送达。
  31.      * 透传命令送达时，接收方会收到一个{@link CommandNotificationEvent}事件通知。
  32.      * sdk不会将此类透传消息内容本地化。
  33.      *
  34.      * @param platformType 平台类型，其中{@link PlatformType#all}表示发送给当前多端在线的其他所有设备（不包括本设备）。
  35.      * @param msg          发送的消息内容
  36.      * @param callback     回调函数
  37.      * @since 2.5.0
  38.      */
  39.     JMessageClient.sendCrossDeviceTransCommand(PlatformType platformType, String msg, BasicCallback callback)