Interface MessageInterface

示例场景

• 单向删除消息

将消息转发至其它会话中

注: 该接口直接返回的是 sending 状态的未完成 message，发送完毕的消息体需要传递 options.done 获得。

影响范围

调用该 API 发送触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

示例场景

• 已读回执-群

• 对应于群组消息发送时配置了needMsgReceipt字段的群组消息，接收方可以对消息发送已读回执
• done 回调的第二个参数是发送的参数，用于校验，第三个参数才是实际的结果
• 在支持db，且存在idClient时：
  • 查询完成后，db中对应的msg会拥有 read和unread属性，分别对应消息的已读未读人数
  • unread为 0 后，消息的已读、未读数量便不会再变化了，因此建议在调用该接口前，过滤掉unread已为0的消息，减少不必要的性能消耗

示例场景

• 已读回执-群

撤回消息。

使用场景

消息发送后的可撤回时长（默认 2 分钟，可在云信控制台配置）内，发送方撤回已发送的单聊消息或者群消息。

• 单聊场景下，发送方撤回之后，对应的离线消息、漫游消息和历史消息将被删除，消息接收方会收到一条类型为 deleteMsg 的系统通知。
• 群聊场景下, 所有群成员都会收到类型为 deleteMsg 的系统通知。
• 如果发送方同时在多个端登录了同一个 IM 账号, 那么其它端也会收到类型为 deleteMsg 的系统通知。

注意

单聊和群聊消息的撤回功能存在些许区别：

• 单聊：用户只能撤回自己发送的消息。
• 群聊：普通成员只能撤回自己发送的消息。管理员可撤回其他群成员的消息。

使用限制

• 如果消息发送失败或者消息发送者被拉黑，那么即使在可撤回时长内也无法撤回。
• 消息撤回后，无论是发送方还是接收方，都无法在历史消息、漫游消息或者离线消息的接口返回中，查到该消息。
• 以下情况下，消息撤回会失败：消息为空、消息没有发送成功、消息超过撤回时限，或者消息被反垃圾（内容审核）命中时。

关联函数

• NIMGetInstanceOptions.onsysmsg
• NIMGetInstanceOptions.onupdatesessions

示例场景

• 撤回消息

当 SDK 提供的能力无法满足您的业务需求时，调用该 API 进行个性化定制并在单聊和群聊场景（包括群组和超大群）中发送，例如石头剪刀布和投骰子功能。

注意

该接口直接返回的是 sending 状态的未完成消息体，发送完毕的消息体需要传递 options.done 获得。

影响范围

调用该 API 可触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

示例场景

• 内容审核
• 发送表情

示例

nim.sendCustomMsg({
  scene: 'p2p',
  to: 'account',
  //接收方通过onMsg接收消息
  //然后如果msg.type === 'custom'，接收方通过读取msg.content，然后调用业务代码
  content: JSON.stringify({type: 1}),
  done: function(err, msg) {
     if (err) {
        console.log('发送失败', err)
     } else {
        console.log('发送消息成功，消息为: ', msg)
     }
  }
})

注意一

• 自版本 v8.9.102 和 v9.7.0+ 开始，该接口直接返回的是 sending 状态的未完成消息体，发送完毕的消息体需要传递 options.done 获得。

注意二

• fileInput、file、blob、filePath四个参数选择一个传入
• fileInput: type='file'类型的input DOM元素的id。上传完成前请不要操作此节点上的文件
• file: previewFile 回调函数的参数
• blob: Blob类型JS对象
• filePath: RN，小程序等特殊的 JS 运行环境专用（chooseImage 拿到的该临时路径）

注意三

• type: image、audio、video 或 file。默认为 file。主要区别在于消息体中 file 对象含有的信息不同
• image: url, name, size, ext, w, h, type
• audio: url, name, size, ext, container, dur
• video: url, name, size, ext, container, dur, w, h
• file: url, name, size, ext

影响范围

调用该 API 可触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

直接发送文件 & 重发文件

nim.sendFile({
  scene: 'p2p',
  to: 'account',
  type: 'image',
  fileInput: 'domId',
  done: function(err, obj) {
     if (err) {
        console.log('发送失败', err)
        // 重发. 当上传文件失败时 obj 参数的 msg 附带消息体，其他情况的 obj 就是消息体。
        setTimeout(function () {
          resendMessage(obj.msg ? obj.msg : obj)
        }, 3000)
     } else {
        console.log('发送消息成功，消息为: ', obj)
     }
  }
})

// 上传前已经能得到 idClient 做渲染
console.log(message.idClient)

// 重发
function resendMessage(oldMessage) {
  nim.sendFile(Object.assign(oldMessage, {
    scene: 'p2p',
    to: 'account',
    type: 'image',
    fileInput: 'domId',
    resend: true, // 注意这个 resend 标记为 true，才能固定使用 oldMessage 里的 idClient
    done: function(err, obj) {
     if (err) {
        console.log('发送失败', err)
     } else {
        console.log('发送消息成功，消息为: ', obj)
     }
    }
  }))
}

先previewFile，再发送文件

nim.previewFile({
   type: 'image',
   fileInput: fileInput,
   uploadprogress: function(obj) {
       console.log('文件总大小: ' + obj.total + 'bytes');
       console.log('已经上传的大小: ' + obj.loaded + 'bytes');
       console.log('上传进度: ' + obj.percentage);
       console.log('上传进度文本: ' + obj.percentageText);
   },
   done: function(error, file) {
       console.log('上传image' + (!error?'成功':'失败'));
       // show file to the user
       if (!error) {
           var msg = nim.sendFile({
               scene: 'p2p',
               to: 'account',
               file: file,
               done: sendMsgDone
           });
           console.log('正在发送p2p image消息, id=' + msg.idClient);
           pushMsg(msg);
       }
   }
})

关联链接

• CloudStorageInterface.previewFile
• 收发文件消息

向目标用户、目标群组或目标超大群发送地理位置消息。

注意

该接口直接返回的是 sending 状态的未完成消息体，发送完毕的消息体需要传递 options.done 获得。

影响范围

调用该 API 可触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

示例

nim.sendGeo({
  scene: 'p2p',
  to: 'account',
  //接收方通过onMsg接收消息
  //然后如果msg.type === 'geo'，接收方通过读取msg.geo，然后调用业务代码
  geo: {
     lng: 116.3833,
     lat: 39.9167,
     title: 'Beijing'
  },
  done: function(err, msg) {
     if (err) {
        console.log('发送失败', err)
     } else {
        console.log('发送消息成功，消息为: ', msg)
     }
  }
})

发送单聊消息的已读回执。

使用场景

单聊场景下，用户B 收到 用户A 发送的消息后，将消息标注为已读。

注意

已读回执分有两种接收方式：

1. 初始化登录时，在同步阶段下发会话的已读回执时间, 必须设置NIMGetInstanceOptions.syncMsgReceipts = true，才能够接收
2. 在线时，如果其它用户发送已读回执，通过NIMGetInstanceOptions.onupdatesessions 监听会话的最新已读回执时间

影响范围

调用该 API 后，可触发已读回执接收方的 NIMGetInstanceOptions.onupdatesessions 回调。

示例场景

• 已读回执-单聊

群消息接收发送消息已读回执。发送方如果在线且已在初始化时注册 onTeamMsgReceipt ，会收到群消息已读的通知

注意

注意，发送者必须设置needMsgReceipt = true，接收者才能够发送群消息已读回执

群消息已读回执分有两种接收方式：

1. 初始化登录时，在同步阶段下发会话的已读回执时间, 必须设置NIMGetInstanceOptions.syncMsgReceipts = true，才能够接收
2. 在线时，如果其它用户发送已读回执，通过NIMGetInstanceOptions.onTeamMsgReceipt 监听会话的最新已读回执时间

影响范围

调用该 API 发送成功时可触发: 回执接收方的 onTeamMsgReceipt 回调。

示例场景

• 已读回执-群

示例

//消息发送方
nim.sendText({
  scene: 'team',
  to: 'teamId',
  text: "Hello",
  //注意，该字段必须设置为true
  needMsgReceipt: true
})

//消息接收方
nim.sendTeamMsgReceipt({
  teamMsgReceipts: [{
    teamId: 'teamId',
    idClient: 'xxxx',
    idServer: 'yyyy'
  }]
})

向目标用户、目标群组或目标超大群发送文本消息。

注意

该接口直接返回的是 sending 状态的未完成的消息体，发送完毕的消息体需要传递 options.done 获得。

影响范围

调用该 API 可触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

示例场景

• 各类消息发送
• 消息推送示例
• 会话中消息队列维护
• 已读回执-群

示例

nim.sendText({
  scene: 'p2p',
  to: 'account',
  text: 'hello',
  done: function(err, msg) {
     if (err) {
        console.log('发送失败', err)
     } else {
        console.log('发送消息成功，消息为: ', msg)
     }
  }
})

向目标用户、目标群组或目标超大群发送提示消息。提示消息主要用于会话内的通知提醒，典型业务场景包括进入群组时出现的欢迎消息和会话过程中命中敏感词后的提示等。

注意

该接口直接返回的是 sending 状态的未完成消息体，发送完毕的消息体需要传递 options.done 获得。

影响范围

调用该 API 可触发:

1. 接收方的 NIMGetInstanceOptions.onmsg 回调函数
2. 接收方的 NIMGetInstanceOptions.onupdatesessions 回调
3. 发送方的 NIMGetInstanceOptions.onupdatesessions 回调
4. 发送方同时在线的其它客户端 NIMGetInstanceOptions.onmsg 回调

示例

nim.sendTipMsg({
  scene: 'p2p',
  to: 'account',
  //接收方通过onMsg接收消息
  //然后如果msg.type === 'tip'，接收方通过读取msg.tip，然后调用业务代码
  tip: 'tip content',
  done: function(err, msg) {
     if (err) {
        console.log('发送失败', err)
     } else {
        console.log('发送消息成功，消息为: ', msg)
     }
  }
})