接收消息

大约 20 分钟

接收消息

功能说明

环信即时通讯 IM SDK 支持接收文本、图片、语音、视频、文件及复合消息等类型的消息。

前提条件

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

  • 完成 SDK 初始化，详见 初始化文档。
  • 初始化 SDK 时已注册 ChatManager，能够通过 client.chatManager 调用会话与消息相关接口。
  • 了解环信即时通讯 IM 的使用限制，详见 使用限制。

监听消息事件

接收消息时，请先注册消息事件监听器：

  1. 调用 client.chatManager.addEventHandler() 注册消息事件监听器。
  2. 在 onMessage 中接收普通消息。
  3. 根据 message.type 判断消息类型，并进入对应的业务处理分支。
const CHAT_HANDLER_ID = 'chat-message-listener';

client.chatManager.addEventHandler(CHAT_HANDLER_ID, {
  // 接收各类消息。
  onMessage: message => {
    console.log('收到消息:', message.msgServerId, message.type);
  },
});

消息通用字段

onMessage 回调中返回的是标准化后的 Message 对象。接收消息时，常用字段如下：

字段类型说明
msgServerIdString服务端消息 ID。
msgLocalIdString本地消息 ID。
fromString消息发送方的用户 ID。
toString消息接收方标识。单聊为对端用户 ID，群聊为群组 ID，聊天室为聊天室 ID。
senderSender发送方摘要信息。
conversationIdString所属会话 ID。
conversationType'singleChat' | 'groupChat' | 'chatRoom'会话类型。
typeMessageType消息类型。
bodyMessageBody消息体。复合消息直接为分段数组，其他消息按各自类型读取正文。
extRecord<string, unknown>扩展字段。
timestampNumber消息时间戳，单位为毫秒。
direct'SEND' | 'RECEIVE'消息方向。
isOnlineBoolean是否为在线消息；false 表示离线同步得到的消息。
isBroadcastBoolean是否为聊天室广播消息。
modifiedInfoMessageModifiedInfo消息编辑信息。

接收文本消息

接收流程

收到 onMessage 回调后，可根据消息的 type 判断消息类型。对于文本消息，消息内容位于 message.body.content；如需读取业务扩展字段，可通过 message.ext 获取。

示例代码如下所示：

client.chatManager.addEventHandler('message-listener', {
  onMessage: message => {
    if (message.type === 'text') {
      console.log('文本内容:', message.body.content);
      console.log('扩展字段:', message.ext);
    }
  },
});

关键字段

字段类型必填/可选适用场景说明
contentString必填普通聊天、通知正文、说明文本文本消息核心内容。
translationsRecord<string, string>可选展示译文语言代码到译文的映射，可按当前用户语言读取。

发送方启用自动翻译时，接收消息中可同时包含原文和 body.translations。接收方如需主动翻译，可调用 translateMessage()；详见 文本消息翻译。

接收图片消息

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

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

接收流程

接收图片消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收图片消息。
  3. 若需要下载原图文件，可调用 client.chatManager.downloadAttachment({ message })。
  4. 若需要使用大图或缩略图，可直接使用 bigImageUrl 或 thumbnailUrl 进行展示或由业务侧自行下载。

示例代码如下所示：

client.chatManager.addEventHandler('image-message-listener', {
  // 接收图片消息。
  onMessage: message => {
    // 判断是否为图片消息。
    if (message.type !== 'image') {
      return;
    }

    // 缩略图地址，适合会话列表或聊天列表展示。
    console.log('缩略图地址:', message.body.thumbnailUrl);
    // 大图地址，适合聊天详情页展示。
    console.log('大图地址:', message.body.bigImageUrl);
    // 原图地址，适合查看或保存原图。
    console.log('原图地址:', message.body.originalImageUrl);
    // 图片宽高。
    console.log('图片尺寸:', message.body.width, message.body.height);
    // 是否为 GIF 图片。
    console.log('是否为 GIF:', message.body.isGif);
  },
});

下载原图、大图和缩略图

接收图片消息后，若业务需要进一步获取不同规格的图片资源，可按以下方式处理：

  1. 缩略图通常直接使用 message.body.thumbnailUrl 展示。
  2. 大图通常直接使用 message.body.bigImageUrl 展示。
  3. 原图通常直接使用 message.body.originalImageUrl 展示或保存。
  4. 若需要下载原图二进制数据，可调用 client.chatManager.downloadAttachment({ message })。
client.chatManager.addEventHandler('image-download-listener', {
  // 接收图片消息。
  onMessage: async message => {
    // 判断是否为图片消息。
    if (message.type !== 'image') {
      return;
    }

    // 读取缩略图地址。
    const thumbnailUrl = message.body.thumbnailUrl;
    // 读取大图地址。
    const bigImageUrl = message.body.bigImageUrl;
    // 读取原图地址。
    const originalImageUrl = message.body.originalImageUrl;

    console.log('缩略图地址:', thumbnailUrl);
    console.log('大图地址:', bigImageUrl);
    console.log('原图地址:', originalImageUrl);

    // 下载原图附件。
    const result = await client.chatManager.downloadAttachment({ message });
    const attachment = "data" in result ? result : result[0];
    if (!attachment) return;

    console.log('下载文件名:', attachment.filename);
    console.log('下载地址:', attachment.downloadUrl);
    console.log('原图二进制数据:', attachment.data);
  },
});

关键字段

字段类型必填/可选适用场景说明
thumbnailUrlString可选会话列表、聊天列表缩略图地址。
bigImageUrlString可选聊天详情页预览大图地址。
originalImageUrlString可选查看或保存原图原图地址。
widthNumber可选预排版、预览展示图片宽度。
heightNumber可选预排版、预览展示图片高度。
isGifBoolean必填GIF 动图判断标识当前图片是否为 GIF。
isOriginalImageBoolean必填原图语义判断标识发送方是否按原图语义发送。
secretString可选私有附件下载下载鉴权密钥。
fileLengthNumber可选文件大小展示图片文件大小，单位为字节。

接收 GIF 图片消息

GIF 图片消息本质上仍属于图片消息，接收时仍通过 onMessage 处理。

接收流程

接收 GIF 图片消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收 GIF 图片消息。

示例代码如下所示：

client.chatManager.addEventHandler('gif-message-listener', {
  // 接收 GIF 消息。
  onMessage: message => {
    // 仅处理图片消息。
    if (message.type !== 'image') {
      return;
    }

    // 判断是否为 GIF 图片。
    if (message.body.isGif !== true) {
      return;
    }

    // 读取 GIF 图片资源地址。
    console.log('GIF 缩略图:', message.body.thumbnailUrl);
    console.log('GIF 原图:', message.body.originalImageUrl);
  },
});

关键字段

字段类型必填/可选适用场景说明
isGifBoolean必填GIF 动图判断true 表示当前图片为 GIF。
thumbnailUrlString可选列表预览GIF 缩略图地址。
originalImageUrlString可选原图展示GIF 原图地址。

接收语音消息

接收流程

接收语音消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收语音消息。
  3. 若需要语音文件，可调用 client.chatManager.downloadAttachment({ message }) 下载。

示例代码如下所示：

client.chatManager.addEventHandler('voice-message-listener', {
  // 接收语音消息。
  onMessage: async message => {
    // 判断是否为语音消息。
    if (message.type !== 'voice') {
      return;
    }

    // 读取语音地址。
    console.log('语音地址:', message.body.url);
    // 读取语音时长。
    console.log('语音时长:', message.body.duration);
    // 读取语音文件名。
    console.log('文件名:', message.body.filename);

    // 下载语音附件。
    const result = await client.chatManager.downloadAttachment({ message });
    const attachment = "data" in result ? result : result[0];
    if (!attachment) return;
    console.log('下载地址:', attachment.downloadUrl);
  },
});

关键字段

字段类型必填/可选适用场景说明
urlString可选在线播放、下载语音资源地址。
durationNumber必填语音播放时长展示语音时长，单位为秒。
filenameString可选文件名展示语音文件名。
filetypeString可选类型识别语音文件 MIME 类型。
fileLengthNumber可选文件大小展示语音文件大小，单位为字节。
secretString可选私有附件下载下载鉴权密钥。

接收视频消息

视频消息用于短视频、录屏片段等场景。通常同时包含视频地址和视频缩略图地址。

接收流程

接收视频消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收视频消息。
  3. 若需要视频文件，可调用 client.chatManager.downloadAttachment({ message }) 下载。

示例代码如下所示：

client.chatManager.addEventHandler('video-message-listener', {
  // 接收视频消息。
  onMessage: async message => {
    // 判断是否为视频消息。
    if (message.type !== 'video') {
      return;
    }

    // 读取视频地址。
    console.log('视频地址:', message.body.url);
    // 读取视频缩略图地址。
    console.log('缩略图地址:', message.body.thumbnailUrl);
    // 读取视频时长。
    console.log('视频时长:', message.body.duration);
    // 读取视频尺寸。
    console.log('视频尺寸:', message.body.width, message.body.height);

    // 下载视频附件。
    const result = await client.chatManager.downloadAttachment({ message });
    const attachment = "data" in result ? result : result[0];
    if (!attachment) return;
    console.log('下载地址:', attachment.downloadUrl);
  },
});

关键字段

字段类型必填/可选适用场景说明
urlString可选视频播放、下载视频资源地址。
thumbnailUrlString可选列表预览、封面展示视频缩略图地址。
durationNumber必填时长展示视频时长，单位为秒。
widthNumber可选播放器布局视频宽度。
heightNumber可选播放器布局视频高度。
filenameString可选文件名展示视频文件名。
fileLengthNumber可选文件大小展示视频文件大小，单位为字节。
secretString可选私有附件下载下载鉴权密钥。

接收文件消息

文件消息适用于文档、压缩包、表格等通用文件传输场景。

接收流程

接收文件消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收文件消息。
  3. 若需要文件，可调用 client.chatManager.downloadAttachment({ message }) 下载。

示例代码如下所示：

client.chatManager.addEventHandler('file-message-listener', {
  // 接收文件消息。
  onMessage: async message => {
    // 判断是否为文件消息。
    if (message.type !== 'file') {
      return;
    }

    // 读取文件地址。
    console.log('文件地址:', message.body.url);
    // 读取文件名。
    console.log('文件名:', message.body.filename);
    // 读取文件类型。
    console.log('文件类型:', message.body.filetype);
    // 读取文件大小。
    console.log('文件大小:', message.body.fileSize ?? message.body.fileLength);

    // 下载文件附件。
    const result = await client.chatManager.downloadAttachment({ message });
    const attachment = "data" in result ? result : result[0];
    if (!attachment) return;
    console.log('下载地址:', attachment.downloadUrl);
  },
});

关键字段

字段类型必填/可选适用场景说明
urlString可选下载文件文件资源地址。
filenameString可选文件展示文件名。
filetypeString可选类型识别文件 MIME 类型。
fileSizeNumber可选文件大小展示文件大小。
fileLengthNumber可选服务端兼容字段文件大小，单位为字节。
secretString可选私有附件下载下载鉴权密钥。

接收位置消息

位置消息用于接收地理位置信息，通常包含经纬度和位置描述。

接收流程

接收位置消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收位置消息。可以结合第三方地图服务或定位展示组件渲染位置。

示例代码如下所示：

client.chatManager.addEventHandler('location-message-listener', {
  // 接收位置消息。
  onMessage: message => {
    // 判断是否为位置消息。
    if (message.type !== 'location') {
      return;
    }

    // 读取经纬度。
    console.log('纬度:', message.body.latitude);
    console.log('经度:', message.body.longitude);
    // 读取地址描述。
    console.log('地址描述:', message.body.address);
    // 读取建筑名称。
    console.log('建筑名称:', message.body.buildingName);
  },
});

关键字段

字段类型必填/可选适用场景说明
latitudeNumber必填地图定位纬度。
longitudeNumber必填地图定位经度。
addressString可选地址展示位置描述。
buildingNameString可选地点名称展示建筑名称。

接收透传消息

透传消息用于通知接收方执行某种业务动作，通常不直接作为普通聊天内容展示。

action 为透传消息的动作名称，不能为空。建议使用业务自定义且语义明确的字符串；为避免与 SDK 或服务端内部动作名称冲突，不建议使用 em_、easemob:: 等可能具有内部含义的前缀。

接收流程

接收透传消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收透传消息。

示例代码如下所示：

client.chatManager.addEventHandler('cmd-message-listener', {
  // 接收透传消息。
  onMessage: message => {
    // 判断是否为透传消息。
    if (message.type !== 'cmd') {
      return;
    }

    // 读取命令动作。
    console.log('命令动作:', message.body.action);
    // 读取命令参数。
    console.log('命令参数:', message.body.params);
  },
});

关键字段

字段类型必填/可选适用场景说明
actionString必填业务指令分发透传消息的命令动作。
paramsRecord<string, String>可选协议兼容读取命令参数。当前主要用于接收或协议兼容场景。

接收自定义类型消息

自定义消息适用于礼物、订单、卡片、互动动作等业务事件。

接收流程

接收自定义消息时，请按以下流程执行：

  1. 调用 addEventHandler 注册消息事件监听器。
  2. 监听 onMessage 回调，接收自定义消息。根据事件名和参数执行对应的界面渲染或业务逻辑。

示例代码如下所示：

client.chatManager.addEventHandler('custom-message-listener', {
  // 接收自定义消息。
  onMessage: message => {
    // 判断是否为自定义消息。
    if (message.type !== 'custom') {
      return;
    }

    // 读取自定义事件名。
    console.log('事件名:', message.body.event);
    // 读取自定义参数。
    console.log('业务参数:', message.body.params);
  },
});

关键字段

字段类型必填/可选适用场景说明
eventString必填业务事件分发自定义消息事件名。
paramsRecord<string, String>可选业务参数读取自定义业务参数。

接收合并消息

合并消息用于“聊天记录转发”或“多条消息打包转发”。接收方收到的是一条外层合并消息，若需查看其中的原始消息，还需进一步下载并解析合并消息详情。

接收流程

接收合并消息与接收普通消息的方式相同。应用可在 onMessage 回调中根据 message.type === 'combine' 识别合并消息。

合并消息包含标题、摘要以及合并消息附件信息。收到合并消息后，可直接从消息体中读取 title 和 summary；如需获取合并消息中的原始消息列表，可调用 downloadAndParseCombineMessage 下载并解析合并消息附件。首次调用该方法时，SDK 会根据合并消息中的附件信息下载并解析附件，然后返回原始消息列表。后续调用时，若附件数据已可用，SDK 可直接解析并返回原始消息列表。

提示

compatibleText 是创建合并消息时的可选参数，用于不支持合并转发消息的旧版本客户端进行兼容展示。当前 SDK 接收合并消息时，message.body 中不包含 compatibleText 字段。

示例代码如下所示：

client.chatManager.addEventHandler('combine-message-listener', {
  // 接收合并消息。
  onMessage: async message => {
    // 判断是否为合并消息。
    if (message.type !== 'combine') {
      return;
    }

    // 读取合并消息标题。
    console.log('标题:', message.body.title);
    // 读取合并消息摘要。
    console.log('摘要:', message.body.summary);
    // 下载并解析原始子消息列表。
    const subMessages = await client.chatManager.downloadAndParseCombineMessage({
      message,
    });

    console.log('子消息列表:', subMessages);
  },
});

也可以直接传入合并消息体中的最小下载参数：

const subMessages = await client.chatManager.downloadAndParseCombineMessage({
  url: combineMessage.body.url!,
  secret: combineMessage.body.secret,
});

downloadAndParseCombineMessage() 支持两种入参：{ message } 和 { url, secret }。解析出的子消息可能为 multi_body，其 body 为分段数组，需按 接收复合消息 的方式展示。

关键字段

字段类型必填/可选适用场景说明
titleString必填概览展示合并消息标题。
summaryString必填概览展示合并消息摘要。仅适合做概览展示；若要展示原始聊天记录，应进一步调用 downloadAndParseCombineMessage()。
urlString可选下载详情合并消息详情下载地址。
secretString可选下载鉴权合并消息详情下载密钥。
messageListReadonlyArray<Message>可选解析后详情展示仅在发送场景或详情解析后可能出现。
combineLevelNumber必填嵌套层级判断当前合并消息层级。

接收复合消息

自 SDK 5.2.0 起，复合消息沿用 ChatManager 的 onMessage 事件接收，无需额外建立接收机制。通过 addEventHandler 注册监听的方式见 监听消息事件。

处理时，先通过 message.type === 'multi_body' 判断整条消息是否为复合消息，再遍历其完整的有序 body 数组，最后根据每个分段的 type 读取内容。message.type 表示整条消息的类型，segment.type 表示当前分段的类型，例如 text 或 image。

复合消息的 body 本身就是分段数组，不能像普通文本消息一样读取 message.body.content，也不能将其整体作为普通图片或文件消息体处理。

以下示例以“文本＋图片”为例，展示类型判断和按分段顺序处理内容的方式。示例使用日志表示处理入口，实际应用应按遍历顺序组织同一条消息的展示内容：

client.chatManager.addEventHandler('multi-body-listener', {
  onMessage: message => {
    if (message.type !== 'multi_body' || !Array.isArray(message.body)) return;
    for (const segment of message.body) {
      switch (segment.type) {
        case 'text':
          console.log('文本:', segment.content);
          break;
        case 'image':
          // 按需使用缩略图、大图或原图地址。
          console.log('图片:', segment.thumbnailUrl ?? segment.bigImageUrl ?? segment.originalImageUrl);
          break;
        default:
          // 按类型处理视频、语音、文件、位置或自定义分段。
          console.log('分段:', segment.type, segment);
      }
    }
  },
});

其余分段的字段读取与展示方式见 视频、语音、文件、位置 和 自定义消息。复用对应示例时，应读取当前 segment 的字段，不要将整条复合消息的 body 当作普通消息对象读取。

下载复合消息附件

调用 downloadAttachment({ message }) 时传入整条复合消息，SDK 按顺序下载其中的图片、语音、视频和文件附件，跳过文本、位置和自定义分段。图片优先使用原图地址，未提供时依次使用大图或缩略图地址；其他附件使用分段中的 url。

普通附件消息返回单个 MessageAttachmentDownloadResult，复合消息返回结果数组。数组顺序与可下载分段一致，不包含被跳过的分段，不能直接使用完整 body 数组的索引对应下载结果。共用下载逻辑时，应先区分单个结果和数组。

async function downloadMultiBodyAttachments(message: Message): Promise<void> {
  if (message.type !== 'multi_body') return;
  try {
    const result = await client.chatManager.downloadAttachment({ message });
    // API 的返回类型同时兼容普通消息的单个结果和复合消息的结果数组。
    const attachments = 'data' in result ? [result] : result;
    for (const attachment of attachments) {
      console.log(attachment.filename, attachment.mimeType, attachment.data);
    }
  } catch (error) {
    console.error('下载复合消息附件失败:', error);
  }
}

每个结果的 data 为 Uint8Array 二进制数据，不是可直接赋给图片或视频元素的 URL。在浏览器中展示时，可根据 mimeType 创建 Blob，再通过 URL.createObjectURL() 生成临时 URL；资源不再使用时调用 URL.revokeObjectURL() 释放。其他运行环境应使用对应平台的文件或媒体展示能力。

此接口不提供下载进度回调。没有可下载附件或缺少远端地址时，错误码为 401；任一附件下载失败则整体失败，不返回部分成功数组，应通过 try/catch 处理失败结果。

注意事项

  • 发送端内容准备：发送方应先通过分段创建方法准备全部内容，再调用 createMultiBodyMessage()，并按阅读顺序排列 bodies。带本地文件的分段必须原样传入，不能在组装前复制、展开或重建对象。具体流程见 发送复合消息。
  • 本地文件分段复用：成功组装后，如需将本地附件用于另一条新消息，应重新创建文件分段；重发同一条失败消息应按 重新发送失败消息 处理，不要直接重新组装已消耗本地文件关联的分段。
  • 已有远程附件：发送方可直接使用 originalUrl 提供已有远程资源，避免重复上传；接收方按实际需要展示远程地址或调用下载接口。
  • 界面更新：保持分段的原始顺序；异步下载完成后更新对应消息中的附件展示。在浏览器主线程处理事件时，避免执行耗时的同步操作。
  • 会话摘要：最后一条消息为复合消息时，lastMessage.type 为 multi_body，lastMessage.body 为分段数组，应按分段生成摘要，不要读取 body.content。示例见 展示复合消息摘要。
  • 合并转发：downloadAndParseCombineMessage() 解析出的子消息可能为复合消息，应继续按子消息的 type 和 body 分段展示。解析流程见 接收合并消息。
  • 功能限制：复合消息不支持编辑或自动翻译。创建与发送方式见 发送复合消息。

离线消息同步事件

离线消息同步属于 ChatClient 级别事件，应通过 client.addEventHandler() 监听，而不是通过 chatManager.addEventHandler() 监听。

监听流程

监听离线消息同步事件时，请按以下流程执行：

  1. 调用 client.addEventHandler() 注册 ChatClient 级事件处理器。
  2. 监听 onOfflineMessageSyncStart，感知离线消息开始同步。
  3. 监听 onOfflineMessageSyncFinish，感知离线消息同步完成。
  4. 在消息处理逻辑中结合 message.isOnline 判断当前消息是否为在线消息。

示例代码

client.addEventHandler('offline-sync', {
  // 离线消息同步开始时触发。
  onOfflineMessageSyncStart: () => {
    console.log('开始同步离线消息');
  },
  // 离线消息同步完成时触发。
  onOfflineMessageSyncFinish: () => {
    console.log('离线消息同步完成');
  },
});

如需进一步区分消息来源，可在消息处理时结合 isOnline 判断：

client.chatManager.addEventHandler('online-flag-listener', {
  // 接收普通消息。
  onMessage: message => {
    // 判断当前消息是否为离线同步消息。
    if (message.isOnline === false) {
      console.log('收到离线消息:', message.msgServerId);
      return;
    }

    console.log('收到在线消息:', message.msgServerId);
  },
});

提示

  • addEventHandler 的第一个参数是事件处理器 ID，不是固定事件名，因此示例中的 'offline-sync' 可以替换为任意不重复的字符串。
  • 聊天室消息只支持在线消息，不支持离线消息。单聊和群聊既支持在线消息，也支持离线同步消息。

更多说明

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

对于聊天室下行消息，你可以通过 message.isBroadcast 判断该消息是否为通过 REST API 发送的聊天室广播消息。

client.chatManager.addEventHandler('chatroom-broadcast-listener', {
  // 接收普通消息。
  onMessage: message => {
    // 判断是否为聊天室广播消息。
    if (message.conversationType === 'chatRoom' && message.isBroadcast) {
      console.log('收到聊天室广播消息:', message.msgServerId);
    }
  },
});

消息回执

关于消息送达回执和已读回执的实现，详见 消息回执文档。

接口列表

API 名称所属模块/类说明
downloadAttachmentChatManager下载普通消息的单个附件，或复合消息的全部附件。
downloadAndParseCombineMessageChatManager下载并解析合并消息中的原始消息列表。
上次编辑于:
环信 IM 文档
© 环信 2026