网易云信即时通讯 Web 版 SDK（以下简称 NIM SDK）支持收发多种消息类型，助您快速实现多样化的消息业务场景。本文介绍通过网易云信 NIM SDK 实现消息收发的技术原理、前提条件以及具体的实现流程。

消息类型

NIM SDK 支持的消息类型包括文本消息、文件（包括音视、视频、图片等）消息、地理位置消息、提示消息、通知消息、和自定义消息。SDK 中定义消息对象的结构为 NIMMessage，相同类型的消息，通过在调用相应类型的消息发送接口时配置 scene 参数进行区分，该参数值配置为 p2p 时表示为单聊消息，为 team 时表示为群聊消息，为 superTeam 时表示为超大群消息。

使用限制

发送消息的方法调用均存在频控，一分钟内默认最多可调用 300 次。

前提条件

在实现消息收发之前，请确保：

• 已集成 SDK。
• 已 注册 IM 账号，获取账号 ID（accid）和凭证（Token）。
• 已了解各消息类型的 使用限制。
• 已创建群组（如果需要发送群消息）。

初始化配置

在收发送消息前，用户需要在初始化时按需完成消息相关参数配置。例如，为了保证能接收到消息，必须注册 onmsg 回调来监听消息接收。

以下仅列出于消息强相关的初始化参数，完整的初始化参数参考 NIMGetInstanceOptions。

JavaScriptvar nim = NIM.getInstance({
    onroamingmsgs: onRoamingMsgs,
    onofflinemsgs: onOfflineMsgs,
    onmsg: onMsg
});
function onRoamingMsgs(obj) {
    console.log('收到漫游消息', obj);
    pushMsg(obj.msgs);
}
function onOfflineMsgs(obj) {
    console.log('收到离线消息', obj);
    pushMsg(obj.msgs);
}
function onMsg(msg) {
    console.log('收到消息', msg.scene, msg.type, msg);
    pushMsg(msg);
    switch (msg.type) {
    case 'custom':
        /**
         * 收到自定义消息，用户根据消息内容处理
         */
        break;
    case 'notification':
        /**
         * 收到群通知消息，用户根据群通知的消息进行进一步处理
         */
        break;
    // 其它 case
    default:
        break;
    }
}

function pushMsg(msgs) {
    if (!Array.isArray(msgs)) { msgs = [msgs]; }
    var sessionId = msgs[0].scene + '-' + msgs[0].account;
    data.msgs = data.msgs || {};
    data.msgs[sessionId] = nim.mergeMsgs(data.msgs[sessionId], msgs);
}

收发文本消息

API 调用时序

sequenceDiagram

发送方 ->> NIM SDK: 初始化
接收方 ->> NIM SDK: 初始化
note left of 接收方 : 初始化时注册 onmsg 回调<br> 监听消息到达事件
发送方 ->> NIM SDK: 登录
接收方 ->> NIM SDK: 登录
发送方 ->> NIM SDK: 发送文本消息<br>(sendText)
NIM SDK ->> 接收方: NIMMessage

具体说明

1. 接收方在进行 SDK 初始化时，注册 onmsg 回调实现对消息接收事件的监听。

2. 发送方调用 sendText 方法发送一条文本消息。

   消息是否存入云端（isHistoryable）、写入漫游（isRoamingable）、计入未读数（isUnreadable）等配置选项说明，请参考 消息配置选项。

   示例代码如下：

   JavaScriptvar msg = nim.sendText({
       scene: 'p2p',
       to: 'account',
       text: 'hello',
       done: sendMsgDone
   });
   console.log('正在发送 p2p text 消息, id=' + msg.idClient);
   pushMsg(msg); // pushMsg 需要用户自己实现，将消息压入到自己的数据中
   function sendMsgDone(error, msg) {
       console.log(error);
       console.log(msg);
       console.log('发送' + msg.scene + ' ' + msg.type + '消息' + (!error?'成功':'失败') + ', id=' + msg.idClient);
       pushMsg(msg);
   }
   

3. SDK 触发 onmsg 回调，接收方通过该回调收到消息。

收发文件消息

文件消息可附带的文件类型包括图片、音频、视频和普通文件，它们的区别在于具体的文件信息不一样。文件信息在消息对象的 file 字段内定义。

文件对象类型

实现流程

您可通过两种方式发送文件消息，直接发送 或者 先上传文件再发送。

sequenceDiagram

发送方 ->> NIM SDK: 初始化 SDK
接收方 ->> NIM SDK: 初始化 SDK
note left of 接收方 : 初始化时注册 onmsg 回调<br> 监听消息到达事件
发送方 ->> NIM SDK: 登录
接收方 ->> NIM SDK: 登录
发送方 ->> NIM SDK: 发送文件消息<br>(sendFile)
NIM SDK ->> 接收方: NIMMessage

sequenceDiagram

发送方 ->> NIM SDK: 初始化 SDK
接收方 ->> NIM SDK: 初始化 SDK
note left of 接收方 : 初始化时注册 onmsg 回调<br> 监听消息到达事件
发送方 ->> NIM SDK: 登录
接收方 ->> NIM SDK: 登录
发送方 ->> NIM SDK: 上传文件(previewFile)
发送方 ->> NIM SDK: 发送文件消息(sendFile)
NIM SDK ->> 接收方: NIMMessage

收发地理位置消息

当发送地理位置消息或收到地理位置消息时, 消息对象（NIMMessage）的 geo 字段代表地理位置对象, 包含以下属性:

API 调用时序

sequenceDiagram

发送方 ->> NIM SDK: 初始化
接收方 ->> NIM SDK: 初始化
note left of 接收方 : 初始化时注册 onmsg 回调<br> 监听消息到达事件
发送方 ->> NIM SDK: 登录
接收方 ->> NIM SDK: 登录
发送方 ->> NIM SDK: 发送地理位置消息<br>(sendGeo)
NIM SDK ->> 接收方: NIMMessage

具体说明

1. 接收方在进行 SDK 初始化时，注册 onmsg 回调实现对消息接收事件的监听。

2. 发送方调用 sendGeo 发送地理位置消息。

   消息是否存入云端（isHistoryable）、写入漫游（isRoamingable）、计入未读数（isUnreadable）等配置选项说明，请参考 消息配置选项。

   示例代码如下：

   JavaScriptvar msg = nim.sendGeo({
       scene: 'p2p',
       to: 'account',
       geo: {
           lng: 116.3833,
           lat: 39.9167,
           title: 'Beijing'
       },
       done: sendMsgDone
   });
   console.log('正在发送 p2p geo 消息, id=' + msg.idClient);
   pushMsg(msg); // pushMsg 需要用户自己实现，将消息压入到自己的数据中
   
   

3. onmsg 回调触发，接收方通过该回调收到消息。

收发提示消息

提示消息（又叫做 Tip 消息）主要用于会话内的通知提醒，典型使用场景包括 进入群组时出现的欢迎消息 和 会话过程中命中敏感词后的提示 等。

调用 sendTipMsg 发送提示消息。

示例代码如下：

JavaScriptvar msg = nim.sendTipMsg({
    scene: 'p2p',
    to: 'account',
    tip: 'tip content',
    done: sendMsgDone
});
console.log('正在发送 p2p 提醒消息, id=' + msg.idClient);
pushMsg(msg); // pushMsg 需要用户自己实现，将消息压入到自己的数据中

接收通知消息

一些特定场景的行为，网易云信服务端预置了一些系统通知消息。通知消息也是一种特定消息，开发者需解析消息中附带的信息，来获取通知内容。如最常见的通知消息：群通知事件，如有新成员进群，则群内已有成员将收到此通知消息。

通知消息属于会话内的一种消息，其对应的数据结构为 NIMMessage，消息类型为 type.notification。目前用于群通知。

收发自定义消息

调用 sendCustomMsg 发送自定义消息。

在网易云信开放的 旧版 web-demo 源码 中，type-1 为 [石头剪刀布]，type-2 为 [阅后即焚]，type-3 为 [贴图表情]，type-4 为 [白板教学]。如下代码用自定义消息实现了 石头剪刀布 游戏：

JavaScriptvar value = Math.ceil(Math.random()*3);
var content = {
    type: 1,
    data: {
        value: value
    }
};
var msg = nim.sendCustomMsg({
    scene: 'p2p',
    to: 'account',
    content: JSON.stringify(content),
    done: sendMsgDone
});
console.log('正在发送 p2p 自定义消息, id=' + msg.idClient);
pushMsg(msg); // pushMsg 需要用户自己实现，将消息压入到自己的数据中

API 参考

公共参数

所有发送消息的 SDK API 都有如下参数。

常见问题

发送消息后怎么获取消息内容

在发送消息接口的 done 回调中返回 NIMMessage 对象。可以通过 flow 属性获取消息方向，通过 to 属性获取聊天对象的 accid/群组 ID，通过 text 属性获取文本消息的内容，通过 file 属性获取文件消息的文件对象，通过 status 属性获取消息发送状态，通过 time 属性获取消息时间戳。

如何判断消息发送成功

在消息发送的 done 回调中根据消息对象的 status 字段和 error 对象来确定消息的发送状态。如果 status 为 success，error 为空则表示消息发送成功。

如何设置消息的扩展字段

单聊或群聊消息具有服务端扩展字段和客户端扩展字段。服务端扩展字段只能在消息发送前设置，会同步到其他端。客户端扩展字段在消息发送前后设置均可，不会同步到其他端。

具体方法如下：