消息

消息是客户端集成中最重要的功能之一，WebIM 消息的使用方法主要为：

构造消息

发送消息

接受消息

处理消息

历史消息

新消息提醒

消息回执

通过对消息的集成，您可以最快速的集成体验 IM 收发消息的流畅体验。

var msg = new WebIM.message('txt', id);
msg.set(option);             //消息内容option，下面会有详细介绍
msg.setGroup('groupchat');   //用于设置当前聊天模式为多人聊天，如聊天室/群组。单聊不调用此方法

环信支持向单聊、群组及聊天室中发送：

文本消息

表情消息

贴图消息

命令消息

附件消息

自定义消息

多样化的消息类型，覆盖多种场景下的消息需求。

发送文本消息（单聊）

单聊发送文本消息示例如下：

// 单聊发送文本消息
var sendPrivateText = function () {
    var id = conn.getUniqueId();                 // 生成本地消息id
    var msg = new WebIM.message('txt', id);      // 创建文本消息
    msg.set({
        msg: 'message content',                  // 消息内容
        to: 'username',                          // 接收消息对象（用户id）
        roomType: false, 
        ext: {},                                 // 扩展消息                         
        success: function (id, serverMsgId) {
            console.log('send private text Success');  
        },                                       // 对成功的相关定义，sdk会将消息id登记到日志进行备份处理
        fail: function(e){
            console.log("Send private text error");  
        }                                        // 对失败的相关定义，sdk会将消息id登记到日志进行备份处理
    });
    conn.send(msg.body);
};

发送文本消息（群组）

群组发送文本消息示例如下：

// 群组发送文本消息
var sendGroupText = function () {
    var id = conn.getUniqueId();            // 生成本地消息id
    var msg = new WebIM.message('txt', id); // 创建文本消息
    var option = {
        msg: 'message content',             // 消息内容
        to: 'group id',                     // 接收消息对象(群组id)
        roomType: false,                    // 群聊类型，true时为聊天室，false时为群组
        ext: {},                            // 扩展消息
        success: function () {
            console.log('send room text success');
        },                                  // 对成功的相关定义，sdk会将消息id登记到日志进行备份处理
        fail: function () {
            console.log('failed');
        }                                   // 对失败的相关定义，sdk会将消息id登记到日志进行备份处理
    };
    msg.set(option);
    msg.setGroup('groupchat');              // 群聊类型
    conn.send(msg.body);
};

发送文本消息（聊天室）

聊天室发送文本消息示例如下：

// 聊天室发送文本消息
var sendRoomText = function () {
    var id = conn.getUniqueId();         // 生成本地消息id
    var msg = new WebIM.message('txt', id); // 创建文本消息
    var option = {
        msg: 'message content',          // 消息内容
        to: 'chatroom id',               // 接收消息对象(聊天室id)
        roomType: true,                  // 群聊类型，true时为聊天室，false时为群组
        ext: {},                         // 扩展消息
        success: function () {
            console.log('send room text success');
        },                               // 对成功的相关定义，sdk会将消息id登记到日志进行备份处理
        fail: function () {
            console.log('failed');
        }                                // 对失败的相关定义，sdk会将消息id登记到日志进行备份处理
    };
    msg.set(option);
    msg.setGroup('groupchat');           // 群聊类型
    conn.send(msg.body);
};

注意：单聊和群聊的表现示例基本一样，区别在于

接受消息的对象不同，单聊 to 的对象为用户 ID ,群组/聊天室 to 的对象为群组/聊天室 ID

聊天室/群组比单聊代码中调一个方法 msg.setGroup('groupchat')

通过roomType区分聊天室、群组，true为聊天室，false为群组

API

示例中使用到的 API

getUniqueId

send

发送表情消息

发送表情同发送文本消息，需要在对方客户端将表情文本进行解析成图片。

示例代码为单聊，贴图发送至群组和聊天室时需参考发送文本消息修改roomType和msg.setGroup('groupchat')。

单聊发送表情消息的代码示例如下：

conn.listen({
    onEmojiMessage: function (message) {
        console.log('Emoji');
        var data = message.data;
        for(var i = 0 , l = data.length ; i < l ; i++){
            console.log(data[i]);
        }
    },   //收到表情消息
});
// 单聊发送文本消息
var sendPrivateText = function () {
    var id = conn.getUniqueId();                 // 生成本地消息id
    var msg = new WebIM.message('txt', id);      // 创建文本消息
    msg.set({
        msg: 'message content',                  // 消息内容
        to: 'username',                          // 接收消息对象（用户id）
        roomType: false,
        ext: {},                                 // 扩展消息
        success: function (id, serverMsgId) {
            console.log('send private text Success');
        },
        fail: function(e){
            console.log("Send private text error");
        }
    });
    conn.send(msg.body);
};

注意：当为 WebIM 添加了 Emoji 属性后，若发送的消息含 WebIM.Emoji 里特定的字符串，connection 就会自动将这些字符串和其它文字按顺序组合成一个数组，每一个数组元素的结构为 {type:'emoji(或者txt)',data:''}

当 type='emoji' 时，data 表示表情图像的路径；

当 type='txt' 时，data 表示文本消息。

API

示例中使用到的 API

listen

getUniqueId

send

发送贴图消息

Web IM SDK本身不支持截图，使用下述代码可以实现用户粘贴图片至输入框后发送。

示例代码为单聊，贴图发送至群组和聊天室时需参考发送文本消息修改roomType和msg.setGroup('groupchat')。

单聊发送贴图消息的代码示例如下：

// 单聊贴图发送
document.addEventListener('paste', function (e) {
    if (e.clipboardData && e.clipboardData.types) {
        if (e.clipboardData.items.length > 0) {
            if (/^image\/\w+$/.test(e.clipboardData.items[0].type)) {
                var blob = e.clipboardData.items[0].getAsFile();
                var url = window.URL.createObjectURL(blob);
                var id = conn.getUniqueId();             // 生成本地消息id
                var msg = new WebIM.message('img', id);  // 创建图片消息
                msg.set({
                    apiUrl: WebIM.config.apiURL,
                    file: {data: blob, url: url},
                    to: 'username',                      // 接收消息对象
                    roomType: false,
                    ext: {},                             // 扩展消息
                    onFileUploadError: function (error) {
                        console.log('Error');
                    },
                    onFileUploadComplete: function (data) {
                        console.log('Complete');
                    },
                    success: function (id) {
                        console.log('Success');
                    }
                });
                conn.send(msg.body);
            }
        }
    }
});

API

示例中使用到的 API

getUniqueId

send

发送命令消息

发送命令消息的代码示例如下：

var id = conn.getUniqueId();            //生成本地消息id
var msg = new WebIM.message('cmd', id); //创建命令消息

msg.set({
  msg: 'msg',
  to: 'username',                       //接收消息对象
  action : 'action'                     //用户自定义，cmd消息必填
  ext :{'extmsg':'extends messages'}    //用户自扩展的消息内容（群聊用法相同）
  success: function ( id，serverMsgId ) {}//消息发送成功回调   
}); 

if ( /*如果是发送到群组*/ ) { 
  msg.setGroup('groupchat');
} else if ( /*如果是发送到聊天室*/ ) {
  msg.body.roomType = true;
  msg.setGroup('groupchat');
}   

conn.send(msg.body);

API

示例中使用到的 API

getUniqueId

send

发送附件消息

附件消息是消息中重要的消息类型，附件消息主要包括以下几种：

图片消息

文件消息

音频消息

视频消息

· 发送附件消息，SDK 自动分两步完成：

上传附件到服务器，并得到服务返回的附件信息等；
发送附件消息，消息体包含附件的基本信息、服务器路径、secret 等。

· 示例代码为单聊，贴图发送至群组和聊天室时需参考发送文本消息修改roomType和msg.setGroup('groupchat')。

单聊发送图片消息示例如下：

// 单聊发送图片消息
upLoadImage(res){
    var me = this;
    var tempFilePaths = res.tempFilePaths;
    var token = WebIM.conn.context.accessToken
    wx.getImageInfo({
        src: res.tempFilePaths[0],
        success(res){
	    var allowType = {
		jpg: true,
		gif: true,
		png: true,
		bmp: true
	    };
	    var str = WebIM.config.appkey.split("#");
	    var width = res.width;
	    var height = res.height;
	    var index = res.path.lastIndexOf(".");
	    var filetype = (~index && res.path.slice(index + 1)) || "";
	    if(filetype.toLowerCase() in allowType){
		wx.uploadFile({
		    url: "https://a1.easemob.com/" + str[0] + "/" + str[1] + "/chatfiles",
		    filePath: tempFilePaths[0],
		    name: "file",
		    header: {
		        "Content-Type": "multipart/form-data",
		        Authorization: "Bearer " + token
		    },
		    success(res){
		        var data = res.data;
		        var dataObj = JSON.parse(data);
		        var id = WebIM.conn.getUniqueId();	// 生成本地消息 id
		        var msg = new WebIM.message(msgType.IMAGE, id);
		        var file = {
			    type: msgType.IMAGE,
			    size: {
			        width: width,
			        height: height
			    },
		            url: dataObj.uri + "/" + dataObj.entities[0].uuid,
			    filetype: filetype,
			    filename: tempFilePaths[0]
		        };
		        msg.set({
			    apiUrl: WebIM.config.apiURL,
		            body: file,
			    from: me.data.username.myName,
			    to: me.getSendToParam(),
			    roomType: false,
			    chatType: me.data.chatType,
			    success: function (argument) {
			        disp.fire('em.chat.sendSuccess', id);
			    }
		        });
		        if(me.data.chatType == msgType.chatType.CHAT_ROOM){
			    msg.setGroup("groupchat");
		        }
		        WebIM.conn.send(msg.body);
		    }
	        });
	    }
        }
    });
}

单聊发送文件消息示例如下：

// 单聊发送文件消息
uploadRecord(tempFilePath){
    var str = WebIM.config.appkey.split("#");
    var me = this;
    var token = WebIM.conn.context.accessToken
    wx.uploadFile({
        url: "https://a1.easemob.com/" + str[0] + "/" + str[1] + "/chatfiles",
        filePath: tempFilePath,
        name: "file",
        header: {
            "Content-Type": "multipart/form-data",
            Authorization: "Bearer " + token
        },
        success(res){
            var id = WebIM.conn.getUniqueId();
            var msg = new WebIM.message(msgType.AUDIO, id);
            var dataObj = JSON.parse(res.data);
            msg.set({
                apiUrl: WebIM.config.apiURL,
                accessToken: token,
                body: {
                    type: msgType.FILE,
                    url: dataObj.uri + "/" + dataObj.entities[0].uuid,
                    filetype: "",
                    filename: tempFilePath,
                    accessToken: token,
                    length: ""
                },
                from: me.data.username.myName,
                to: me.getSendToParam(),
                roomType: false,
                chatType: me.data.chatType,
                success: function (argument) {
                    disp.fire('em.chat.sendSuccess', id);
                }
           });
           if(me.isGroupChat()){
               msg.setGroup("groupchat");
           }
           msg.body.length = "";
           WebIM.conn.send(msg.body);
       }
   });
};

单聊发送音频消息示例如下：

// 单聊发送音频消息
uploadRecord(tempFilePath, dur){
    var str = WebIM.config.appkey.split("#");
    var me = this;
    var token = WebIM.conn.context.accessToken
    wx.uploadFile({
        url: "https://a1.easemob.com/" + str[0] + "/" + str[1] + "/chatfiles",
        filePath: tempFilePath,
        name: "file",
        header: {
            "Content-Type": "multipart/form-data",
            Authorization: "Bearer " + token
        },
        success(res){
            var id = WebIM.conn.getUniqueId();
            var msg = new WebIM.message(msgType.AUDIO, id);
            var dataObj = JSON.parse(res.data);
            msg.set({
                apiUrl: WebIM.config.apiURL,
                accessToken: token,
                body: {
                    type: msgType.AUDIO,
                    url: dataObj.uri + "/" + dataObj.entities[0].uuid,
                    filetype: "",
                    filename: tempFilePath,
                    accessToken: token,
                    length: Math.ceil(dur / 1000)
                },
                from: me.data.username.myName,
                to: me.getSendToParam(),
                roomType: false,
                chatType: me.data.chatType,
                success: function (argument) {
                    disp.fire('em.chat.sendSuccess', id);
                }
           });
           if(me.isGroupChat()){
               msg.setGroup("groupchat");
           }
           msg.body.length = Math.ceil(dur / 1000);
           //console.log('发送的语音消息', msg.body)
           WebIM.conn.send(msg.body);
       }
   });
};

API

示例中使用到的 API

getUniqueId

send

发送自定义消息

单聊发送自定义消息示例如下：

var sendCustomMsg = function () {
    var id = conn.getUniqueId();                 // 生成本地消息id
    var msg = new WebIM.message('custom', id);   // 创建自定义消息
    var customEvent = "customEvent";             // 创建自定义事件
    var params = {};                             // 消息内容
    var customExts = {};                         // 消息扩展
    msg.set({
        to: 'username',                          // 接收消息对象（用户id）
        customEvent,
        customExts,
        params,
        roomType: false,
        success: function (id, serverMsgId) {},
        fail: function(e){}
    });
    conn.send(msg.body);
};

API

示例中使用到的 API

getUniqueId

send

SDK增值服务。

/**
 * 发送撤回消息
  * @param {Object} option - 
 * @param {Object} option.mid -   回撤消息id
 * @param {Object} option.to -   消息的接收方
 * @param {Object} option.type -  chat(单聊) groupchat(群组) chatroom(聊天室)
 */
WebIM.conn.recallMessage(option)

查看回调函数，接收各类消息的回调函数代码如下：

conn.listen({
    onOpened: function ( message ) {          //连接成功回调
    },  
    onClosed: function ( message ) {},         //连接关闭回调
    onTextMessage: function ( message ) {},    //收到文本消息
    onEmojiMessage: function ( message ) {},   //收到表情消息
    onPictureMessage: function ( message ) {}, //收到图片消息
    onCmdMessage: function ( message ) {},     //收到命令消息
    onAudioMessage: function ( message ) {},   //收到音频消息
    onLocationMessage: function ( message ) {},//收到位置消息
    onFileMessage: function ( message ) {},    //收到文件消息
    onCustomMessage: function ( message ) {},  //收到自定义消息
    onVideoMessage: function (message) {
        var node = document.getElementById('privateVideo');
        var option = {
            url: message.url,
            headers: {
              'Accept': 'audio/mp4'
            },
            onFileDownloadComplete: function (response) {
                var objectURL = WebIM.utils.parseDownloadResponse.call(conn, response);
                node.src = objectURL;
            },
            onFileDownloadError: function () {
                console.log('File down load error.')
            }
        };
        WebIM.utils.download.call(conn, option);
    },   //收到视频消息
    onPresence: function ( message ) {},       //处理“广播”或“发布-订阅”消息，如联系人订阅请求、处理群组、聊天室被踢解散等消息
    onRoster: function ( message ) {},         //处理好友申请
    onInviteMessage: function ( message ) {},  //处理群组邀请
    onOnline: function () {},                  //本机网络连接成功
    onOffline: function () {},                 //本机网络掉线
    onError: function ( message ) {},          //失败回调
    onBlacklistUpdate: function (list) {       //黑名单变动
        // 查询黑名单，将好友拉黑，将好友从黑名单移除都会回调这个函数，list则是黑名单现有的所有好友信息
        console.log(list);
    },
    onReceivedMessage: function(message){},    //收到消息送达服务器回执
    onDeliveredMessage: function(message){},   //收到消息送达客户端回执
    onReadMessage: function(message){},        //收到消息已读回执
    onCreateGroup: function(message){},        //创建群组成功回执（需调用createGroupNew）
    onMutedMessage: function(message){}        //如果用户在A群组被禁言，在A群发消息会走这个回调并且消息不会传递给群其它成员
});

API

示例中使用到的 API

listen

这里主要介绍几种特殊的消息处理示例

表情消息

图片消息

音频消息

表情消息

收到表情消息的处理示例：

conn.listen({
    onEmojiMessage: function (message) {
        console.log('Emoji');
        var data = message.data;
        for(var i = 0 , l = data.length ; i < l ; i++){
            console.log(data[i]);
        }
    },   //收到表情消息
});

注意：当为 WebIM 添加了 Emoji 属性后，若发送的消息含 WebIM.Emoji 里特定的字符串，connection 就会自动将这些字符串和其它文字按顺序组合成一个数组，每一个数组元素的结构为 {type:'emoji(或者txt)',data:''}

当 type='emoji' 时，data 表示表情图像的路径；

当 type='txt' 时，data 表示文本消息。

图片消息

收到图片消息的处理示例：

conn.listen({
    onPictureMessage: function (message) {
        console.log("Location of Picture is ", message.url);
    }, //收到图片消息
});

音频消息

收到音频消息的处理示例：

conn.listen({
  onAudioMessage: function ( message ) {
    var options = { url: message.url };
    
    options.onFileDownloadComplete = function ( response ) { 
      //音频下载成功，需要将response转换成blob，使用objectURL作为audio标签的src即可播放。
      var objectURL = WebIM.utils.parseDownloadResponse.call(Demo.conn, response);
    };  

    options.onFileDownloadError = function () {
      //音频下载失败 
    };  

    //通知服务器将音频转为mp3
    options.headers = { 
      'Accept': 'audio/mp3'
    };

    WebIM.utils.download.call(conn, options);
  }
})

注意：

conn.listen() 中注册不同消息接收 handler 之后，可自行解析消息体，定位聊天好友，并追加到与其聊天窗口。具体参考 http://webim.easemob.com 效果。

对于图片、语音消息需要先进行下载，然后进行显示或者播放处理。

API

示例中使用到的 API

listen

SDK 在收到新消息时会直接转发给登录用户，接收到消息后，Demo 中会在好友或者群组的后面显示红色消息数，具体样式开发者可自行处理。

已送达回执：在 webim.config.js 中配置 delivery 为 true ，在收到消息时会自动发送已送达回执，对方收到已送达回执的回调函数是 onDeliveredMessage

已读回执：当认为用户已读某条（些）消息时，可以生成已读回执，再进行发送

对方收到已送达回执的回调函数是 onReadMessage

var bodyId = message.id;         // 需要发送已读回执的消息id
var msg = new WebIM.message('read', msgId);
msg.set({
    id: bodyId
    ,to: message.from
});
Demo.conn.send(msg.body);

API

示例中使用到的 API

send

上一页：微信小程序SDK更新日志

下一页：好友管理

消息

构造消息

发送消息

发送文本消息（单聊）

发送文本消息（群组）

发送文本消息（聊天室）

API

发送表情消息

API

发送贴图消息

API

发送命令消息

API

发送附件消息

API

发送自定义消息

API

消息撤回

接收消息

API

处理消息

表情消息

图片消息

音频消息

API

新消息提示

消息回执

API