logo
控制台登录/注册
文档
客户端 API
服务端 API
即时通讯
uni-app: TS
产品简介
概述
计费说明
基本概念介绍
客户端 SDK
下载
客户端 APIlink
发布日志
升级指南
错误码
快速开始
跑通示例代码
实现基本消息收发
功能指引
用户
房间
群组
消息
会话
缓存管理
内容审核
呼叫邀请
离线推送
迁移方案
常见问题link
当前页

收发消息

功能简介

ZIM SDK 支持单聊消息、群组消息、房间消息等的收发，以及查询历史消息、删除消息等功能。可广泛应用于娱乐社交、电商购物、在线教育、互动直播等多种场景下。

本文档介绍了如何使用 ZIM SDK 的接口，实现各类消息的收发功能与监听消息的状态。

说明

开发者请根据业务需要，查看 查询历史消息、删除消息 等功能。

消息类型

目前 ZIM 支持的消息类型如下：

消息类型说明特性及适用场景
ZIMCommandMessage(2)开发者可自定义数据内容的信令消息。消息大小不超过 5 KB。限频：单个客户端发送频率限制为 10 次/秒（两次之间间隔 100 毫秒）。

不可存储，一般适用于“语聊房”、“在线课堂”等房间内的信令传输，比如上下麦操作、送礼物，发送在线课堂课件等。

支持更高的并发，但不可靠，不保证消息送达和消息顺序。

相关接口：sendMessage

ZIMBarrageMessage(20)房间内弹幕文本消息。消息大小不超过 5 KB。

限频：单个客户端发送频率无限制。

不可存储，专门用于房间内的高频、不可靠、允许丢掉的消息，一般适用于发送“弹幕消息”的场景中。

支持高并发，但不可靠，不保证消息送达。

相关接口：sendMessage

ZIMTextMessage(1)文本消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。限频：单个客户端发送频率限制为 10 次/秒（两次之间间隔 100 毫秒）。

消息可靠有序，可存储为历史消息（保存时间请参考 计费说明 - 版本差异 中“历史消息存储天数”）。
可用于单聊、房间、群聊等即时聊天场景。房间解散后，“房间聊天”的消息不存储。

  • 图片、文件、语音、视频：通常用于发送富媒体文件类型的消息。
  • 自定义消息：通常用于发送投票类型、接龙类型、视频卡片类型等消息。
  • 组合消息：常用于发送图文消息。

相关接口：sendMessage、replyMessage

ZIMMultipleMessage(10)组合消息，即包含多个 item 的消息，可包括多条文本、至多 10 张图片、1 个文件、1 个音频、1 个视频和 1 条自定义消息。
说明
  • Item 总量不得超过 20。
  • 图片、音频、文件和视频的大小和格式限制与对应的富媒体消息类型相同。
ZIMImageMessage(11)图片消息。支持主流图片格式，包括 JPG、PNG、BMP、TIFF、GIF、WebP，大小不超过 10 MB。
ZIMFileMessage(12)文件消息。消息内容为文件，格式不限，大小不超过 100 MB。
ZIMAudioMessage(13)语音消息。支持 MP3、M4A 格式的语音文件，时长不超过 300 秒，大小不超过 6 MB。
ZIMVideoMessage(14)视频消息。支持 MP4、MOV 格式的视频文件，大小不超过 100 MB。
说明
若要在消息发送成功后获取视频首帧的宽高信息，视频必须使用 H.264 或 H.265 编码格式。
ZIMCombineMessage(100)合并消息，消息大小无限制。
ZIMCustomMessage(200)自定义消息。消息大小上限默认为 2 KB。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。开发者可自定义消息的类型，并自行完成消息的解析，ZIM SDK 不负责定义和解析自定义消息的具体内容。

发送消息

以客户端 A 向客户端 B 发送消息为例：

  1. 客户端 A、B 分别创建自己的 ZIM 实例，并注册 on 监听的 peerMessageReceived 回调接口，用于接收单聊消息通知。
  1. 客户端 A、B 分别登录 ZIM SDK。
  2. 客户端 A 调用 sendMessage 接口，设置 conversationType 为 ZIMConversationType.Peer 发送一条单聊消息到客户端 B。
  3. 客户端 B 将通过 peerMessageReceived 回调接口，收到客户端 A 的消息。
注意

发送消息时，统一使用 sendMessage 接口，并根据会话类型传入对应的 conversationType 取值。

目前，ZIM SDK 对于 sendMessage 接口有以下限制：

  • 不支持向自己发送消息：即 toConversationID 不能设置为调用者自己的用户 ID。
  • 不支持发送空白消息：消息内容不能为空或空白。 当出现上述两种情况时，ZIM SDK 会返回错误 6000001，并提示传入参数错误。

普通消息

普通消息是指消息内容为文本的消息，包含 ZIMTextMessage、ZIMBarrageMessage 消息类型。

// 发送单聊 `Text` 信息
// toConversationID 为 消息需要发送的会话 ID
// 单聊时，toConversationID 即是对方的 userID；群组时，toConversationID 即是群组的 groupID；房间时，toConversationID 即是房间的 roomID
const toConversationID = ''; // 对方 userID
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

const messageTextObj: ZIMMessage = {
    type: 1,
    message: 'xxxx'
};

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

富媒体消息

ZIM SDK 支持发送多种类型的富媒体消息，包含图片、文件、音频、视频等消息类型，开发者可以通过以下步骤实现富媒体文件消息的收发。

  1. 用户登录成功后，指定消息类型（图片、文件、音频、视频）、会话类型（单聊、房间、群组）等，向指定会话发送富媒体消息。
  2. 接收方用户登录成功后，根据会话类型（单聊、房间、群组）的相关回调监听，接收富媒体消息的相关通知，以及下载富媒体消息文件到本地。
注意
  • 发送富媒体消息时，填写的待发送文件路径，必须使用 UTF-8 编码格式和本地文件的绝对路径。
  • 如果需要向房间/群组内发送富媒体消息，消息发送者必须要在这个房间/群组内。
说明
  1. 本地图片（通过 fileLocalPath 发送） 图片将上传至 ZEGO 服务器，并自动生成 fileDownloadURL（发送方需在消息发送成功的回调中，通过 ZIMMessage 对象获取该 URL）。发送方和接收方均能通过 fileDownloadURL 下载原图（即使发送方本地图片已删除，仍可通过该 URL 重新获取）。
  2. 网络图片（通过 fileDownloadURL 直接发送） 不会经过 ZEGO 服务器中转，SDK 仅透传该 URL，不会生成新的服务端下载地址。需要确保该 URL 是公网可访问的有效地址，接收方需自行处理图片加载（如缓存、防失效等）。
  • 若发送方发送本地图片后删除了手机中的原图，可通过 fileDownloadURL 重新下载；
  • 若需降低服务器存储成本，或图片需实时更新（如动态生成的海报），可直接发送网络图片 URL。
// 发送“本地文件”富媒体消息示例 - 单聊
// conversationID 为 消息需要发送的会话 ID
// 单聊时，conversationID 即是对方的 userID；群组时，conversationID 即是群组的 groupID；房间时，conversationID 即是房间的 roomID
const conversationID = 'xxxx';
const config: ZIMMessageSendConfig = { priority: 1 };
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        
    },
    onMediaUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) {
        // 您可以在这里展示上传进度
    }
};

function sendMessage(file: string) {
    /* 以下代码仅为示例：实际开发时请结合需求和文件类型，创建对应的 `媒体消息对象` */

    // 如果是 `图片` 消息
    let mediaMessageObj: ZIMMessage = {
        fileLocalPath: file,
        type: 11,
    };
    // 如果是 `文件` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 12,
    };
    // 如果是 `音频` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 13,
        audioDuration: 100, // 请填写音频文件播放时长，单位秒（必填）
    };
    // 如果是 `视频` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 14,
        videoDuration: 100, // 请填写视频文件播放时长，单位秒（必填）
    };
  
    zim.sendMessage(mediaMessageObj, conversationID, 0, config, notification);  
}

// Android 文件绝对路径 示例
const file = '/storage/emulated/0/Android/data/packagename/picture/xxx.jpg';
// iOS 文件绝对路径 示例  
const file = '/var/mobile/Containers/Data/Application/C142EFE6-9DEC-449D-89B7-BF99F2578F98/tmp/D1513E30-2641-440B-B897-48CD43BE1D04.jpeg';

// 注意：必须是文件的绝对路径，不能是 file://xxxx 等形式的字符串（某些跨平台框架提供的获取本地文件返回的文件路径）
sendMessage(file);
// 发送“网络文件”富媒体消息示例 - 单聊
/* 发送网络文件消息时，ZIM SDK 仅透传相关字段到后台，ZIM 后台不会保存网络文件 */
// conversationID 为 消息需要发送的会话 ID
// 单聊时，conversationID 即是对方的 userID；群组时，conversationID 即是群组的 groupID；房间时，conversationID 即是房间的 roomID
const conversationID = 'xxxx';
const config: ZIMMessageSendConfig = { priority: 1 };
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
};

/* 以下代码仅为示例：实际开发时请结合需求和文件类型，创建对应的 `媒体消息对象` */

// 如果是 `图片` 消息
let mediaMessageObj: ZIMMessage = {
    fileDownloadUrl: 'https://xxxx.jpeg', // 原图
    thumbnailDownloadUrl: 'https://xxxx-thumbnail.jpeg', // 缩略图
    largeImageDownloadUrl: 'https://xxxx-large.jpeg', // 大图
    type: 11,
};
// 如果是 `文件` 消息
mediaMessageObj = {
    fileDownloadUrl: 'https://xxxx.pdf',
    type: 12,
};
// 如果是 `音频` 消息
mediaMessageObj = {
    fileDownloadUrl: 'https://xxxx.mp3',
    type: 13,
    audioDuration: 100, // 请填写音频文件播放时长，单位秒（必填）
};
// 如果是 `视频` 消息
mediaMessageObj = {
    fileDownloadUrl: 'https://xxxx.mp4',
    videoFirstFrameDownloadUrl: 'https://xxxx-firstframe.jpeg', // 视频首帧图片
    type: 14,
    videoDuration: 100, // 请填写视频文件播放时长，单位秒（必填）
};
  
zim.sendMessage(mediaMessageObj, conversationID, 0, config, notification);

上传文件进度回调

  • 通过 onMediaUploadingProgress 回调，接收富媒体消息的上传文件进度的相关通知。

    • message：正在发送的消息对象。
    • currentFileSize：当前已上传文件的大小。
    • totalFileSize：上传文件的总体大小。
type onMediaUploadingProgress = (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => void;

信令消息

ZIM SDK 支持开发者实现信令类型的消息收发，开发者可以通过 ZIMCommandMessage 对象定义自己的消息类型，例如位置消息等。

说明

信令消息不支持离线推送和本地存储。

// 发送单聊 `Command` 信息
// toConversationID 为 消息需要发送的会话 ID
// 单聊时，toConversationID 即是对方的 userID；群组时，toConversationID 即是群组的 groupID；房间时，toConversationID 即是房间的 roomID
const toConversationID = ''; // 对方 userID
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

// 这里以 JSON 字符串 为例，需要将字符串转换为 Uint8Array
// peerMessageReceived 收到 type 为 2 的 Command 消息时，需要将 Uint8Array 转换为 JSON 字符串
const jsonText = JSON.stringify({ id: '111', name: '张三' });
const uint8Array = new Uint8Array(Array.from(unescape(encodeURIComponent(jsonText))).map((val) => val.charCodeAt(0)));

const messageCommandObj: ZIMMessage = { type: 2, message: uint8Array };

zim.sendMessage(messageCommandObj, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

自定义消息

ZIM SDK 支持开发者实现自定义类型的消息收发，开发者可以通过 ZIMCustomMessage 对象创建自定义类型消息，例如投票类型、接龙类型、视频卡片类型等。

说明
  • 仅 2.8.0 及以上版本的 ZIM SDK 支持发送自定义类型消息，接收并查看自定义类型消息的内容。
  • 如果接收端的 SDK 版本介乎 [2.0.0, 2.8.0) 区间，可以收到自定义消息时，但会显示此消息类型为未知，且无法获取信息内容。如需获取此条消息，请将 SDK 升级为 2.8.0 或以上版本。
  • 如果接收端的 SDK 版本为 1.x.x 版本，则无法收到自定义消息，也不会收到未知消息。
// 发送自定义信息

// 指定用户的 ID
// 单聊时，toConversationID 即是对方的 userID；群组时，toConversationID 即是群组的 groupID；房间时，toConversationID 即是房间的 roomID
const toConversationID = "xxxx";
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
// 发送消息的高级属性配置
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

const zimCustomMessage: ZIMMessage = {
    type: 200,
    message: 'xxxx', // 自定义消息的文本内容
    subType: 100, // 具体的自定义类型
    searchedContent: 'xxxx' // 自定义消息的检索字段
};

zim.sendMessage(zimCustomMessage, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

组合消息

ZIM SDK 支持开发者实现组合类型的消息收发，开发者可以通过 ZIMMultipleMessage 对象组合多种消息类型（文本、图片、音频、视频、文件和自定义消息），实现图文消息等场景。

说明
  • 仅 2.19.0 及以上版本的 ZIM SDK 支持发送组合类型消息，接收并查看组合类型消息的内容。
  • 如果接收端的 SDK 版本介乎 [2.0.0, 2.19.0) 区间，可以收到组合消息时，但会显示此消息类型为未知，且无法获取信息内容。如需获取此条消息，请将 SDK 升级为 2.19.0 或以上版本。
  • 如果接收端的 SDK 版本为 1.x.x 版本，则无法收到组合消息，也不会收到未知消息。
ZIMMultipleMessage_zh.png

通过 multipleMediaUploadingProgress 回调，接收组合消息中富媒体文件的上传进度的相关通知。在此回调中，您可以了解到以下字段：

  • currentFileSize：已上传文件总大小，单位为 Byte。
  • totalFileSize：组合消息中多媒体文件的总大小，，单位为 Byte。
  • messageInfoIndex：接收到此回调时，当前正在上传的文件在 ZIMMultipleMessage 数组的索引。
  • currentIndexFileSize： 接收到此回调时，当前正在上传的文件的已上传大小，单位为 Byte。
  • totalIndexFileSize：接收到此回调时，当前正在上传的文件的实际大小，单位为 Byte。

上述字段可用于计算多媒体文件的总上传进度、以及当前文档的上传进度：

  • 总上传进度 = currentFileSize / totalFileSize。
  • 当前文件上传进度 = currentIndexFileSize / totalIndexFileSize。

:::

// 在单聊会话中向指定用户发送组合消息

// 指定用户的 ID
// 单聊时，toConversationID 即是对方的 userID；群组时，toConversationID 即是群组的 groupID；房间时，toConversationID 即是房间的 roomID
const toConversationID = "xxxx";
// 发送消息的高级属性配置
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        
    },
    onMultipleMediaUploadingProgress: (
        message: ZIMMultipleMessage,
        currentFileSize: number,      // 已上传文件总大小，单位为 Byte。比如已上传了 20,971,520 Byte，则此处为 20,971,520。
        totalFileSize: number,        // 总文件大小，单位为 Byte。比如总文件大小 104,857,600 Byte，则此处为 104,857,600
        messageInfoIndex: number,     // 接收到此回调时，当前正在上传的文件在 messageInfoList 数组的索引
        currentIndexFileSize: number, // 接收到此回调时，当前正在上传的文件的已上传大小，单位为 Byte。
        totalIndexFileSize: number    // 接收到此回调时，当前正在上传的文件的实际大小，单位为 Byte。
    ) => {
        // 开发者可以监听这个回调获取多媒体上传的进度
        // 总文件上传进度： currentFileSize / totalFileSize
        // 上述例子中，总文件上传进度为：20,971,520 / 104,857,600 = 20% 
        // 接收此回调时，当前正在上传的文件的上传进度：currentIndexFileSize / totalIndexFileSize
    }
};

const zimMultipleMessage: ZIMMessage = {
    type: 10,
    // 组合消息 Item 列表，最多只可以包含 20 个 Item
    messageInfoList: [
        // 文本
        {
            type: 1,
            message: 'xxxx',
        },
        // 自定义消息：最多支持 1 个
        {
            type: 200,
            message: 'xxxx',
            subType: 100,
            searchedContent: 'xxxx'
        },
        // 图片：最多支持 10 个
        // 网络图片示例
        {
            type: 11,
            fileDownloadUrl: 'https://xxxx.jpeg', // 原图
            thumbnailDownloadUrl: 'https://xxxx-thumbnail.jpeg', // 缩略图
            largeImageDownloadUrl: 'https://xxxx-large.jpeg', // 大图
        },
        // 本地图片示例
        {
            type: 11,
            fileLocalPath: file, // 上传的文件
        },
        // 文件：最多支持 1 个
        {
            type: 12,
            fileLocalPath: file, // 上传的文件
        },
        // 音频：最多支持 1 个
        {
            type: 13,
            fileLocalPath: file, // 上传的文件
            audioDuration: 100, // 请填写音频时长，单位秒（必填）
        },
        // 视频：最多支持 1 个
        {
            type: 14,
            fileLocalPath: file, // 上传的文件
            videoDuration: 100, // 请填写视频时长，单位秒（必填）
        }
    ]
};

zim.sendMessage(zimMultipleMessage, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

@ 消息

@ 消息，是指包含“@ + 用户”内容的消息。被 @ 的用户在收到消息时会强提醒。

说明

仅 2.14.0 及以上版本的 ZIM SDK 支持发送消息中带 @ 信息。

@ 消息不属于消息类型，是消息对象的属性。一条消息既可以是文本消息或其他类型消息，同时也是 @ 消息。

在调用 sendMessage 发送消息时，可以通过以下属性或方法（可同时使用）将一条消息设置为 @ 信息：

  • mentionedUserIDs：提醒指定用户（可以是会话外用户）查看消息。传入的 userID 列表长度最多为 50，如需上调，请联系 ZEGO 技术支持。
  • isMentionAll：提醒会话内所有其他用户查看消息。
// 以下为用户在单聊会话中发送 @ 消息（文本消息）的示例代码：
// 单聊时，toConversationID 即是对方的 userID；群组时，toConversationID 即是群组的 groupID；房间时，toConversationID 即是房间的 roomID
const toConversationID = '';
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

const messageTextObj: ZIMMessage = {
    type: 1,
    message: 'xxxx',
    isMentionAll: true, // 提醒会话内所有其他用户查看消息
    mentionedUserIDs: ["userId1", "userId2"], // 提醒列表中用户查看消息
};

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

接收消息

注意
  • 开发者可以通过 on 注册监听，用于接收消息相关通知。
  • 接收消息时：
  • 接收消息时，收到的消息类型是基类 ZIMMessage 。开发者需要根据其中的 type（具体请参考 ZIMMessageType ）字段，判断消息类型，然后强转基类为具体的子类。
  • 接收消息时，可以使用消息的 orderkey 来实现排序；即 orderkey 越大，消息的时间越新。接收到消息后，会自动更新消息未读数量。
// 收到单消息的回调
zim.on('peerMessageReceived', (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => {
    
    const config: ZIMMediaDownloadConfig = {messageInfoIndex: 0};

    data.messageList.forEach((msg) => {
        if (msg.type == 2) {
            // 信令消息，这里以 JSON 字符串 为例，将 Uint8Array 消息内容转为 JSON 字符串
            const uint8Array = msg.message;
            const jsonText = decodeURIComponent(escape(String.fromCharCode(...Array.from(uint8Array))));
            const jsonObj = JSON.parse(jsonText);
        } else if (msg.type == 11 || msg.type == 12 || msg.type == 13 || msg.type == 14) {
            // 下载富媒体文件消息
            zim.downloadMediaFile(msg, 1, config, (_msg, currentFileSize, totalFileSize) => {
                // 下载进度
            })
            .then((res: ZIMMediaDownloadedResult) => {
                // 操作成功
            })
            .catch((err: ZIMError) => {
                // 操作失败
            })
        } else if (msg.type == 10) {
            // 下载组合消息中的富媒体文件
            msg.messageInfoList.forEach((info, i) => {
                if (info.type == 11 || info.type == 12 || info.type == 13 || info.type == 14) {
                    // 设置为 item 的序号
                    const infoConfig: ZIMMediaDownloadConfig = {messageInfoIndex: i};

                    zim.downloadMediaFile(msg, 1, infoConfig, (_msg, currentFileSize, totalFileSize) => {
                        // 下载进度
                    })
                    .then((res: ZIMMediaDownloadedResult) => {
                        // 操作成功
                    })
                    .catch((err: ZIMError) => {
                        // 操作失败
                    })
                } 
            }
        }
    })
});

// 收到群组消息的回调
zim.on('groupMessageReceived', (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => {
});

// 收到房间消息的回调
zim.on('roomMessageReceived', (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => {
});

富媒体消息

接收富媒体消息时，可以直接获取富媒体消息的相关 URL 属性。

如需下载富媒体消息到本地，可调用 downloadMediaFile 接口。

下载富媒体消息时，需要指定对应的媒体消息的文件类型。

  • 图片消息：可以选择下载原始文件、大图、缩略图。
  • 文件/音频消息：仅能选择下载文件/音频的原始文件。
  • 视频消息：可以选择下载视频原始文件、视频首帧的缩略图。

下载文件进度回调

  • 通过 ZIMMediaDownloadingProgress 回调，接收富媒体消息的下载文件进度的相关通知。

    • message：正在下载的消息对象。
    • currentFileSize：当前已下载文件的大小。
    • totalFileSize：下载文件的总体大小。
type ZIMMediaDownloadingProgress = (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => void;

组合消息

如果需要下载组合消息的 Item 中的富媒体文件，可遍历 messageInfoList 列表并判断为富媒体文件类型时，调用 downloadMediaFile 接口下载。开发者可参考 接收消息 - 富媒体消息 了解此接口参数详情。

Tips 消息

ZIM SDK 支持用户在会话内的操作转换为 Tips 消息。当相关操作出现后，ZIM SDK 会向会话发送一条 Tips 消息进行通知，详情请参考 接收 Tips 消息。

@ 消息

说明
  • 仅 2.14.0 及以上版本的 ZIM SDK 支持接收并查看 @ 信息中的内容。
  • 如果接收端的 SDK 版本介乎 [2.0.0, 2.14.0) 区间，则收到的消息和会话中不会带 @ 信息。
  • 如果接收端的 SDK 版本为 1.x.x 版本，则无法收到 @ 信息。

获取 mentionedInfoList

当会话内用户被提醒后，可以被动或主动获取 mentionedInfoList 。

mentionedInfoList，包含 @ 消息的对应消息 ID，发送者 userID，以及 @ 消息的类型 ZIMMessageMentionedType ，开发者可用于实现标记会话等多样业务逻辑。

被动获取

在用户被提醒时，会收到 conversationChanged 回调，即可获取当前 ZIMConversation 的最新 mentionedInfoList 。

zim.on('conversationChanged', (zim: ZIM, data: ZIMEventOfConversationChangedResult) => {
    console.log(data.info.mentionInfoList);
});
主动获取

如用 queryConversationList 或者 queryConversation 主动拉取会话，也可获取会话里面的 mentionedInfoList ，可参考以下示例代码：

const mentionedInfoList = conversaion.mentionedInfoList;

清除会话的 mentionedInfoList

接收 @ 消息后，用户需要清除会话的 mentionedInfoList ，才能不再被提醒。

清除会话的 mentionedInfoList 接口与清除会话消息未读数接口相同：

获取被提醒用户列表

会话内所有用户都可以调用 mentionedUserIDs 参数获取具体的被提醒用户列表。

const userIds = message.mentionedUserIDs;

确认是否为全员提醒

会话内所有用户都可以调用 isMentionAll 参数，确认消息是否为全员提醒消息。

const isMentionAll = message.isMentionAll;

收发全员推送消息

ZIM 支持您通过服务端向 App 所有在线用户发送消息，目标用户通过客户端接收相关消息。

从服务端向所有用户发送消息

请查看服务端 API 文档 全员推送 文档，实现从服务端向所有用户发送消息。

接收服务端发送的全员推送消息

说明
  • 仅 2.10.0 及以上版本的 ZIM SDK 支持接收并查看全员推送消息的内容。
  • 如果接收端的 SDK 版本介乎 [2.0.0, 2.10.0) 区间，不可以收到服务端发送的全员推送消息，如需获取此条消息，请将 SDK 升级为 2.10.0 或以上版本。

通过 broadcastMessageReceived 回调，即可接收全员推送消息。

示例代码：

// 用户接收全员推送消息
zim.on('broadcastMessageReceived', (zim: ZIM, data: ZIMEventOfBroadcastMessageReceivedResult) => {
    console.log(data.message);
});

发送消息进阶功能

转发消息

ZIM SDK 支持实现以下两种形式的消息转发：

  • 合并消息后转发。
  • 逐条消息转发。

具体实现流程，请参考 转发消息。

重发消息

说明
如需使用本功能，请集成 2.20.0 及以上版本的 ZIM SDK。

当用户发送单聊和群聊消息时，网络断开：

  • 若在 30 秒内网络恢复，则 ZIM SDK 会自动重发该消息。
  • 若在 30 秒内网络未恢复，则消息发送失败。
  • 如需配置网络恢复等待时间，请联系 ZEGO 技术支持。

当自动重发失败时，用户可以在网络恢复后，手动重发该消息。此时，再次调用 sendMessage 接口，将发送失败的消息对象重新填入，并且参数 config.isRetrySend 设置为 true。

手动重发成功后，该消息会排序到当前最后位置。例如：当前消息排序为：A（成功）、B（失败）、C（成功），当重发消息 B 成功后，排序为 A、C、B。

说明
当 ZIM SDK 自动重发消息时，若用户同时进行手动重发，接口将调用失败，ZIM SDK 提示参数错误。
// 重发单聊 `Text` 信息

const toConversationID = ''; // 对方 userID
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
// !mark
    isRetrySend: true, // 需要设置为 true，表示重发此消息
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

const messageTextObj: ZIMMessage = {}; // 从 queryHistoryMessage 接口获取发送失败的消息

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
// !mark
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

发送不计入未读消息数的消息

在调用 sendMessage 发送消息时，可以通过以下参数设置发送的消息不会被计入到未读消息数中：

注意

仅 2.23.0 及以上版本的 ZIM SDK 支持发送不计入未读消息数的消息。

// 以下为用户在单聊会话中发送不计入未读消息数的示例代码：
const toConversationID = ''; // 对方 userID
const conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
const config: ZIMMessageSendConfig = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
// !mark
    disableUnreadMessageCount: true, // 设置消息为不计入未读消息数消息
};

const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {}
}

const messageTextObj: ZIMMessage = {
    type: 1,
    message: 'xxxx',
};

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // 发送成功
    })
    .catch((err: ZIMError) => {
        // 发送失败
    });

监听消息发送状态

在一些弱网场景中，可能存在以下场景，即消息发送成功，但由于某些因素（如网络丢包），导致 ZIM SDK 未收到服务端应答。此时，ZIM SDK 会因应答超时而认为消息发送失败，但实际上消息发送成功，导致消息状态混乱。为解决该问题，明确消息最终状态， 2.6.0 或以上版本 SDK 支持开发者监听 messageSentStatusChanged 回调，接收消息的状态变化。消息的状态有三种，即 Sending、Success 和 Failed。根据消息状态的变化，开发者可判断消息发送是否成功，并在业务上做相应处理。

// 监听消息状态
zim.on('messageSentStatusChanged', (zim: ZIM, data: ZIMEventOfMessageSentStatusChangedResult) => {
    data.infos.forEach((info) => {
        console.warn(info.message, info.status);
    });  
});

Previous

群成员管理

Next

获取历史消息

当前页

返回到顶部