收发消息

功能简介

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

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

说明

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

消息类型

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

消息类型	说明	特性及适用场景
ZIMCommandMessage(2)	开发者可自定义数据内容的信令消息。消息大小不超过 5 KB，单个客户端发送频率限制为 10 次/秒。	不可存储，支持更高的并发；一般适用于“语聊房”、“在线课堂”等房间内的信令传输，比如上下麦操作、送礼物，发送在线课堂课件等。相关接口：sendMessage
ZIMBarrageMessage(20)	房间内弹幕文本消息。消息大小不超过 5 KB，单个客户端发送频率无限制。	不可存储，专门用于房间内的高频、不可靠、允许丢掉的消息，一般适用于发送“弹幕消息”的场景中。支持高并发，但不可靠，不保证消息送达。相关接口：sendMessage
ZIMTextMessage(1)	文本消息。消息大小不超过 32 KB，单个客户端发送频率限制为 10 次/秒。	消息可靠有序，可存储为历史消息（保存时间请参考计费说明 - 版本说明中“历史消息存储天数”）。可用于单聊、房间、群聊等即时聊天场景。房间解散后，“房间聊天”的消息不存储。图片、文件、语音、视频：通常用于发送富媒体文件类型的消息。自定义消息：通常用于发送投票类型、接龙类型、视频卡片类型等消息。组合消息：常用于发送图文消息。相关接口：sendMessage、replyMessage
ZIMMultipleMessage(10)	组合消息，即包含多个 item 的消息，可包括多条文本、至多 10 张图片、1 个文件、1 个音频、1 个视频和 1 条自定义消息。说明 Item 总量不得超过 20。图片、音频、文件和视频的大小和格式限制与对应的富媒体消息类型相同。
ZIMImageMessage(11)	图片消息。支持主流图片格式，包括 JPG、PNG、BMP、TIFF、GIF、WebP，大小不超过 10 MB，单个客户端发送频率限制为 10 次/秒。
ZIMFileMessage(12)	文件消息。消息内容为文件，格式不限，大小不超过 100 MB，单个客户端发送频率限制为 10 次/秒。
ZIMAudioMessage(13)	语音消息。支持 MP3、M4A 格式的语音文件，时长不超过 300 秒，大小不超过 6 MB，单个客户端发送频率限制为 10 次/秒。
ZIMVideoMessage(14)	视频消息。支持 MP4、MOV 格式的视频文件，大小不超过 100 MB，单个客户端发送频率限制为 10 次/秒。说明若要在消息发送成功后获取视频首帧的宽高信息，视频必须使用 H.264 或 H.265 编码格式。
ZIMCombineMessage(100)	合并消息，消息大小无限制，单个客户端发送频率限制为 10 次/秒。
ZIMCustomMessage(200)	自定义消息。开发者可自定义消息的类型，并自行完成消息的解析，ZIM SDK 不负责定义和解析自定义消息的具体内容。

收发普通消息

普通消息，包含 ZIMTextMessage、ZIMBarrageMessage 等消息类型。

注意

开发者可以通过注册 on 监听，用于接收相关通知（接收房间消息、连接状态、token 即将过期等通知）。
接收消息时，收到的消息类型是基类 ZIMMessage 。开发者需要根据其中的 type（具体请参考 ZIMMessageType ）字段，判断消息类型是 Text 还是 Command，然后强转基类为具体的子类（ ZIMTextMessage 或 ZIMCommandMessage ），然后从 “message” 字段获取消息内容。
接收消息时，可以使用消息的 orderkey 来实现排序；即 orderkey 越大，消息的时间越新。接收到消息后，会自动更新消息未读数量。

发送消息

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

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

注意

目前 ZIM 不支持调用 sendMessage 接口，向自己发送消息（即 toConversationID = 自己的 ID）。如果尝试向自己发送消息，会返回错误 6000001，并提示传入参数错误。

示例代码

// 发送单聊 `Text` 信息

var toConversationID = ''; // 对方 userID
var conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
var config = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
};

var notification = {
    onMessageAttached: function(message) {
    }
}

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

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

Copied!

接收消息

说明

发送消息时，统一使用 sendMessage 接口，并根据会话类型传入对应的 conversationType 取值。
接收消息时：
- 单聊消息（Peer 类型），通过 peerMessageReceived 回调接收。
- 房间消息（Room 类型），通过 roomMessageReceived 回调接收。
- 群组消息（Group 类型），通过 groupMessageReceived 回调接收。

Untitled

// 收到单聊通信的消息回调
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});

// 收到群组消息的回调
zim.on('groupMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});

// 收到房间消息的回调
zim.on('roomMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});

Copied!

收发富媒体消息

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

用户登录成功后，指定消息类型（图片、文件、音频、视频）、会话类型（单聊、房间、群组）等，向指定会话发送富媒体消息。
接收方用户登录成功后，根据会话类型（单聊、房间、群组）的相关回调监听，接收富媒体消息的相关通知，以及下载富媒体消息文件到本地。

发送富媒体消息

用户登录成功后，调用 sendMessage 接口，指定会话、消息类型（图片、文件、音频、视频）、会话类型（单聊、房间、群组）、以及相关消息配置，向指定会话发送富媒体消息。

注意

发送富媒体消息时，填写的待发送文件路径，必须使用 UTF-8 编码格式。
如果需要向房间/群组内发送富媒体消息，消息发送者必须要在这个房间/群组内。

发送“本地文件”消息示例

发送“网络文件”消息示例

富媒体文件消息的发送进度回调

开发者可以通过 onMediaUploadingProgress 回调，接收富媒体消息的上传发送进度的相关通知。

Untitled

function onMediaUploadingProgress(message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number);

Copied!

其中：

message：正在发送消息的内容。
currentFileSize：当前已被发送的消息大小。
totalFileSize：发送消息的总体大小。

接收富媒体消息

接收方用户登录成功后，根据会话类型（单聊、房间、群组）的相关回调监听（ peerMessageReceived 、 roomMessageReceived 、 groupMessageReceived ），接收富媒体消息的相关通知，然后可以直接获取富媒体消息的相关 URL 属性。

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

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

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

Untitled

zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    const config = {messageInfoIndex: 0}
    messageList.forEach((msg) => {
        if (msg.type == 11) {
            zim.downloadMediaFile(msg, 1, config (_msg, currentFileSize, totalFileSize) => {});
        }
    });
});

Copied!

富媒体文件消息的下载进度回调

开发者可以通过 ZIMMediaDownloadingProgress 回调，接收富媒体消息的下载进度的相关通知。

Untitled

function ZIMMediaDownloadingProgress(message: ZIMMessage, currentFileSize: number, totalFileSize: number);

Copied!

其中：

message：正在下载的消息内容。
currentFileSize：当前已被下载的消息大小。
totalFileSize：下载消息的总体大小。

收发信令消息

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

说明

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

以下以向指定用户发送信令消息为例。

发送信令消息

Untitled

// 发送单聊 `Command` 信息

var toConversationID = ''; // 对方 userID
var conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
var config = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};

var notification = {
    onMessageAttached: function(message) {
        
    }
}

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

var messageCommandObj = { type: 2, message: uint8Array };

zim.sendMessage(messageCommandObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

Copied!

接收信令消息

Untitled

// 用户接收信令消息
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
    messageList.forEach(function (msg) {
        // 收到 `Command` 消息时，这里以 JSON 字符串 为例，将 Uint8Array 消息内容转为 JSON 字符串
        if (msg.type == 2) {
            var uint8Array = msg.message;
            var jsonText = decodeURIComponent(escape(String.fromCharCode(...Array.from(uint8Array))));
            var jsonObj = JSON.parse(jsonText);
            console.log('peerMessageReceived', jsonObj);
        }
    })
});

Copied!

收发自定义消息

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

说明

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

发送自定义消息

发送自定义消息使用的接口为 sendMessage ，与发送普通消息所用接口相同，开发者可参考收发普通消息 - 发送消息了解此接口参数详情。

开发者需要通过 ZIMCustomMessage 对象定义自定义类型消息，包括以下参数：

以下为用户在单聊会话中发送自定义消息的示例代码：

Untitled

// 发送自定义信息

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

var notification = {
    onMessageAttached: function(message) {
       
    }
}

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

zim.sendMessage(zimCustomMessage, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

Copied!

接收自定义消息

接收自定义消息的回调接口与接收普通消息的回调接口一致，请参考收发普通消息 - 接收消息了解具体接口。

以下为用户在单聊会话中接收自定义消息的示例代码：

Untitled

// 用户在单聊会话中接收自定义消息
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
    messageList.forEach(function (msg) {
        // 收到 `Custom` 消息时
        if (msg.type == 200) {
        }
    })
});

Copied!

收发组合消息

ZIM SDK 支持开发者实现组合类型的消息收发，开发者可以通过 ZIMMultipleMessage 对象组合多种消息类型，例如图文类型等。

说明

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

发送组合消息

用户登录成功后，通过 ZIMMultipleMessage 对象组合多种消息类型（文本、图片、音频、视频、文件和自定义文本等），调用 sendMessage 接口向单聊、房间或群聊会话发送该消息。

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

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

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

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

以下为用户在单聊会话中发送组合消息的示例代码：

Untitled

// 选择本地文件的方法
var file = ''; // 上传的文件的绝对路径

Copied!

Untitled

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

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

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

var zimMultipleMessage = {
    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(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

Copied!

接收组合消息

接收组合消息的回调接口与接收普通消息的回调接口一致，请参考收发普通消息 - 接收消息了解具体接口。

以下为用户在单聊会话中接收组合消息的示例代码：

Untitled

// 用户在单聊会话中接收组合消息
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, fromConversationID);
    messageList.forEach(function (msg) {
        // 收到 `Multiple` 消息时
        if (msg.type == 10) {
            msg.messageInfoList.forEach(function (info) {
                // 根据消息类型展示 UI
                console.log('组合消息 item 类型：' + info.type);
            }
        }
    })
});

Copied!

收发 @ 消息

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

说明

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

发送 @ 消息

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

mentionedUserIDs：提醒指定用户（可以是会话外用户）查看消息。传入的 userID 列表长度最多为 50，如需上调，请联系 ZEGO 技术支持。
isMentionAll：提醒会话内所有其他用户查看消息。

说明

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

Untitled

// 以下为用户在单聊会话中发送 @ 消息（文本消息）的示例代码：
var toConversationID = ''; // 对方 userID
var conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
var config = { 
    priority: 1, // 设置消息优先级，取值为 低：1（默认），中:2，高：3
};

var notification = {
    onMessageAttached: function(message) {
    }
}

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

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

Copied!

接收 @ 消息

接收 @ 消息的回调接口与接收普通消息的回调接口一致，请参考收发普通消息 - 接收消息了解具体接口。

收到消息后，开发者可根据业务逻辑实现对应的功能，如高亮等。

说明

仅 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 。

Untitled

zim.on('conversationChanged', function (zim, { info }) {
    console.log(info.mentionInfoList);
});

Copied!

主动获取

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

Untitled

var mentionedInfoList = conversaion.mentionedInfoList;

Copied!

清除会话的 mentionedInfoList

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

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

clearConversationUnreadMessageCount ：清除单个会话消息未读数，调用示例请参考会话管理 - 清除单个会话消息未读数。
clearConversationTotalUnreadMessageCount ：清除全部会话消息未读数，调用示例请参考会话管理 - 清除全部会话消息未读数。

获取被提醒用户列表

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

Untitled

var userIds = message.mentionedUserIDs;

Copied!

确认是否为全员提醒

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

Untitled

var isMentionAll = message.isMentionAll;

Copied!

收发全员推送消息

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

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

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

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

说明

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

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

示例代码：

Untitled

// 用户接收全员推送消息
zim.on('broadcastMessageReceived', function (zim, { message }) {
    console.log(message);
});

Copied!

转发消息

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

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

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

接收 Tips 消息

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

监听消息状态

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

Untitled

// 监听消息状态
zim.on('messageSentStatusChanged', function (zim, { infos }) {
    infos.forEach( function (info) {
        console.warn(info.message, info.status);
    });  
});

Copied!