收发消息

功能简介

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

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

消息类型

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

前提条件

在实现“收发消息”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

• 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。

• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “3 集成 SDK”。

收发普通消息

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

发送消息

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

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

发送消息

// 发送单聊 `Text` 信息

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

var messageTextObj = { type: 1, message: '文本消息内容', extendedData: '消息的扩展信息（可选）' };
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    }
}

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

接收消息

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

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

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

收发富媒体消息

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

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

发送富媒体消息

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

// 发送“本地文件”富媒体消息示例 - 单聊

var conversationID = 'xxxx';
var config = { priority: 1 };
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    },
    onMediaUploadingProgress: function(message, currentFileSize, totalFileSize) {
        // todo: upload progress
    }
};

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

    // 如果是 `图片` 消息
    var mediaMessageObj = {
        fileLocalPath: file,
        type: 11,
    };
    // 如果是 `文件` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 12,
    };
    // 如果是 `音频` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 13,
        audioDuration: 100, // 请填写音频文件播放时长，单位秒（必填）
    };
    // 如果是 `视频` 消息
    mediaMessageObj = {
        fileLocalPath: file,
        type: 14,
        videoDuration: 100, // 请填写视频文件播放时长，单位秒（必填）
    };

    zim.sendMediaMessage(
        mediaMessageObj,
        conversationID,
        0,
        config,
        notification,
    );  
}

// Web: 选择本地文件
var input = document.createElement('input');
input.type = 'file';
input.onchange = function() {
    sendMediaMessage(this.files[0]);
}

// 小程序: 拍摄或从手机相册中选择图片或视频
// 请参考小程序官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseMedia.html
wx.chooseMedia({
    count: 1,
    success(res) {
        sendMediaMessage(res.tempFiles[0].tempFilePath);
    }
})

// 小程序: 从微信客户端会话选择文件
// 请参考小程序官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/media/image/wx.chooseMessageFile.html
wx.chooseMessageFile({
    count: 1,
    success(res) {
        sendMediaMessage(res.tempFiles[0].path);
    }
})

// 发送“网络文件”富媒体消息示例 - 单聊
/* 发送网络文件消息时，ZIM SDK 仅透传相关字段到后台，ZIM 后台不会保存网络文件 */

var conversationID = 'xxxx';
var config = { priority: 1 };
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    },
    onMediaUploadingProgress: function(message, currentFileSize, totalFileSize) {
        // todo: upload progress
    }
};

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

// 如果是 `图片` 消息
var mediaMessageObj = {
    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.sendMediaMessage(
    mediaMessageObj,
    conversationID,
    0,
    config,
    notification,
);

if (navigator.mediaDevices) {
    console.log('getUserMedia supported.');

    var startTime = Date.now();
    var constraints = { audio: true };
    var chunks = [];

    navigator.mediaDevices
        .getUserMedia(constraints)
        .then((stream) => {
            var mediaRecorder = new MediaRecorder(stream);

            mediaRecorder.onstop = function (e) {
                // 录制结束后，发送音频消息
                var conversationID = 'xxxx';
                var config = { priority: 1 };
                var notification = {
                    onMessageAttached: function(message) {
                        // todo: Loading
                    },
                    onMediaUploadingProgress: function(message, currentFileSize, totalFileSize) {
                        // todo: upload progress
                    }
                };

                var audioDuration = Date.now() - startTime;
                var mediaMessageObj = {
                    fileLocalPath: new File(chunks, '文件名xxxx.mp3'),
                    type: 13,
                    audioDuration: audioDuration > 0 ? audioDuration : 100, // 请填写音频文件播放时长，单位秒（必填）
                };

                zim.sendMediaMessage(mediaMessageObj, conversationID, 0, config, notification)
                    .then((res) => {
                        // 发送成功
                    })
                    .catch((err) => {
                        // 发送失败
                    });

                // 重置 chunks  
                chunks = [];
            };

            mediaRecorder.ondataavailable = function (e) {
                chunks.push(e.data);
            };
        })
        .catch((err) => {
            console.log('The following error occured: ' + err);
        });
}

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

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

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

其中：

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

接收富媒体消息

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

收发信令消息

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

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

发送信令消息

// 发送单聊 `Command` 信息

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

// 这里以 JSON 字符串 为例，需要将字符串转换为 Uint8Array
// receivePeerMessage 收到 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 };
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    }
}
zim.sendMessage(messageCommandObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // 发送成功
    })
    .catch(function (err) {
        // 发送失败
    });

接收信令消息

// 用户接收信令消息
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log(messageList, 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('receivePeerMessage', jsonObj);
        }
    })
});

收发自定义消息

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

发送自定义消息

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

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

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

// 发送自定义信息
// 指定用户的 ID
var toConversationID = "xxxx";
var message = "";  // 自定义消息的文本内容
var subType = 100;  // 具体的自定义类型
var searchedContent = "";// 自定义消息的检索字段。

var zimCustomMessage = {
    type: 200,
    message: message,
    subType: subType,
    searchedContent: searchedContent
};

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

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

接收自定义消息

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

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

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

收发 @ 消息

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

发送 @ 消息

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

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

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

var messageTextObj = { type: 1, message: '文本消息内容', extendedData: '消息的扩展信息（可选）' };

// 调用接口提醒列表中用户查看消息
message.mentionedUserIDs = ["userId1", "userId2"];

// 提醒会话内所有其他用户查看消息
message.isMentionAll = true;

var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    }
}

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

接收 @ 消息

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

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

获取 mentionedInfoList

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

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

被动获取

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

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

主动获取

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

var mentionedInfoList = conversaion.mentionedInfoList;

清除会话的 mentionedInfoList

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

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

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

获取提醒用户列表

会话内所有用户都可以通过 ZIMMessage 的 mentionedUserIDs 参数获取具体提醒用户列表，可此接口仅能返回 @ 消息发送用户通过 ZIMMessage 的 mentionedUserIDs 参数传入的用户列表。

var userIds = message.mentionedUserIDs;

确认是否为全员提醒

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

var isMentionAll = message.isMentionAll;

收发全员推送消息

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

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

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

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

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

示例代码：

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

转发消息

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

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

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

接收 Tips 消息

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

监听消息状态

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

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