接收消息

大约 17 分钟

接收消息

功能说明

环信即时通讯 IM Android SDK 通过 EMMessageListener 接收文本、图片、语音、视频、文件、位置、透传、自定义和合并等类型的消息。应用在消息监听回调中识别消息类型，读取对应消息体并根据业务需要展示或处理消息。自 SDK 5.2.1 起，还支持通过完整消息体列表接收和展示复合消息。

前提条件

开始前，请确保满足以下条件：

完成 SDK 初始化，详见初始化文档。
了解环信即时通讯 IM 的使用限制，详见使用限制。

监听消息事件

应用通过 EMChatManager#addMessageListener 注册 EMMessageListener。收到普通消息时触发 onMessageReceived；收到透传消息时，还会触发 onCmdMessageReceived。

EMMessageListener messageListener = new EMMessageListener() {
    @Override
    public void onMessageReceived(List<EMMessage> messages) {
        // 处理文本、附件、位置、自定义及合并消息。
    }

    @Override
    public void onCmdMessageReceived(List<EMMessage> messages) {
        // 处理透传消息。
    }
};

EMClient.getInstance().chatManager().addMessageListener(messageListener);
// 不再使用时移除监听器。
EMClient.getInstance().chatManager().removeMessageListener(messageListener);

消息通用信息

收到消息后，可通过以下 EMMessage 方法读取消息的通用信息：

字段或属性	获取方式	说明
消息 ID	`EMMessage#getMsgId`	消息的唯一 ID。
发送方	`EMMessage#getFrom`	消息发送者的用户 ID。
接收方	`EMMessage#getTo`	消息目标 ID。
会话类型	`EMMessage#getChatType`	单聊、群聊或聊天室。
消息类型	`EMMessage#getType` / `getContentType`	单消息体消息返回其具体类型；复合消息返回 `EMMessage.Type.MULTIBODY`。
首个消息体	`EMMessage#getBody`	返回第一个消息体。复合消息中仅使用此方法会遗漏后续消息体。
完整消息体列表	`EMMessage#getBodies`	返回有序、结构只读的消息体列表，适用于单消息体和复合消息。
扩展字段	`EMMessage#getStringAttribute` 等	读取发送方通过 `setAttribute` 设置的业务字段。

接收文本消息

收到 onMessageReceived 回调后，遍历消息列表。对于文本消息，将消息体转换为 EMTextMessageBody，调用 getMessage() 获取文本内容；如需读取业务扩展字段，可调用 EMMessage#getExt() 获取扩展字段映射。

示例代码如下所示：

EMMessageListener messageListener = new EMMessageListener() {
    @Override
    public void onMessageReceived(List<EMMessage> messages) {
        for (EMMessage message : messages) {
            if (message.getType() != EMMessage.Type.TXT) {
                continue;
            }

            // 获取文本消息内容。
            EMTextMessageBody textBody =
                    (EMTextMessageBody) message.getBody();
            String text = textBody.getMessage();

            // 按业务字段名读取消息扩展字段。
            // 字段不存在时返回默认值 null。
            String businessValue = message.getStringAttribute(
                    "businessKey",
                    null);

            EMLog.d(
                    "Message",
                    "text: " + text
                            + ", businessValue: " + businessValue);
        }
    }

    // 其他回调方法按需实现。
};

EMClient.getInstance()
        .chatManager()
        .addMessageListener(messageListener);

接收附件消息

除文本消息外，SDK 还支持接收附件类型消息，包括语音、图片、视频和文件消息。

附件消息的接收过程如下：

接收附件消息。SDK 自动下载语音消息，默认自动下载图片和视频的缩略图。若下载原图、大图、视频和文件，需调用对应下载接口。
获取附件的服务器地址和本地路径。

附件下载接口与回调

根据所需资源调用以下 EMChatManager 下载接口，并通过 EMCallBack 获取下载进度和结果。

接口	主要用途	进度回调
`downloadAttachment(message, callback)`	下载原始附件，如原图、语音、视频或文件。	通过 `onProgress` 返回 0–100 的下载进度。
`downloadBigImage(message, callback)`	下载图片大图。	通过 `onProgress` 返回 0–100 的下载进度。
`downloadThumbnail(message, callback)`	下载图片或视频缩略图。	不触发 `onProgress`。

每次下载请求通过 onSuccess() 或 onError(int code, String error) 返回一次最终结果。下载成功后，从消息体读取对应资源的本地路径和下载状态，更新展示。

自 SDK 5.2.1 起，上述接口也支持传入整条复合消息，无需逐个消息体调用。消息体筛选、消息级进度及整体下载结果的规则请参见下载复合消息附件。

接收语音消息

接收方收到语音消息时，自动下载语音文件。
接收方收到 onMessageReceived 回调，调用 getRemoteUrl 或 getLocalUri 方法获取语音文件的服务器地址或本地路径，从而获取语音文件。

EMVoiceMessageBody voiceBody = (EMVoiceMessageBody) message.getBody();
// 获取语音文件在服务器的地址。
String voiceRemoteUrl = voiceBody.getRemoteUrl();
// 本地语音文件的资源路径。
Uri voiceLocalUri = voiceBody.getLocalUri();

接收图片消息

一条图片消息通常包含三类图片资源：

原图：发送方本地选择的原始图片文件，通常用于查看或保存原图。
大图：SDK 客户端基于原图进行等比压缩后上传的图片。压缩规则为：若图片短边大于 720 像素，则等比压缩至短边为 720 像素；若短边小于等于 720 像素，则保留原图尺寸，不做放大处理。此类图片通常用于聊天详情页展示。
缩略图：服务端基于原图进行等比压缩后的图片。压缩规则为：默认情况下，若图片短边大于 170 像素，则等比压缩至短边为 170 像素；若短边小于等于 170 像素，则保留原图尺寸，不做放大处理。缩略图的压缩方式和尺寸可在控制台进行配置。此类图片通常用于会话列表、聊天列表等轻量展示场景。

收到图片消息后，SDK 会根据配置自动下载缩略图。若业务需要显示更清晰的图片，可再按需下载大图或原图。

接收图片消息的流程如下：

接收图片消息时，SDK 会根据配置决定是否自动下载缩略图：

默认自动下载，即 EMClient.getInstance().getOptions().setAutoDownloadThumbnail(true)。
如果关闭自动下载，即 EMClient.getInstance().getOptions().setAutoDownloadThumbnail(false)，则需要调用 EMClient.getInstance().chatManager().downloadThumbnail(message, callback) 手动下载。

收到图片消息后，接收方可以在 onMessageReceived 回调中处理图片消息，并根据业务需要下载原图或大图。

调用 downloadAttachment(message, callback) 下载原图。
调用 downloadBigImage(message, callback) 下载大图。

如果本地已存在对应资源路径，建议优先复用本地文件，避免重复下载。

示例代码如下所示：

@Override
public void onMessageReceived(List<EMMessage> messages) {
    for(EMMessage message : messages) {
        if (message.getType() == EMMessage.Type.IMAGE) {
            EMCallBack callback = new EMCallBack() {
               @Override
               public void onSuccess() {
                   // 附件下载成功
               }

               @Override
               public void onError(int code, String error) {
                   // 附件下载失败
               }

               @Override
               public void onProgress(int progress, String status) {
                   // 附件下载进度
               }
           };
           // 下载原图
           EMClient.getInstance().chatManager().downloadAttachment(message, callback);
           // 下载大图
           EMClient.getInstance().chatManager().downloadBigImage(message, callback);
        }
    }
}

你可以通过 EMImageMessageBody 获取原图、大图和缩略图的服务端地址或本地路径：

EMImageMessageBody imgBody = (EMImageMessageBody) message.getBody();
// 从服务端获取原图
String imgRemoteUrl = imgBody.getRemoteUrl();
// 从服务端获取大图
String bigImgRemoteUrl = imgBody.getBigImageRemoteUrl();
// 从服务端获取图片缩略图
String thumbnailUrl = imgBody.getThumbnailUrl();
// 从本地获取原图
Uri imgLocalUri = imgBody.getLocalUri();
// 从本地获取大图
Uri bigImgLocalUri = imgBody.getBigImageLocalUri();
// 从本地获取图片缩略图
Uri thumbnailLocalUri = imgBody.thumbnailLocalUri();

此外，SDK 还支持通过以下方法判断图片资源状态：

isOriginalImage()：判断当前消息对应的是原图还是发送方压缩后的大图资源。
getBigImageDownloadStatus()：获取大图的下载状态。
getWidth() / getHeight()：获取图片宽高。

接收 GIF 图片消息

GIF 图片缩略图的下载与普通图片消息相同，详见接收图片消息。

与普通消息相同，接收 GIF 图片消息时，接收方会收到 onMessageReceived 回调方法。接收方判断为图片消息后，读取消息体的 isGif 属性，若 isGif() 返回 true，则为 GIF 图片消息；返回 false 时为普通图片消息。

public void onMessageReceived(List<EMMessage> messages) {
    for(EMMessage message : messages) {
        if (message.getType() == EMMessage.Type.IMAGE) {
            EMImageMessageBody body = (EMImageMessageBody) message.getBody();
            if(body.isGif()) {
                // 根据业务情况处理gif message, 例如下载展示该消息
            }
        }
    }
    
}

接收视频消息

收到视频消息后，通常会先在聊天界面展示视频缩略图；当用户点击消息时，再下载或播放视频原文件。

接收视频消息的流程如下：

接收方收到视频消息时，SDK 会根据配置决定是否自动下载视频缩略图。
视频缩略图的下载策略与图片缩略图一致。默认情况下，SDK 自动下载缩略图；如果关闭自动下载，则需要在业务侧手动下载。详见设置图片缩略图自动下载。
SDK 会通过 onMessageReceived 回调将视频消息传递给接收方。接收方可根据业务需要选择使用缩略图，或进一步下载视频原文件。
- 如果只需要在会话列表或聊天界面展示预览图，可优先使用缩略图。
- 如果用户需要播放视频，再调用 EMClient.getInstance().chatManager().downloadAttachment(message, callback) 下载视频原文件。
为避免重复下载，建议优先检查本地是否已存在对应的视频文件或缩略图；如果本地已有可用资源，可直接复用。

/**
 * 下载视频文件。
 */
private void downloadVideo(final EMMessage message) {
    EMCallBack callback = new EMCallBack() {
        @Override
        public void onSuccess() {
        }

        @Override
        public void onProgress(final int progress,String status) {
        }

        @Override
        public void onError(final int error, String msg) {
        }
    };
    // 下载附件
    EMClient.getInstance().chatManager().downloadAttachment(message, callback);
}

通过 EMVideoMessageBody 获取视频原文件和缩略图的服务端地址或本地路径。其中，缩略图适合用于预览展示，视频原文件适合用于播放或下载保存。

EMVideoMessageBody videoBody =
        (EMVideoMessageBody) message.getBody();
// 从服务器端获取视频文件。
String videoRemoteUrl = videoBody.getRemoteUrl();
// 从服务器获取视频缩略图文件。
String thumbnailUrl = videoBody.getThumbnailUrl();
// 从本地获取视频文件文件。
Uri localUri = videoBody.getLocalUri();
// 从本地获取视频缩略图文件。
Uri localThumbUri = videoBody.getLocalThumbUri();

接收文件消息

接收文件消息的流程如下所示：

接收方收到 onMessageReceived 回调，调用 downloadAttachment(message, callback) 方法下载文件。

/**
 * 下载文件。
 */
private void downloadFile(final EMMessage message) {
    EMCallBack callback = new EMCallBack() {
        @Override
        public void onSuccess() {
        }

        @Override
        public void onProgress(final int progress,String status) {
        }

        @Override
        public void onError(final int error, String msg) {
        }
    };
    // 下载附件
    EMClient.getInstance().chatManager().downloadAttachment(message, callback);
}

调用以下方法从服务器或本地获取文件附件：

EMNormalFileMessageBody fileMessageBody = (EMNormalFileMessageBody) message.getBody();
// 从服务器获取文件。
String fileRemoteUrl = fileMessageBody.getRemoteUrl();
// 从本地获取文件。
Uri fileLocalUri = fileMessageBody.getLocalUri();

接收位置消息

接收位置消息与文本消息一致，详见接收文本消息。

接收方接收到位置消息时，需要将该位置的经纬度，借由第三方的地图服务，将位置在地图上显示出来。

将消息体转换为 EMLocationMessageBody，通过 getLatitude()、getLongitude() 和 getAddress() 获取位置坐标及地址信息。

EMLocationMessageBody locationBody =
        (EMLocationMessageBody) message.getBody();
double latitude = locationBody.getLatitude();
double longitude = locationBody.getLongitude();
String address = locationBody.getAddress();

接收透传消息

可将透传消息理解为一条指令，通过发送这条指令给对方，通知对方要执行的操作，收到消息可以自定义处理。

具体功能可以根据自身业务需求自定义。另外，以 em_ 和 easemob:: 开头的 action 为内部保留字段，注意不要使用。

提示

透传消息发送后，不支持撤回。
透传消息不会存入本地数据库，也不会创建本地会话，因此通常不在 UI 中显示。

接收方通过 onMessageReceived 和 onCmdMessageReceived 回调接收透传消息，方便用户进行不同的处理。透传消息通常通过 onCmdMessageReceived 接收。

EMMessageListener msgListener = new EMMessageListener(){
  // 收到消息。
  @Override
  public void onMessageReceived(List<EMMessage> messages) {
  }
  // 收到透传消息。
  @Override
  public void onCmdMessageReceived(List<EMMessage> messages) {
  }
}

将消息体转换为 EMCmdMessageBody，通过 action() 获取命令动作。如需传递结构化参数，应在命令内容中定义业务协议，或改用自定义消息。

接收自定义类型消息

你可以自己定义消息类型，方便业务处理，即首先设置一个消息类型名称，然后可添加多种自定义消息。

接收自定义消息与其他类型消息一致，应用在 onMessageReceived 回调中判断消息类型并读取消息体。

将消息体转换为 EMCustomMessageBody，通过 event() 获取自定义事件，通过 getParams() 获取自定义参数。

EMCustomMessageBody customBody =
        (EMCustomMessageBody) message.getBody();
String event = customBody.event();
Map<String, String> params = customBody.getParams();

接收合并消息

接收合并消息与接收普通消息的操作相同，应用在 onMessageReceived 回调中识别 EMMessage.Type.COMBINE 消息。

对于不支持合并消息的 SDK 版本，该类消息会被解析为文本消息，消息内容为 compatibleText 携带的内容，其他字段会被忽略。
合并消息实际上是一种附件消息。收到合并消息后，可以调用 EMChatManager#downloadAndParseCombineMessage 下载并解析合并消息附件，获取原始消息列表：
首次调用该方法时，SDK 会下载并解析合并消息附件，并通过回调返回其中包含的原始消息列表。
后续调用该方法时：
- 若合并消息附件已存在，SDK 会直接解析附件并返回原始消息列表。
- 若合并消息附件不存在，SDK 会先下载附件，再解析并返回原始消息列表。

将消息体转换为 EMCombineMessageBody 后，可以读取合并消息的标题、摘要和兼容文本。

EMClient.getInstance().chatManager().downloadAndParseCombineMessage(combineMessage, new EMValueCallBack<List<EMMessage>>() {
    @Override
    public void onSuccess(List<EMMessage> value) {
        // 处理并展示消息列表
    }

    @Override
    public void onError(int error, String errorMsg) {
        // 处理出错信息
    }
});

接收复合消息

自 SDK 5.2.1 起，复合消息沿用 EMMessageListener#onMessageReceived 接收，无需注册额外监听器。接入消息监听的方式见监听消息事件。

处理时，先通过 getContentType() 或 getType() 判断整条消息是否为 EMMessage.Type.MULTIBODY，再通过 getBodies() 获取完整的有序消息体列表，最后根据每个消息体的实际子类读取内容。整条消息的 MULTIBODY 类型表示它包含多个消息体，不代表列表中的每个消息体都是复合类型。

getBody() 仍可使用，但仅返回首个消息体。原有逻辑若只处理 TXT、IMAGE 等整条消息类型，应增加 MULTIBODY 分支，避免遗漏整条复合消息或后续消息体。

以下示例以“文本＋图片”为例，展示类型判断和按消息体顺序处理内容的方式：

EMMessageListener messageListener = new EMMessageListener() {
    @Override
    public void onMessageReceived(List<EMMessage> messages) {
        for (EMMessage message : messages) {
            if (message.getContentType() != EMMessage.Type.MULTIBODY) {
                // 按原有逻辑处理单消息体消息。
                continue;
            }
            for (EMMessageBody body : message.getBodies()) {
                if (body instanceof EMTextMessageBody) {
                    String text = ((EMTextMessageBody) body).getMessage();
                    // 将文本加入当前消息的展示内容。
                } else if (body instanceof EMImageMessageBody) {
                    EMImageMessageBody imageBody = (EMImageMessageBody) body;
                    // 将图片加入当前位置，按需下载附件后更新展示。
                } else {
                    // 按实际子类处理视频、语音、文件、位置或自定义消息体。
                }
            }
        }
    }
};
EMClient.getInstance().chatManager().addMessageListener(messageListener);

其余消息体的字段读取与展示方式见视频、语音、文件、位置和自定义消息。复用对应示例时，应读取当前遍历到的 body，不要再次调用 message.getBody() 获取首个消息体。

下载复合消息附件

调用下载接口时传入整条 EMMessage，无需逐个消息体发起请求。接口用途与基本回调说明见附件下载接口与回调。

SDK 按以下规则筛选复合消息中的消息体：

消息体类型	原文件下载	大图下载	缩略图下载
图片	原图	大图	图片缩略图
视频	原始视频	跳过	视频缩略图
语音	语音原文件	语音原文件	语音原文件
文件	原文件	跳过	跳过
文本、位置、自定义	跳过	跳过	跳过

不适用的消息体自动跳过，不计为失败，也不参与进度计算。若整条复合消息中没有适用的消息体，则触发 onSuccess()，但不下载任何内容；该规则不表示适用附件缺失或下载失败时也返回成功。

原文件和大图下载通过 onProgress(int progress, String status) 上报按各附件原始文件大小加权的消息级总进度，范围为 0–100，不单独上报每个附件的进度；缩略图下载不触发进度回调。每次请求只返回一次最终结果：所有适用附件下载成功后触发 onSuccess()；任一适用附件下载失败时终止剩余下载，并触发 onError(int code, String error)。

以下示例下载复合消息中的原始附件：

EMCallBack downloadCallback = new EMCallBack() {
    @Override
    public void onSuccess() {
        // 本次请求的所有适用附件下载成功；根据消息体中的本地路径更新展示。
    }

    @Override
    public void onError(int code, String error) {
        // 本次请求失败，后续尚未下载的附件不再继续下载。
    }

    @Override
    public void onProgress(int progress, String status) {
        // 原文件或大图下载的消息级总进度，范围为 0–100。
        // 使用 downloadThumbnail 时不触发此回调。
    }
};
EMClient.getInstance().chatManager().downloadAttachment(message, downloadCallback);

下载完成后，重新遍历 message.getBodies()，读取相应附件消息体的 getLocalUri() 和下载状态，更新原消息中的附件展示。

提示

上述适用性筛选规则仅用于复合消息。单消息体消息保持历史行为：例如，单视频消息调用 downloadBigImage 时下载原始视频文件；不支持的资源或下载类型会通过 onError 返回失败，不会按“无适用消息体”返回成功。仍建议根据实际资源类型选择相应的下载接口。

注意事项

发送端内容准备：发送方应先创建全部消息体，再按阅读顺序组装消息；接收方按 getBodies() 的原始顺序展示。消息体列表的增删或替换应在发送前完成，需要上传的本地附件应在发送完成前保持可读。具体流程见发送复合消息。
附件复用与重发：如需复用已上传附件，应按转发单条消息的说明保留其服务端信息，避免重复上传。重发同一条失败消息时使用原消息对象，见重新发送失败消息。
消息体列表与界面更新：getBodies() 返回的列表结构只读，SDK 可能更新其中消息体的附件路径和下载状态。消息接收回调在 SDK 工作线程执行，更新 Android UI 时应切换到主线程；不要在回调中执行耗时的同步操作。
会话摘要：通过 EMConversation#getLastMessage() 获取最后一条消息后，若其类型为 MULTIBODY，应结合完整消息体列表生成摘要，避免只展示首个消息体。会话读取方式见会话列表。
转发处理：转发复合消息时保留完整的有序消息体列表，不要只复制 getBody()。创建转发消息的方法见转发单条消息。
功能限制：复合消息不支持编辑或翻译，创建和发送规则见发送复合消息。

消息接收回调返回发送成功的消息

若初始化时开启了 EMOptions#setIncludeSendMessageInMessageListener 选项，发送成功的消息也会通过 onMessageReceived 事件返回。

判断消息是否为聊天室广播消息

对于聊天室消息，你可以通过消息的 EMMessage#isBroadcast 属性判断该消息是否为通过 REST API 发送的聊天室全局广播消息。

消息附件下载鉴权

环信即时通讯 IM 支持消息附件下载鉴权功能。该功能默认关闭，如要开通需联系环信商务。该功能开通后，用户必须调用 SDK 的 downloadAttachment(message, callback) 等下载接口下载消息附件。

接口列表

API 名称	所属模块/类	说明
`getContentType`	`EMMessage`	识别复合消息，返回 `MULTIBODY`。
`getBodies`	`EMMessage`	获取完整有序消息体列表。
`downloadThumbnail`	`EMChatManager`	下载适用的缩略图或语音原文件，不提供进度回调。
`downloadBigImage`	`EMChatManager`	下载大图等适用附件，提供消息级进度。
`downloadAttachment`	`EMChatManager`	下载原始附件，提供消息级进度。
`downloadAndParseCombineMessage`	`EMChatManager`	下载并解析合并消息。
`thumbnailLocalUri`	`EMImageMessageBody`	获取图片缩略图本地 URI。

接收消息

# 接收消息

# 功能说明

# 前提条件

# 监听消息事件

# 消息通用信息

# 接收文本消息

# 接收附件消息

# 附件下载接口与回调

# 接收语音消息

# 接收图片消息

# 接收 GIF 图片消息

# 接收视频消息

# 接收文件消息

# 接收位置消息

# 接收透传消息

# 接收自定义类型消息

# 接收合并消息

# 接收复合消息

# 下载复合消息附件

# 注意事项

# 更多

# 消息接收回调返回发送成功的消息

# 判断消息是否为聊天室广播消息

# 消息附件下载鉴权

# 接口列表

接收消息

功能说明

前提条件

监听消息事件

消息通用信息

接收文本消息

接收附件消息

附件下载接口与回调

接收语音消息

接收图片消息

接收 GIF 图片消息

接收视频消息

接收文件消息

接收位置消息

接收透传消息

接收自定义类型消息

接收合并消息

接收复合消息

下载复合消息附件

注意事项

更多

消息接收回调返回发送成功的消息

判断消息是否为聊天室广播消息

消息附件下载鉴权

接口列表