new SDK(options)
即时通信 IM SDK 基本概念:
基本概念 | 说明 |
---|---|
Message(消息) | IM SDK 中 Message 表示要发送给对方的内容,消息包括若干属性,例如自己是否为发送者,发送人帐号以及消息产生时间等。 |
Conversation(会话) | IM SDK 中 Conversation 分为两种: |
Profile(资料) | IM SDK 中 Profile 描述个人的常用基本信息,例如昵称、性别、个性签名以及头像地址等。 |
Friend(好友) | IM SDK 中 Friend 描述好友的常用基本信息,例如备注、分组等。 |
FriendApplication(好友申请) | IM SDK 中 FriendApplication 描述好友申请的常用基本信息,例如加好友来源、备注等。 |
FriendGroup(好友分组) | IM SDK 中 FriendGroup 描述好友分组的常用基本信息,例如分组名、分组成员等。 |
Group(群组) | IM SDK 中 Group 表示一个支持多人聊天的通信系统,支持好友工作群(Work)、陌生人社交群(Public)、临时会议群(Meeting)和直播群(AVChatRoom) |
GroupMember(群成员) | IM SDK 中 GroupMember 描述群内成员的常用基本信息,例如 ID、昵称、群内身份以及入群时间等。 |
群提示消息 | 当有用户被邀请加入群组或被移出群组等事件发生时,群内会产生提示消息,接入侧可以根据实际需求展示给群组用户或忽略。 群提示消息有多种类型,详细描述请参见 Message.GroupTipPayload。 |
群系统通知消息 | 当有用户申请加群等事件发生时,管理员会收到申请加群等系统消息。管理员同意或拒绝加群申请,IM SDK 会通过群系统通知消息将申请加群等相应消息发送给接入侧,由接入侧展示给用户。 群系统通知消息有多种类型,详细描述请参见 Message.GroupSystemNoticePayload。 |
消息上屏 | 用户单击发送后,事先输入的文字或选择的图片等信息显示在用户电脑屏幕或手机屏幕上的过程。 |
支持的平台:
- IM SDK 支持 IE 9+、Chrome、微信、手机QQ、QQ 浏览器、FireFox、Opera 和 Safari。
Web项目集成 SDK
集成方式 | 示例 |
---|---|
NPM 集成 | // IM Web SDK npm install tim-js-sdk --save // 发送图片、文件等消息需要的上传插件 npm install tim-upload-plugin --save |
Script 集成 | 在您的项目中使用 script 标签引入 SDK,并初始化 IM Web SDK 下载地址:IM Web SDK |
微信小程序项目集成 SDK
集成方式 | 示例 |
---|---|
NPM 集成 | // IM 小程序 SDK npm install tim-wx-sdk --save // 发送图片、文件等消息需要的上传插件 npm install tim-upload-plugin --save |
Example
import TIM from 'tim-js-sdk';
// import TIM from 'tim-wx-sdk'; // 微信小程序环境请取消本行注释,并注释掉 import TIM from 'tim-js-sdk';
import TIMUploadPlugin from 'tim-upload-plugin'; // 使用前请将 IM SDK 升级到v2.9.2或更高版本
// 创建 SDK 实例,TIM.create() 方法对于同一个 SDKAppID 只会返回同一份实例
let options = {
SDKAppID: 0 // 接入时需要将0替换为您的即时通信应用的 SDKAppID
};
let tim = TIM.create(options); // SDK 实例通常用 tim 表示
// 设置 SDK 日志输出级别,详细分级请参见 setLogLevel 接口的说明
tim.setLogLevel(0); // 普通级别,日志量较多,接入时建议使用
// tim.setLogLevel(1); // release级别,SDK 输出关键信息,生产环境时建议使用
// 注册腾讯云即时通信 IM 上传插件,即时通信 IM SDK 发送图片、语音、视频、文件等消息需要使用上传插件,将文件上传到腾讯云对象存储
tim.registerPlugin({'tim-upload-plugin': TIMUploadPlugin});
// 监听事件,如:
tim.on(TIM.EVENT.SDK_READY, function(event) {
// 收到离线消息和会话列表同步完毕通知,接入侧可以调用 sendMessage 等需要鉴权的接口
// event.name - TIM.EVENT.SDK_READY
});
tim.on(TIM.EVENT.MESSAGE_RECEIVED, function(event) {
// 收到推送的单聊、群聊、群提示、群系统通知的新消息,可通过遍历 event.data 获取消息列表数据并渲染到页面
// event.name - TIM.EVENT.MESSAGE_RECEIVED
// event.data - 存储 Message 对象的数组 - [Message]
});
tim.on(TIM.EVENT.MESSAGE_MODIFIED, function(event) {
// 收到消息被第三方回调修改的通知,消息发送方可通过遍历 event.data 获取消息列表数据并更新页面上同 ID 消息的内容(v2.12.1起支持)
// event.name - TIM.EVENT.MESSAGE_MODIFIED
// event.data - 存储被第三方回调修改过的 Message 对象的数组 - [Message]
});
tim.on(TIM.EVENT.MESSAGE_REVOKED, function(event) {
// 收到消息被撤回的通知。使用前需要将SDK版本升级至v2.4.0或更高版本
// event.name - TIM.EVENT.MESSAGE_REVOKED
// event.data - 存储 Message 对象的数组 - [Message] - 每个 Message 对象的 isRevoked 属性值为 true
});
tim.on(TIM.EVENT.MESSAGE_READ_BY_PEER, function(event) {
// SDK 收到对端已读消息的通知,即已读回执。使用前需要将SDK版本升级至v2.7.0或更高版本。仅支持单聊会话
// event.name - TIM.EVENT.MESSAGE_READ_BY_PEER
// event.data - event.data - 存储 Message 对象的数组 - [Message] - 每个 Message 对象的 isPeerRead 属性值为 true
});
tim.on(TIM.EVENT.CONVERSATION_LIST_UPDATED, function(event) {
// 收到会话列表更新通知,可通过遍历 event.data 获取会话列表数据并渲染到页面
// event.name - TIM.EVENT.CONVERSATION_LIST_UPDATED
// event.data - 存储 Conversation 对象的数组 - [Conversation]
});
tim.on(TIM.EVENT.GROUP_LIST_UPDATED, function(event) {
// 收到群组列表更新通知,可通过遍历 event.data 获取群组列表数据并渲染到页面
// event.name - TIM.EVENT.GROUP_LIST_UPDATED
// event.data - 存储 Group 对象的数组 - [Group]
});
tim.on(TIM.EVENT.PROFILE_UPDATED, function(event) {
// 收到自己或好友的资料变更通知
// event.name - TIM.EVENT.PROFILE_UPDATED
// event.data - 存储 Profile 对象的数组 - [Profile]
});
tim.on(TIM.EVENT.BLACKLIST_UPDATED, function(event) {
// 收到黑名单列表更新通知
// event.name - TIM.EVENT.BLACKLIST_UPDATED
// event.data - 存储 userID 的数组 - [userID]
});
tim.on(TIM.EVENT.ERROR, function(event) {
// 收到 SDK 发生错误通知,可以获取错误码和错误信息
// event.name - TIM.EVENT.ERROR
// event.data.code - 错误码
// event.data.message - 错误信息
});
tim.on(TIM.EVENT.SDK_NOT_READY, function(event) {
// 收到 SDK 进入 not ready 状态通知,此时 SDK 无法正常工作
// event.name - TIM.EVENT.SDK_NOT_READY
});
tim.on(TIM.EVENT.KICKED_OUT, function(event) {
// 收到被踢下线通知
// event.name - TIM.EVENT.KICKED_OUT
// event.data.type - 被踢下线的原因,例如 :
// - TIM.TYPES.KICKED_OUT_MULT_ACCOUNT 多实例登录被踢
// - TIM.TYPES.KICKED_OUT_MULT_DEVICE 多终端登录被踢
// - TIM.TYPES.KICKED_OUT_USERSIG_EXPIRED 签名过期被踢(v2.4.0起支持)。
});
tim.on(TIM.EVENT.NET_STATE_CHANGE, function(event) {
// 网络状态发生改变(v2.5.0 起支持)
// event.name - TIM.EVENT.NET_STATE_CHANGE
// event.data.state 当前网络状态,枚举值及说明如下:
// - TIM.TYPES.NET_STATE_CONNECTED - 已接入网络
// - TIM.TYPES.NET_STATE_CONNECTING - 连接中。很可能遇到网络抖动,SDK 在重试。接入侧可根据此状态提示“当前网络不稳定”或“连接中”
// - TIM.TYPES.NET_STATE_DISCONNECTED - 未接入网络。接入侧可根据此状态提示“当前网络不可用”。SDK 仍会继续重试,若用户网络恢复,SDK 会自动同步消息
});
tim.on(TIM.EVENT.FRIEND_LIST_UPDATED, function(event) {
// 收到好友列表更新通知(v2.13.0起支持)
// event.name - TIM.EVENT.FRIEND_LIST_UPDATED
// event.data - 存储 Friend 对象的数组 - [Friend]
});
tim.on(TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED, function(event) {
// 收到好友申请列表更新通知(v2.13.0起支持)
// event.name - TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED
// friendApplicationList - 好友申请列表 - [FriendApplication]
// unreadCount - 好友申请的未读数
// const { friendApplicationList, unreadCount } = event.data;
// 发送给我的好友申请(即别人申请加我为好友)
// const applicationSentToMe = friendApplicationList.filter((friendApplication) => friendApplication.type === TIM.TYPES.SNS_APPLICATION_SENT_TO_ME);
// 我发送出去的好友申请(即我申请加别人为好友)
// const applicationSentByMe = friendApplicationList.filter((friendApplication) => friendApplication.type === TIM.TYPES.SNS_APPLICATION_SENT_BY_ME);
});
tim.on(TIM.EVENT.FRIEND_GROUP_LIST_UPDATED, function(event) {
// 收到好友分组列表更新通知(v2.13.0起支持)
// event.name - TIM.EVENT.FRIEND_GROUP_LIST_UPDATED
// event.data - 存储 FriendGroup 对象的数组 - [FriendGroup]
});
// 开始登录
tim.login({userID: 'your userID', userSig: 'your userSig'});
Parameters:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
应用配置 Properties
|
Methods
login(options) → {Promise}
使用 用户ID(userID) 和 签名串(userSig) 登录即时通信 IM,登录流程有若干个异步执行的步骤,使用返回的 Promise 对象处理登录成功或失败。
注意1:登录成功,需等待 sdk 处于 ready 状态后(监听事件 TIM.EVENT.SDK_READY)才能调用 sendMessage 等需要鉴权的接口。
注意2:默认情况下,不支持多实例登录,即如果此帐号已在其他页面登录,若继续在当前页面登录成功,有可能会将其他页面踢下线。用户被踢下线时会触发事件TIM.EVENT.KICKED_OUT
,用户可在监听到事件后做相应处理。
如需支持多实例登录(允许在多个网页中同时登录同一帐号),请到 即时通信 IM 控制台,找到相应 SDKAppID,【应用配置】 > 【功能配置】> 【Web端实例同时在线】配置实例个数。配置将在50分钟内生效。
Example
let promise = tim.login({userID: 'your userID', userSig: 'your userSig'});
promise.then(function(imResponse) {
console.log(imResponse.data); // 登录成功
if (imResponse.data.repeatLogin === true) {
// 标识账号已登录,本次登录操作为重复登录。v2.5.1 起支持
console.log(imResponse.data.errorInfo);
}
}).catch(function(imError) {
console.warn('login error:', imError); // 登录失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
登录配置 Properties
|
Returns:
- Type
- Promise
logout() → {Promise}
登出即时通信 IM,通常在切换帐号的时候调用,清除登录态以及内存中的所有数据。
注意!
- 调用此接口的实例会发布
SDK_NOT_READY
事件,此时该实例下线,无法收、发消息。 - 如果您在即时通信 IM 控制台配置的“Web端实例同时在线个数”大于 1,且同一账号登录了
a1
和a2
两个实例(含小程序端),当执行a1.logout()
后,a1
会下线,无法收、发消息。而a2
实例不会受影响。 - 多实例被踢:基于第 2 点,如果“Web端实例同时在线个数”配置为 2,且您的某一账号已经登录了
a1
,a2
两个实例,当使用此账号成功登录第三个实例a3
时,a1
或a2
中的一个实例会被踢下线(通常是最先处在登录态的实例会触发),这种情况称之为**“多实例被踢”**。假设a1
实例被踢下线,a1
实例内部会执行登出流程,然后抛出KICKED_OUT
事件,接入侧可以监听此事件,并在触发时跳转到登录页。此时a1
实例下线,而a2
、a3
实例可以正常运行。
Example
let promise = tim.logout();
promise.then(function(imResponse) {
console.log(imResponse.data); // 登出成功
}).catch(function(imError) {
console.warn('logout error:', imError);
});
Returns:
- Type
- Promise
destroy() → {Promise}
销毁 SDK 实例。SDK 会先 logout,然后断开 WebSocket 长连接,并释放资源
Example
tim.destroy();
Returns:
- Type
- Promise
on(eventName, handler, contextopt)
监听事件。
注意:请在调用 login 接口前调用此接口监听事件,避免漏掉 SDK 派发的事件。
Example
let onMessageReceived = function(event) {
// 收到推送的单聊、群聊、群提示、群系统通知的新消息,可通过遍历 event.data 获取消息列表数据并渲染到页面
// event.name - TIM.EVENT.MESSAGE_RECEIVED
// event.data - 存储 Message 对象的数组 - [Message]
};
tim.on(TIM.EVENT.MESSAGE_RECEIVED, onMessageReceived);
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
eventName |
String |
事件名称。所有的事件名称都存放在 |
|
handler |
function |
处理事件的方法,当事件触发时,会调用此handler进行处理。 |
|
context |
* |
<optional> |
期望 handler 执行时的上下文 |
off(eventName, handler, contextopt, onceopt)
取消监听事件。
Example
let onMessageReceived = function(event) {
// 收到推送的单聊、群聊、群提示、群系统通知的新消息,可通过遍历 event.data 获取消息列表数据并渲染到页面
// event.name - TIM.EVENT.MESSAGE_RECEIVED
// event.data - 存储 Message 对象的数组 - [Message]
};
tim.off(TIM.EVENT.MESSAGE_RECEIVED, onMessageReceived);
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
eventName |
String |
事件名称。所有的事件名称都存放在 |
|
handler |
function |
处理事件的方法,当事件触发时,会调用此handler进行处理。 |
|
context |
* |
<optional> |
期望 handler 执行时的上下文 |
once |
Boolean |
<optional> |
是否只解绑一次 |
registerPlugin(options)
注册插件。
即时通信 IM SDK 发送图片、语音、视频、文件等消息需要使用上传插件,将文件上传到腾讯云对象存储。
Example
// 使用前请将 tim-js-sdk 或 tim-wx-sdk 升级到v2.9.2或更高版本
// 小程序端使用 tim-upload-plugin,在小程序管理后台增加 uploadFile 域名配置 https://cos.ap-shanghai.myqcloud.com,增加 downloadFile 域名配置 https://cos.ap-shanghai.myqcloud.com
tim.registerPlugin({'tim-upload-plugin': TIMUploadPlugin});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
插件配置 Properties
|
setLogLevel(level)
设置日志级别,低于 level 的日志将不会输出。
Example
tim.setLogLevel(0);
Parameters:
Name | Type | Description |
---|---|---|
level |
Number |
日志级别
|
createTextMessage(options) → {Message}
创建文本消息的接口,此接口返回一个消息实例,可以在需要发送文本消息时调用 发送消息 接口发送消息。
注意:创建话题消息时 to 是话题 ID, conversationType 是
TIM.TYPES.CONV_GROUP
。
Examples
// 发送文本消息,Web 端与小程序端相同
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createTextMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
text: 'Hello world!'
},
// v2.20.0起支持C2C消息已读回执功能,如果您发消息需要已读回执,需购买旗舰版套餐,并且创建消息时将 needReadReceipt 设置为 true
needReadReceipt: true
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// 发送群消息
let message = tim.createTextMessage({
to: 'test',
conversationType: TIM.TYPES.CONV_GROUP,
payload: {
text: 'Hello world!'
},
// v2.18.0起支持群消息已读回执功能,如果您发消息需要已读回执,需购买旗舰版套餐,并且创建消息时将 needReadReceipt 设置为 true
needReadReceipt: true
});
// 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// 向社群(不支持话题)发消息,v2.17.0 起支持
let message = tim.createTextMessage({
to: '@TGS#_@TGS#cWWFWHIM62CL', // 社群 ID
conversationType: TIM.TYPES.CONV_GROUP,
payload: {
text: 'Hello world!'
},
// v2.18.0起支持群消息已读回执功能,如果您发消息需要已读回执,需购买旗舰版套餐,并且创建消息时将 needReadReceipt 设置为 true
needReadReceipt: true
});
// 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// 向话题(Topic)发消息,v2.19.1 起支持
let message = tim.createTextMessage({
to: '@TGS#_@TGS#cWWFWHIM62CL@TOPIC#_@TOPIC#cXWFWHIM62CR', // 话题 ID
conversationType: TIM.TYPES.CONV_GROUP,
payload: {
text: 'Hello world!'
},
});
// 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createTextAtMessage(options) → {Message}
创建可以附带 @ 提醒功能的文本消息的接口,此接口返回一个消息实例,可以在需要发送文本消息时调用 发送消息 接口发送消息。
注意1:使用该接口前,需要将 SDK 版本升级至v2.9.0或更高版本。
注意2:此接口仅用于群聊,且社群和话题不支持 @ALL。
Example
// 发送文本消息,Web 端与小程序端相同
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createTextAtMessage({
to: 'group1',
conversationType: TIM.TYPES.CONV_GROUP,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
text: '@denny @lucy @所有人 今晚聚餐,收到的请回复1',
atUserList: ['denny', 'lucy', TIM.TYPES.MSG_AT_ALL] // 'denny' 'lucy' 都是 userID,而非昵称
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createImageMessage(options) → {Message}
创建图片消息的接口,此接口返回一个消息实例,可以在需要发送图片消息时调用 发送消息 接口发送消息。
注意1:v2.3.1版本开始支持传入 File 对象,使用前需要将 SDK 升级至v2.3.1或更高版本。
注意2:v2.11.2版本支持 uni-app 发图片等文件类消息,使用前需要将 SDK 升级至v2.11.2或更高版本,同时将 tim-upload-plugin 升级至v1.0.2或更高版本。
注意3:v2.16.1版本开始支持支付宝小程序发送后缀为 .image 的图片。 注意4:v2.17.0版本开始支持 webp 格式的图片。
Examples
// Web 端发送图片消息示例1 - 传入 DOM 节点
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createImageMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
file: document.getElementById('imagePicker'),
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// Web 端发送图片消息示例2- 传入 File 对象
// 先在页面上添加一个 id 为 "testPasteInput" 的消息输入框,如 <input type="text" id="testPasteInput" placeholder="截图后粘贴到输入框中" size="30" />
document.getElementById('testPasteInput').addEventListener('paste', function(e) {
let clipboardData = e.clipboardData;
let file;
let fileCopy;
if (clipboardData && clipboardData.files && clipboardData.files.length > 0) {
file = clipboardData.files[0];
// 图片消息发送成功后,file 指向的内容可能被浏览器清空,如果接入侧有额外的渲染需求,可以提前复制一份数据
fileCopy = file.slice();
}
if (typeof file === 'undefined') {
console.warn('file 是 undefined,请检查代码或浏览器兼容性!');
return;
}
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createImageMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: {
file: file
},
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
});
// 小程序端发送图片
// 1. 选择图片
wx.chooseImage({
sourceType: ['album'], // 从相册选择
count: 1, // 只选一张,目前 SDK 不支持一次发送多张图片
success: function (res) {
// 2. 创建消息实例,接口返回的实例可以上屏
let message = tim.createImageMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: { file: res },
onProgress: function(event) { console.log('file uploading:', event) }
});
// 3. 发送图片
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
}
})
// uni-app 发送图片,使用前请将 SDK 升级至v2.11.2或更高版本,将 tim-upload-plugin 升级至v1.0.2或更高版本
// 1. 选择图片
uni.chooseImage({
count: 1,
sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有
sourceType: ['album'], // 从相册选择
success: function(res) {
let message = tim.createImageMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: { file: res },
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
}
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createAudioMessage(options) → {Message}
创建音频消息实例的接口,此接口返回一个消息实例,可以在需要发送音频消息时调用 发送消息 接口发送消息。 目前 createAudioMessage 只支持在微信小程序环境使用。
Example
// 示例:使用微信官方的 RecorderManager 进行录音,参考 https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html
// 1. 获取全局唯一的录音管理器 RecorderManager
const recorderManager = wx.getRecorderManager();
// 录音部分参数
const recordOptions = {
duration: 60000, // 录音的时长,单位 ms,最大值 600000(10 分钟)
sampleRate: 44100, // 采样率
numberOfChannels: 1, // 录音通道数
encodeBitRate: 192000, // 编码码率
format: 'aac' // 音频格式,选择此格式创建的音频消息,可以在即时通信 IM 全平台(Android、iOS、微信小程序和Web)互通
};
// 2.1 监听录音错误事件
recorderManager.onError(function(errMsg) {
console.warn('recorder error:', errMsg);
});
// 2.2 监听录音结束事件,录音结束后,调用 createAudioMessage 创建音频消息实例
recorderManager.onStop(function(res) {
console.log('recorder stop', res);
// 4. 创建消息实例,接口返回的实例可以上屏
const message = tim.createAudioMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
file: res
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 5. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
});
// 3. 开始录音
recorderManager.start(recordOptions);
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createVideoMessage(options) → {Message}
创建视频消息实例的接口,此接口返回一个消息实例,可以在需要发送视频消息时调用 发送消息 接口发送消息。
注意1:使用该接口前,需要将 SDK 版本升级至v2.2.0或更高版本。只支持 mp4 格式的视频。
注意2:createVideoMessage 支持在微信小程序环境使用,从v2.6.0起,支持在 Web 环境使用。
注意3:全平台互通视频消息,移动端请升级使用 最新的 TUIKit 或 SDK。
注意4:v2.16.2起 uni-app 发文件消息,使用前需要将 SDK 升级至v2.16.2或更高版本,同时将 tim-upload-plugin 升级至v1.0.2或更高版本。
注意5:v2.17.0起 SDK 支持视频封面 snapshotUrl,需要使用 tim-upload-plugin 作为上传插件。
Examples
// 小程序端发送视频消息示例:
// 1. 调用小程序接口选择视频,接口详情请查阅 https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseVideo.html
wx.chooseVideo({
sourceType: ['album', 'camera'], // 来源相册或者拍摄
maxDuration: 60, // 设置最长时间60s
camera: 'back', // 后置摄像头
success (res) {
// 2. 创建消息实例,接口返回的实例可以上屏
let message = tim.createVideoMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
file: res
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
// v2.12.2起,支持小程序端视频上传进度回调
onProgress: function(event) { console.log('file uploading:', event) }
})
// 3. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
}
})
// web 端发送视频消息示例(v2.6.0起支持):
// 1. 获取视频:传入 DOM 节点
// 2. 创建消息实例
const message = tim.createVideoMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: {
file: document.getElementById('videoPicker') // 或者用event.target
},
onProgress: function(event) { console.log('file uploading:', event) }
});
// 3. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// uni-app 发送视频,使用前请将 SDK 升级至v2.16.2或更高版本,将 tim-upload-plugin 升级至v1.0.2或更高版本
// 1. 选择视频
uni.chooseVideo({
count: 1,
sourceType: ['camera', 'album'], // album 从相册选视频,camera 使用相机拍摄,默认为:['album', 'camera']
maxDuration: 60, // 设置最长时间60s
camera: 'back', // 后置摄像头
success: function(res) {
let message = tim.createVideoMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: { file: res },
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
}
})
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createCustomMessage(options) → {Message}
创建自定义消息实例的接口,此接口返回一个消息实例,可以在需要发送自定义消息时调用 发送消息 接口发送消息。 当 SDK 提供的能力不能满足您的需求时,可以使用自定义消息进行个性化定制,例如投骰子功能。
Example
// 示例:利用自定义消息实现投骰子功能
// 1. 定义随机函数
function random(min, max) {
return Math.floor(Math.random() * (max - min + 1) + min);
}
// 2. 创建消息实例,接口返回的实例可以上屏
let message = tim.createCustomMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_HIGH,
payload: {
data: 'dice', // 用于标识该消息是骰子类型消息
description: String(random(1,6)), // 获取骰子点数
extension: ''
}
});
// 3. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createFaceMessage(options) → {Message}
创建表情消息实例的接口,此接口返回一个消息实例,可以在需要发送表情消息时调用 发送消息 接口发送消息。
注意:使用该接口前,需要将 SDK 版本升级至v2.3.1或更高版本。
Example
// 发送表情消息,Web端与小程序端相同。
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createFaceMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
index: 1, // Number 表情索引,用户自定义
data: 'tt00' // String 额外数据
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createFileMessage(options) → {Message}
创建文件消息的接口,此接口返回一个消息实例,可以在需要发送文件消息时调用 发送消息 接口发送消息。
注意1:v2.3.1版本开始支持传入 File 对象,使用前需要将 SDK 升级至v2.3.1或更高版本。
注意2:v2.4.0版本起,上传文件大小最大值调整为100M。
注意3:微信小程序目前不支持选择文件的功能,故该接口暂不支持微信小程序端。
注意4:v2.16.2版本支持 uni-app 发文件消息,使用前需要将 SDK 升级至v2.16.2或更高版本,同时将 tim-upload-plugin 升级至v1.0.2或更高版本。
Examples
// Web 端发送文件消息示例1 - 传入 DOM 节点
// 1. 创建文件消息实例,接口返回的实例可以上屏
let message = tim.createFileMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
file: document.getElementById('filePicker'),
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
// Web 端发送文件消息示例2- 传入 File 对象
// 先在页面上添加一个 id 为 "testPasteInput" 的消息输入框,如 <input type="text" id="testPasteInput" placeholder="截图后粘贴到输入框中" size="30" />
document.getElementById('testPasteInput').addEventListener('paste', function(e) {
let clipboardData = e.clipboardData;
let file;
let fileCopy;
if (clipboardData && clipboardData.files && clipboardData.files.length > 0) {
file = clipboardData.files[0];
// 图片消息发送成功后,file 指向的内容可能被浏览器清空,如果接入侧有额外的渲染需求,可以提前复制一份数据
fileCopy = file.slice();
}
if (typeof file === 'undefined') {
console.warn('file 是 undefined,请检查代码或浏览器兼容性!');
return;
}
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createFileMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: {
file: file
},
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
});
// uni-app 发送文件,使用前请将 SDK 升级至v2.16.2或更高版本,将 tim-upload-plugin 升级至v1.0.2或更高版本
// 1. 选择文件
uni.chooseFile({
count: 1,
extension:['.zip','.doc'],
success: function(res) {
let message = tim.createFileMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: { file: res },
onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
}
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createLocationMessage(options) → {Message}
创建地理位置消息的接口,此接口返回一个消息实例,可以在需要发送地理位置消息时调用 发送消息 接口发送消息。
注意1:v2.15.0起支持
Example
// 发送地理位置消息,Web 端与小程序端相同(v2.15.0起支持)
// 1. 创建消息实例,接口返回的实例可以上屏
let message = tim.createLocationMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊(v2.4.2起支持)。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: {
description: '深圳市深南大道10000号腾讯大厦',
longitude: 113.941079, // 经度
latitude: 22.546103 // 纬度
}
});
// 2. 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
createMergerMessage(options) → {Message}
创建合并消息的接口,此接口返回一个消息实例,可以在需要发送合并消息时调用 发送消息 接口发送消息。
注意1:使用前需要将 SDK 升级至v2.10.1或更高版本。
注意2:不支持合并已发送失败的消息,如果消息列表内传入了已发送失败的消息,则创建消息接口会报错。
Example
// 1. 将群聊消息转发到 c2c 会话
// message1 message2 message3 是群聊消息
let mergerMessage = tim.createMergerMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
payload: {
messageList: [message1, message2, message3],
title: '大湾区前端人才中心的聊天记录',
abstractList: ['allen: 666', 'iris: [图片]', 'linda: [文件]'],
compatibleText: '请升级IMSDK到v2.10.1或更高版本查看此消息'
},
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 2. 发送消息
let promise = tim.sendMessage(mergerMessage);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
downloadMergerMessage(message) → {Promise}
下载合并消息的接口。如果发送方发送的合并消息较大,SDK 会将此消息存储到云端,消息接收方查看消息时,需要先把消息从云端下载到本地。
注意1:使用前需要将 SDK 升级至v2.10.1或更高版本。
Example
// downloadKey 存在说明收到的合并消息存储在云端,需要先下载
if (message.type === TIM.TYPES.MSG_MERGER && message.payload.downloadKey !== '') {
let promise = tim.downloadMergerMessage(message);
promise.then(function(imResponse) {
// 下载成功后,SDK会更新 message.payload.messageList 等信息
console.log(imResponse.data);
}).catch(function(imError) {
// 下载失败
console.warn('downloadMergerMessage error:', imError);
});
}
Parameters:
Name | Type | Description |
---|---|---|
message |
Message |
消息实例 |
Returns:
- Type
- Promise
createForwardMessage(options) → {Message}
创建转发消息的接口,此接口返回一个消息实例,可以在需要发送转发消息时调用 发送消息 接口发送消息。
注意1:使用前需要将 SDK 升级至v2.10.1或更高版本。
注意2:支持单条转发和逐条转发。
Example
let forwardMessage = tim.createForwardMessage({
to: 'user1',
conversationType: TIM.TYPES.CONV_C2C,
// 消息优先级,用于群聊,如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息,详细请参考:https://cloud.tencent.com/document/product/269/3663#.E6.B6.88.E6.81.AF.E4.BC.98.E5.85.88.E7.BA.A7.E4.B8.8E.E9.A2.91.E7.8E.87.E6.8E.A7.E5.88.B6)
// 支持的枚举值:TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL(默认), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
// priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
payload: message, // 消息实例,已收到的或自己已发出的消息
// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到,v2.10.2起支持)
// cloudCustomData: 'your cloud custom data'
});
// 2. 发送消息
let promise = tim.sendMessage(forwardMessage);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
消息实例
- Type
- Message
sendMessage(message, optionsopt) → {Promise}
发送消息的接口,需先调用下列的创建消息实例的接口获取消息实例后,再调用该接口发送消息实例。
注意1:调用该接口发送消息实例,需要 sdk 处于 ready 状态,否则将无法发送消息实例。sdk 状态,可通过监听以下事件得到:
- TIM.EVENT.SDK_READY - sdk 处于 ready 状态时触发
- TIM.EVENT.SDK_NOT_READY - sdk 处于 not ready 状态时触发
注意2:接收推送的单聊、群聊、群提示、群系统通知的新消息,需监听事件 TIM.EVENT.MESSAGE_RECEIVED
注意3:本实例发送的消息,不会触发事件 TIM.EVENT.MESSAGE_RECEIVED。同账号从其他端(或通过 REST API)发送的消息,会触发事件 TIM.EVENT.MESSAGE_RECEIVED
注意4:离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
注意5:onlineUserOnly 和 messageControlInfo 不能同时使用。
Examples
// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。离线推送的标题和内容使用默认值。
// 离线推送的说明请参考 https://cloud.tencent.com/document/product/269/3604
tim.sendMessage(message);
// v2.6.4起支持消息发送选项
tim.sendMessage(message, {
onlineUserOnly: true // 如果接收方不在线,则消息不存入漫游,且不会进行离线推送
});
// v2.6.4起支持消息发送选项
tim.sendMessage(message, {
offlinePushInfo: {
disablePush: true // 如果接收方不在线,则消息将存入漫游,但不进行离线推送
}
});
// v2.6.4起支持消息发送选项
tim.sendMessage(message, {
// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。接入侧可自定义离线推送的标题及内容
offlinePushInfo: {
title: '', // 离线推送标题
description: '', // 离线推送内容
androidOPPOChannelID: '' // 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID
}
});
// v2.16.0起支持消息控制选项
tim.sendMessage(message, {
messageControlInfo: {
excludedFromUnreadCount: true, // 消息不更新会话 unreadCount(消息存漫游)
excludedFromLastMessage: true // 消息不更新会话 lastMessage(消息存漫游)
}
});
Parameters:
Name | Type | Attributes | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
message |
Message |
消息实例 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
options |
Object |
<optional> |
消息发送选项 Properties
|
Returns:
- Type
- Promise
revokeMessage(message) → {Promise}
撤回单聊消息或者群聊消息。撤回成功后,消息对象的 isRevoked 属性值为 true。
注意1:使用该接口前,需要将 SDK 版本升级至v2.4.0或更高版本。
注意2:消息可撤回时间默认为2分钟。可通过 控制台 调整消息可撤回时间。
注意3:被撤回的消息,可以调用 getMessageList 接口从单聊或者群聊消息漫游中拉取到。接入侧须根据消息对象的 isRevoked 属性妥善处理被撤回消息的展示。如单聊会话内可展示为 "对方撤回了一条消息";群聊会话内可展示为 "XXX撤回了一条消息"。
注意4:可使用 REST API 撤回单聊消息 或 撤回群聊消息。
Examples
// 主动撤回消息
let promise = tim.revokeMessage(message);
promise.then(function(imResponse) {
// 消息撤回成功
}).catch(function(imError) {
// 消息撤回失败
console.warn('revokeMessage error:', imError);
});
// 收到消息被撤回的通知
tim.on(TIM.EVENT.MESSAGE_REVOKED, function(event) {
// event.name - TIM.EVENT.MESSAGE_REVOKED
// event.data - 存储 Message 对象的数组 - [Message] - 每个 Message 对象的 isRevoked 属性值为 true
});
// 获取会话的消息列表时遇到被撤回的消息
let promise = tim.getMessageList({conversationID: 'C2Ctest', count: 15});
promise.then(function(imResponse) {
const messageList = imResponse.data.messageList; // 消息列表
messageList.forEach(function(message) {
if (message.isRevoked) {
// 处理被撤回的消息
} else {
// 处理普通消息
}
});
});
Parameters:
Name | Type | Description |
---|---|---|
message |
Message |
消息实例 |
Returns:
- Type
- Promise
resendMessage(message) → {Promise}
重发消息的接口,当消息发送失败时,可调用该接口进行重发。
Example
// 重发消息
let promise = tim.resendMessage(message); // 传入需要重发的消息实例
promise.then(function(imResponse) {
// 重发成功
console.log(imResponse);
}).catch(function(imError) {
// 重发失败
console.warn('resendMessage error:', imError);
});
Parameters:
Name | Type | Description |
---|---|---|
message |
Message |
待重发的消息实例 |
Returns:
- Type
- Promise
deleteMessage(messageList) → {Promise}
删除消息的接口。删除成功后,被删除消息的 isDeleted 属性值为 true。
C2C 会话,消息被删除后,下次登录拉取历史消息将拉取不到,对端不受影响。
群会话,消息被删除后,下次登录拉取历史消息将拉取不到,群内其他成员不受影响。
注意1:使用该接口前,需要将SDK版本升级至v2.12.0或更高版本
注意2:一次最多只能删除30条消息,超过30条则只删除前30条
注意3:要删除的消息必须属于同一会话,以消息列表的第1个消息的所属会话为准
注意4:一秒钟最多只能调用一次该接口
注意5:删除消息不支持多端同步
注意6:AVChatRoom(直播群)不支持删除消息,调用此接口将返回10035错误码
Example
// 删除消息,v2.12.0起支持
let promise = tim.deleteMessage([message1, message2, message3, ...]);
promise.then(function(imResponse) {
// 删除消息成功
}).catch(function(imError) {
// 删除消息失败
console.warn('deleteMessage error:', imError);
});
Parameters:
Name | Type | Description |
---|---|---|
messageList |
Array |
同一会话的消息列表,最大长度为30 |
Returns:
- Type
- Promise
modifyMessage(message) → {Promise}
变更消息的接口。变更成功后,自己和对端用户(C2C)或群组成员(Group)都会收到 MESSAGE_MODIFIED 事件。
注意1:使用该接口前,需要将SDK版本升级至v2.20.0或更高版本
注意2:不支持修改在线消息;不支持修改直播群消息;请勿修改消息的 random,sequence,time 等字段
注意3:只支持修改文本消息、自定义消息、地理位置消息和表情消息
注意4:如果在修改消息过程中,消息已经被其他人修改,SDK 会返回错误码2480,表示修改消息时发生冲突
Example
// 监听 MESSAGE_MODIFIED 事件,当修改消息成功后,SDK 会派发此事件
let onMessageModified = function(event) {
// event.data - 存储被修改过的 Message 对象的数组 - [Message]
};
tim.on(TIM.EVENT.MESSAGE_MODIFIED, onMessageModified);
// 将 txtMessage 的文本内容改为 "Hello Tencent"
txtMessage.payload.text = "Hello Tencent";
let promise = tim.modifyMessage(txtMessage);
promise.then(function(imResponse) {
const { message } = imResponse.data;
// 修改消息成功,message 是最新的消息
}).catch(function(imError) {
// 修改消息失败
const { code, data } = imError;
if (code === 2480) {
// 修改消息发生冲突,data.message 是最新的消息
} else if (code === 2481) {
// 不支持修改直播群消息
} else if (code === 20026) {
// 消息不存在
}
});
Parameters:
Name | Type | Description |
---|---|---|
message |
Message |
消息实例 |
Returns:
- Type
- Promise
getMessageList(options) → {Promise}
分页拉取指定会话的消息列表的接口,当用户进入会话首次渲染消息列表或者用户“下拉查看更多消息”时,需调用该接口。
注意:该接口可用于"拉取历史消息"
Examples
// 打开某个会话时,第一次拉取消息列表,注意!第一次拉取时不要传入 nextReqMessageID
let promise = tim.getMessageList({conversationID: 'C2Ctest', count: 15});
promise.then(function(imResponse) {
const messageList = imResponse.data.messageList; // 消息列表。
const nextReqMessageID = imResponse.data.nextReqMessageID; // 用于续拉,分页续拉时需传入该字段。
const isCompleted = imResponse.data.isCompleted; // 表示是否已经拉完所有消息。isCompleted 为 true 时,nextReqMessageID 为 ""。
});
// 下拉查看更多消息
let promise = tim.getMessageList({conversationID: 'C2Ctest', nextReqMessageID, count: 15});
promise.then(function(imResponse) {
const messageList = imResponse.data.messageList; // 消息列表。
const nextReqMessageID = imResponse.data.nextReqMessageID; // 用于续拉,分页续拉时需传入该字段。
const isCompleted = imResponse.data.isCompleted; // 表示是否已经拉完所有消息。isCompleted 为 true 时,nextReqMessageID 为 ""。
});
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getMessageListHopping(options) → {Promise}
根据指定的消息 sequence 或 消息时间拉取会话的消息列表的接口。
注意:使用该接口前,需要将SDK版本升级至v2.20.0或更高版本
Examples
// 根据 sequence 拉群漫游消息,direction 0 向上拉,拉更旧的消息,direction 1 向下拉,拉更新的消息
let promise = tim.getMessageListHopping({conversationID: 'GROUPtest', sequence: xxx, count: 15, direction: 0});
promise.then(function(imResponse) {
const messageList = imResponse.data.messageList; // 消息列表。
});
// 根据时间拉 C2C 会话漫游消息,direction 0 向上拉,拉更旧的消息,direction 1 向下拉,拉更新的消息
let promise = tim.getMessageListHopping({conversationID: 'C2Ctest', time: xxx, count: 15, direction: 0});
promise.then(function(imResponse) {
const messageList = imResponse.data.messageList; // 消息列表。
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
sendMessageReadReceipt(messageList) → {Promise}
发送消息已读回执。
注意1:使用群消息已读回执功能前,需要将SDK版本升级至v2.18.0或更高版本。
注意2:使用 C2C 消息已读回执功能前,需要将SDK版本升级至v2.20.0或更高版本。
注意3:messageList 里的消息必须在同一个 C2C 或 Group 会话中。
注意4:调用该接口成功后,会话未读数不会变化,消息发送者会收到 TIM.TYPES.MESSAGE_READ_RECEIPT_RECEIVED 事件,回调里面会携带消息的最新已读信息。
Examples
// 拉取群消息列表
let messageList = null;
tim.getMessageList({conversationID: 'GROUPtest', count: 15}).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
tim.sendMessageReadReceipt(messageList).then(function() {
// 发送群消息已读回执成功
}).catch(function(imError) {
// 发送群消息已读回执失败
});
});
// 拉取C2C消息列表
let messageList = null;
tim.getMessageList({conversationID: 'C2Ctest', count: 15}).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
tim.sendMessageReadReceipt(messageList).then(function() {
// 发送群消息已读回执成功
}).catch(function(imError) {
// 发送群消息已读回执失败
});
});
Parameters:
Name | Type | Description |
---|---|---|
messageList |
Array |
同一个 C2C 或 GROUP 会话的消息列表,最大长度为30 |
Returns:
- Type
- Promise
getMessageReadReceiptList(messageList) → {Promise}
拉取已读回执列表。调用时机:拉取完群漫游消息后。
注意1:使用群消息已读回执功能前,需要将SDK版本升级至v2.18.0或更高版本。
注意2:使用 C2C 消息已读回执功能前,需要将SDK版本升级至v2.20.0或更高版本。
注意3:messageList 里的消息必须在同一个 C2C 或 Group 会话中。
Examples
// 拉取群消息列表
let messageList = null;
tim.getMessageList({conversationID: 'GROUPtest', count: 15}).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
tim.getMessageReadReceiptList(messageList).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
// 成功后,Message.readReceiptInfo 包含消息的已读回执信息
// Message.readReceiptInfo.readCount - 消息的已读数,如果想要查询哪些群成员已读了此消息,请使用 [getGroupMessageReadMemberList] 接口
// Message.readReceiptInfo.unreadCount - 消息的未读数,当为0的时候,表示“全部已读”。
}).catch(function(imError) {
// 拉取已读回执列表失败
});
});
// 拉取 C2C 消息列表
let messageList = null;
tim.getMessageList({conversationID: 'C2Ctest', count: 15}).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
tim.getMessageReadReceiptList(messageList).then(function(imResponse) {
messageList = imResponse.data.messageList; // 消息列表
// 成功后,Message.readReceiptInfo 包含消息的已读回执信息
// Message.readReceiptInfo.isPeerRead - 对端是否已发送已读回执
}).catch(function(imError) {
// 拉取已读回执列表失败
});
});
Parameters:
Name | Type | Description |
---|---|---|
messageList |
Array |
同一群会话的消息列表 |
Returns:
- Type
- Promise
getGroupMessageReadMemberList(options) → {Promise}
获取群消息已读(或未读)群成员列表。
注意1:使用该接口前,需要将SDK版本升级至v2.18.0或更高版本
Examples
// 拉取群消息已读成员列表
let promise = tim.getGroupMessageReadMemberList({
message,
filter: 0,
cursor: '', // 第一次拉取传''
count: 30,
});
promise.then(function(imResponse) {
const { isCompleted, cursor, messageID, readUserIDList } = imResponse.data;
// isCompleted - true,拉取完成;false 未完成
// cursor - 当 isCompleted 为 false 的时候用于续拉
// messageID - 群消息的 ID
// readUserIDList - 已读的群成员 userID 列表。接入侧可调用 getGroupMemberProfile 接口查询群成员的资料,如群名片、头像、昵称等
}).catch(function(imError) {
// 拉取群消息已读群成员列表失败
});
// 拉取群消息未读成员列表
let promise = tim.getGroupMessageReadMemberList({
message,
filter: 1,
cursor: '', // 第一次拉取传''
count: 30,
});
promise.then(function(imResponse) {
const { isCompleted, cursor, messageID, readUserIDList } = imResponse.data;
// isCompleted - true,拉取完成;false 未完成
// cursor - 当 isCompleted 为 false 的时候用于续拉
// messageID - 群消息的 ID
// unreadUserIDList - 未读的群成员 userID 列表。接入侧可调用 getGroupMemberProfile 接口查询群成员的资料,如群名片、头像、昵称等
}).catch(function(imError) {
// 拉取群消息未读群成员列表失败
// 10062 - 找不到群消息的已读回执信息
});
Parameters:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
findMessage(messageID) → {Message|null}
根据 messageID 查询会话的本地消息的接口。
注意1:使用该接口前,需要将SDK版本升级至v2.18.0或更高版本
Example
// 查找消息,v2.18.0起支持
let message = tim.findMessage('144115217363870632-1647417469-77069006');
if (message) {
// 读取 message 相关属性,如已读回执信息 readReceiptInfo
}
Parameters:
Name | Type | Description |
---|---|---|
messageID |
String |
消息 ID |
Returns:
- Type
- Message | null
setMessageRead(options) → {Promise}
将某会话下的未读消息状态设置为已读,置为已读的消息不会计入到未读统计,当打开会话或切换会话时调用该接口。如果在打开/切换会话时,不调用该接口,则对应的消息会一直是未读的状态。
Example
// 将某会话下所有未读消息已读上报
let promise = tim.setMessageRead({conversationID: 'C2Cexample'});
promise.then(function(imResponse) {
// 已读上报成功,指定 ID 的会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setMessageRead error:', imError);
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getConversationList(options) → {Promise}
获取会话列表的接口。
注意1:该接口获取的会话列表中的资料是不完整的(仅包括头像、昵称等,能够满足会话列表的渲染需求),若要查询详细会话资料,可参考:getConversationProfile
注意2:客户端默认可从云端拉取100个最近联系人会话,升级旗舰版后可配置从云端拉取最多500个最近联系人会话。
注意3:会话保存时长跟会话最后一条消息保存时间一致,消息默认保存7天,即会话默认保存7天。
注意4:该接口 v2.15.0 起支持获取指定的多个会话。
- See:
Examples
// 获取全量的会话列表
let promise = tim.getConversationList();
promise.then(function(imResponse) {
const conversationList = imResponse.data.conversationList; // 全量的会话列表,用该列表覆盖原有的会话列表
}).catch(function(imError) {
console.warn('getConversationList error:', imError); // 获取会话列表失败的相关信息
});
// 获取指定的会话列表
let promise = tim.getConversationList([conversationID1, conversationID2]);
promise.then(function(imResponse) {
const conversationList = imResponse.data.conversationList; // 缓存中已存在的指定的会话列表
}).catch(function(imError) {
console.warn('getConversationList error:', imError); // 获取会话列表失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
options |
undefined | Array |
参数选项
|
Returns:
- Type
- Promise
getConversationProfile(conversationID) → {Promise}
获取会话资料的接口,当点击会话列表中的某个会话时,调用该接口获取会话的详细信息。
- See:
-
- 会话结构描述
Example
let promise = tim.getConversationProfile(conversationID);
promise.then(function(imResponse) {
// 获取成功
console.log(imResponse.data.conversation); // 会话资料
}).catch(function(imError) {
console.warn('getConversationProfile error:', imError); // 获取会话资料失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
conversationID |
String |
会话 ID。会话 ID 组成方式:
|
Returns:
- Type
- Promise
deleteConversation(conversationID) → {Promise}
根据会话 ID 删除会话的接口。
注意1:v2.16.1起删除会话会同时删除历史消息。
注意2:v2.16.1之前的版本,只删除会话,不删除历史消息。例如:删除与用户 A 的会话,下次再与用户 A 发起会话时,之前的聊天信息仍在。
- See:
-
- 会话结构描述
Example
let promise = tim.deleteConversation('C2CExample');
promise.then(function(imResponse) {
// 删除会话成功
const { conversationID } = imResponse.data; // 被删除的会话 ID
}).catch(function(imError) {
console.warn('deleteConversation error:', imError); // 删除会话失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
conversationID |
String |
会话 ID。会话 ID 组成方式:
|
Returns:
- Type
- Promise
pinConversation(options) → {Promise}
置顶或取消置顶会话的接口。调用接口成功后会话列表重新排序,SDK 会派发事件 TIM.EVENT.CONVERSATION_LIST_UPDATED
注意:v2.14.0起支持
Examples
// 置顶会话,v2.14.0起支持
let promise = tim.pinConversation({ conversationID: 'C2CExample', isPinned: true });
promise.then(function(imResponse) {
// 置顶会话成功
const { conversationID } = imResponse.data; // 被置顶的会话 ID
}).catch(function(imError) {
console.warn('pinConversation error:', imError); // 置顶会话失败的相关信息
});
// 取消置顶会话,v2.14.0起支持
let promise = tim.pinConversation({ conversationID: 'C2CExample', isPinned: false });
promise.then(function(imResponse) {
// 取消置顶会话成功
const { conversationID } = imResponse.data; // 被取消置顶的会话 ID
}).catch(function(imError) {
console.warn('pinConversation error:', imError); // 取消置顶会话失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setAllMessageRead(options) → {Promise}
将所有会话的未读消息设置为已读 注意:v2.16.0 版本开始支持。
Examples
// 将所有会话的未读消息全部设置为已读
let promise = tim.setAllMessageRead(); // 等同于 tim.setAllMessageRead({scope: TIM.TYPES.READ_ALL_MSG})
promise.then(function(imResponse) {
// 已读上报成功,所有会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});
// 将所有 C2C 会话的未读消息全部设置为已读
let promise = tim.setAllMessageRead({scope: TIM.TYPES.READ_ALL_C2C_MSG});
promise.then(function(imResponse) {
// 已读上报成功,所有 C2C 会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});
// 将所有群会话的未读消息全部设置为已读
let promise = tim.setAllMessageRead({scope: TIM.TYPES.READ_ALL_GROUP_MSG});
promise.then(function(imResponse) {
// 已读上报成功,所有 C2C 会话的 unreadCount 属性值被置为0
}).catch(function(imError) {
// 已读上报失败
console.warn('setAllMessageRead error:', imError);
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setMessageRemindType(options) → {Promise}
设置会话消息提醒类型,您可以使用此接口实现“消息免打扰”,“拒收消息”的功能。
注意1:作为群成员,设置自己所在群的消息提示类型。
注意2:v2.16.0起,支持设置 C2C 会话的消息提示类型。
注意3:“消息免打扰”,一般的实现是在线接收消息,离线不接收消息(在有离线推送的情况下)。
注意4:“拒收消息”,即在线和离线都不接收消息,对端发送的消息可通过 getMessageList 获取到。
注意5:v2.19.1 起,该接口支持设置社群话题的消息提示类型,groupID 传入 topicID 即可,如果话题所属社群设置为 TIM.TYPES.MSG_REMIND_DISCARD,则会忽略话题的设置。
Examples
// 拒收群消息(通过 getMessageList 接口可拉取到其他群成员发送的消息)
let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_DISCARD });
promise.then(function(imResponse) {
// 设置成功后 SDK 会触发 TIM.EVENT.CONVERSATION_LIST_UPDATED 事件(遍历列表,并读取 Conversation.messageRemindType)
}).catch(function(imError) {
console.warn('setMessageRemindType error:', imError);
});
// 拒收群消息后,重新开启新消息提醒
let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_ACPT_AND_NOTE });
promise.then(function(imResponse) {
// 设置成功后 SDK 会触发 TIM.EVENT.CONVERSATION_LIST_UPDATED 事件(遍历列表,并读取 Conversation.messageRemindType)
}).catch(function(imError) {
console.warn('setMessageRemindType error:', imError);
});
// C2C 消息免打扰,一般的实现是在线接收消息,离线不接收消息(在有离线推送的情况下),v2.16.0起支持
let promise = tim.setMessageRemindType({ userIDList: ['user1', 'user2'], messageRemindType: TIM.TYPES.MSG_REMIND_ACPT_NOT_NOTE });
promise.then(function(imResponse) {
// 设置成功后 SDK 会触发 TIM.EVENT.CONVERSATION_LIST_UPDATED 事件(遍历列表,并读取 Conversation.messageRemindType)
const { successUserIDList, failureUserIDList } = imResponse.data;
// 删除成功的 userIDList
successUserIDList.forEach((item) => {
const { userID } = item;
});
// 删除失败的 userIDList
failureUserIDList.forEach((item) => {
const { userID, code, message } = item;
});
}).catch(function(imError) {
console.warn('setMessageRemindType error:', imError);
});
// 群消息免打扰,一般的实现是在线接收消息,离线不接收消息(在有离线推送的情况下)
let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_ACPT_NOT_NOTE });
promise.then(function(imResponse) {
// 设置消息免打扰成功
}).catch(function(imError) {
// 设置消息免打扰失败
console.warn('setMessageRemindType error:', imError);
});
// 社群话题消息免打扰,一般的实现是在线接收消息,离线不接收消息(在有离线推送的情况下)
let promise = tim.setMessageRemindType({ groupID: 'topicID', messageRemindType: TIM.TYPES.MSG_REMIND_ACPT_NOT_NOTE });
promise.then(function(imResponse) {
// 设置消息免打扰成功
}).catch(function(imError) {
// 设置消息免打扰失败
console.warn('setMessageRemindType error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getMyProfile() → {Promise}
获取个人资料
注意:v2.3.2版本开始支持自定义资料字段,使用前需要将SDK升级至v2.3.2或更高版本。
- See:
-
- 资料结构描述
Example
let promise = tim.getMyProfile();
promise.then(function(imResponse) {
console.log(imResponse.data); // 个人资料 - Profile 实例
}).catch(function(imError) {
console.warn('getMyProfile error:', imError); // 获取个人资料失败的相关信息
});
Returns:
- Type
- Promise
getUserProfile(options) → {Promise}
获取其他用户资料。此接口会同时获取标配资料和自定义资料,详细请参考 https://cloud.tencent.com/document/product/269/1500#.E8.B5.84.E6.96.99.E7.B3.BB.E7.BB.9F.E7.AE.80.E4.BB.8B
注意1:v2.3.2版本开始支持自定义资料字段,使用前需要将SDK升级至v2.3.2或更高版本。
注意2:如果您没有配置自定义资料字段,或者配置了自定义资料字段,但是没有设置 value,此接口将不会返回自定义资料的内容。
注意3:每次拉取的用户数不超过100,避免因回包数据量太大导致回包失败。如果传入的数组长度大于100,则只取前100个用户进行查询,其余丢弃。
Example
let promise = tim.getUserProfile({
userIDList: ['user1', 'user2'] // 请注意:即使只拉取一个用户的资料,也需要用数组类型,例如:userIDList: ['user1']
});
promise.then(function(imResponse) {
console.log(imResponse.data); // 存储用户资料的数组 - [Profile]
}).catch(function(imError) {
console.warn('getUserProfile error:', imError); // 获取其他用户资料失败的相关信息
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
搜索参数 Properties
|
Returns:
- Type
- Promise
updateMyProfile(options) → {Promise}
更新个人资料
注意:v2.3.2版本开始支持自定义资料字段,使用前需要将SDK升级至v2.3.2或更高版本。
Examples
// 修改个人标配资料
let promise = tim.updateMyProfile({
nick: '我的昵称',
avatar: 'http(s)://url/to/image.jpg',
gender: TIM.TYPES.GENDER_MALE,
selfSignature: '我的个性签名',
allowType: TIM.TYPES.ALLOW_TYPE_ALLOW_ANY
});
promise.then(function(imResponse) {
console.log(imResponse.data); // 更新资料成功
}).catch(function(imError) {
console.warn('updateMyProfile error:', imError); // 更新资料失败的相关信息
});
// 修改个人自定义资料
// 自定义资料字段需要预先在控制台配置,详细请参考:https://cloud.tencent.com/document/product/269/1500#.E8.87.AA.E5.AE.9A.E4.B9.89.E8.B5.84.E6.96.99.E5.AD.97.E6.AE.B5
let promise = tim.updateMyProfile({
// 这里要求您已在即时通信 IM 控制台>【应用配置】>【功能配置】 申请了自定义资料字段 Tag_Profile_Custom_Test1
// 注意!即使只有一个自定义资料字段,profileCustomField 也需要用数组类型
profileCustomField: [
{
key: 'Tag_Profile_Custom_Test1',
value: '我的自定义资料1'
}
]
});
promise.then(function(imResponse) {
console.log(imResponse.data); // 更新资料成功
}).catch(function(imError) {
console.warn('updateMyProfile error:', imError); // 更新资料失败的相关信息
});
// 修改个人标配资料和自定义资料
let promise = tim.updateMyProfile({
nick: '我的昵称',
// 这里要求您已在即时通信 IM 控制台>【应用配置】>【功能配置】 申请了自定义资料字段 Tag_Profile_Custom_Test1 和 Tag_Profile_Custom_Test2
profileCustomField: [
{
key: 'Tag_Profile_Custom_Test1',
value: '我的自定义资料1'
},
{
key: 'Tag_Profile_Custom_Test2',
value: '我的自定义资料2'
},
]
});
promise.then(function(imResponse) {
console.log(imResponse.data); // 更新资料成功
}).catch(function(imError) {
console.warn('updateMyProfile error:', imError); // 更新资料失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
资料参数 Properties
|
Returns:
- Type
- Promise
getBlacklist() → {Promise}
获取我的黑名单列表
Example
let promise = tim.getBlacklist();
promise.then(function(imResponse) {
console.log(imResponse.data); // 我的黑名单列表,结构为包含用户 userID 的数组 - [userID]
}).catch(function(imError) {
console.warn('getBlacklist error:', imError); // 获取黑名单列表失败的相关信息
});
Returns:
- Type
- Promise
addToBlacklist(options) → {Promise}
添加用户到黑名单列表。将用户加入黑名单后可以屏蔽来自 TA 的所有消息,因此该接口可以实现“屏蔽该用户消息”的功能。
- 如果用户 A 与用户 B 之间存在好友关系,拉黑时会解除双向好友关系。
- 如果用户 A 与用户 B 之间存在黑名单关系,二者之间无法发起会话。
- 如果用户 A 与用户 B 之间存在黑名单关系,二者之间无法发起加好友请求。
Example
let promise = tim.addToBlacklist({userIDList: ['user1', 'user2']}); // 请注意:即使只添加一个用户帐号到黑名单,也需要用数组类型,例如:userIDList: ['user1']
promise.then(function(imResponse) {
console.log(imResponse.data); // 成功添加到黑名单的账号信息,结构为包含用户 userID 的数组 - [userID]
}).catch(function(imError) {
console.warn('addToBlacklist error:', imError); // 添加用户到黑名单列表失败的相关信息
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
removeFromBlacklist(options) → {Promise}
从黑名单列表中移除,即解除拉黑。
Example
let promise = tim.removeFromBlacklist({userIDList: ['user1', 'user2']}); // 请注意:即使只从黑名单中移除一个用户帐号,也需要用数组类型,例如:userIDList: ['user1']
promise.then(function(imResponse) {
console.log(imResponse.data); // 从黑名单中成功移除的账号列表,结构为包含用户 userID 的数组 - [userID]
}).catch(function(imError) {
console.warn('removeFromBlacklist error:', imError); // 将用户从黑名单中移除失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
options |
Object |
参数选项 |
option.userIDList |
Array.<String> |
待从黑名单中移除的 userID 列表,单次请求的 userID 数不得超过1000 |
Returns:
注意 checkType 的使用需要注意:
- Type
- Promise
getFriendList() → {Promise}
获取 SDK 缓存的好友列表。当好友列表有更新时,SDK 会派发事件 TIM.EVENT.FRIEND_LIST_UPDATED
注意:v2.13.0起支持,升级指引
Example
let promise = tim.getFriendList();
promise.then(function(imResponse) {
const friendList = imResponse.data; // 好友列表
}).catch(function(imError) {
console.warn('getFriendList error:', imError); // 获取好友列表失败的相关信息
});
Returns:
- Type
- Promise
addFriend(options) → {Promise}
添加好友
注意:v2.13.0起支持,升级指引
Example
// 添加好友
let promise = tim.addFriend({
to: 'user1',
source: 'AddSource_Type_Web',
remark: '小橙子',
groupName: '好友',
wording: '我是 user0',
type: TIM.TYPES.SNS_ADD_TYPE_BOTH,
});
promise.then(function(imResponse) {
// 添加好友的请求发送成功
const { code } = imResponse.data;
if (code === 30539) {
// 30539 说明 user1 设置了【需要经过自己确认对方才能添加自己为好友】,此时 SDK 会触发 TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
} else if (code === 0) {
// 0 说明 user1 设置了【允许任何人添加自己为好友】,此时 SDK 会触发 TIM.EVENT.FRIEND_LIST_UPDATED 事件
}
}).catch(function(imError) {
console.warn('addFriend error:', imError); // 添加好友失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteFriend(options) → {Promise}
删除好友,支持单向删除好友和双向删除好友
注意1:v2.13.0起支持,升级指引 注意2:userID 建议一次最大 100 个,因为数量过多可能会导致数据包太大被后台拒绝,后台限制数据包最大为 1M
Example
let promise = tim.deleteFriend({
userIDList: ['user1','user2'],
type: TIM.TYPES.SNS_DELETE_TYPE_BOTH
});
promise.then(function(imResponse) {
const { successUserIDList, failureUserIDList } = imResponse.data;
// 删除成功的 userIDList
successUserIDList.forEach((item) => {
const { userID } = item;
});
// 删除失败的 userIDList
failureUserIDList.forEach((item) => {
const { userID, code, message } = item;
});
// 如果好友列表有变化,则 SDK 会触发 TIM.EVENT.FRIEND_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('removeFromFriendList error:', imError);
});
Parameters:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
checkFriend(options) → {Promise}
校验好友关系
注意:v2.13.0起支持,升级指引
Example
let promise = tim.checkFriend({
userIDList: ['user0','user1'],
type: TIM.TYPES.SNS_CHECK_TYPE_BOTH,
});
promise.then(function(imResponse) {
const { successUserIDList, failureUserIDList } = imResponse.data;
// 校验成功的 userIDList
successUserIDList.forEach((item) => {
const { userID, code, relation } = item; // 此时 code 始终为0
// 单向校验好友关系时可能的结果有:
// - relation: TIM.TYPES.SNS_TYPE_NO_RELATION A 的好友表中没有 B,但无法确定 B 的好友表中是否有 A
// - relation: TIM.TYPES.SNS_TYPE_A_WITH_B A 的好友表中有 B,但无法确定 B 的好友表中是否有 A
// 双向校验好友关系时可能的结果有:
// - relation: TIM.TYPES.SNS_TYPE_NO_RELATION A 的好友表中没有 B,B 的好友表中也没有 A
// - relation: TIM.TYPES.SNS_TYPE_A_WITH_B A 的好友表中有 B,但 B 的好友表中没有 A
// - relation: TIM.TYPES.SNS_TYPE_B_WITH_A A 的好友表中没有 B,但 B 的好友表中有 A
// - relation: TIM.TYPES.SNS_TYPE_BOTH_WAY A 的好友表中有 B,B 的好友表中也有 A
});
// 校验失败的 userIDList
failureUserIDList.forEach((item) => {
const { userID, code, message } = item;
});
}).catch(function(imError) {
console.warn('checkFriend error:', imError);
});
Parameters:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getFriendProfile(options) → {Promise}
获取指定好友的好友数据和资料数据,包括标配好友字段和标配资料字段,也支持拉取自定义好友字段和自定义资料字段。
注意:v2.13.0起支持,升级指引
Example
let promise = tim.getFriendProfile({
userIDList: ['user0','user1']
});
promise.then(function(imResponse) {
const { friendList, failureUserIDList } = imResponse.data;
friendList.forEach((friend) => {
// Friend 对象
});
// 失败的 userIDList
failureUserIDList.forEach((item) => {
const { userID, code, message } = item;
});
}).catch(function(imError) {
console.warn('getFriendProfile error:', imError); // 获取失败
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
updateFriend(options) → {Promise}
更新好友的关系链数据,只支持好友备注、关系链自定义字段的更新操作。
注意!
- v2.13.0起支持,升级指引
- 更新好友分组,请使用 addToFriendGroup 和 removeFromFriendGroup 接口
Examples
// 更新好友备注
let promise = tim.updateFriend({
userID: 'user1',
remark: 'helloworld'
});
promise.then(function(imResponse) {
console.log(imResponse.data); // Friend 实例
}).catch(function(imError) {
console.warn('getFriendProfile error:', imError); // 更新失败
});
// 更新好友自定义字段
let promise = tim.updateFriend({
userID: 'user1',
friendCustomField: [
// 好友自定义字段必须以 Tag_SNS_Custom 为前缀
{ key: 'Tag_SNS_Custom_test1', value: 'hello' },
{ key: 'Tag_SNS_Custom_test2', value: 'world' },
]
});
promise.then(function(imResponse) {
console.log(imResponse.data); // Friend 实例
}).catch(function(imError) {
console.warn('getFriendProfile error:', imError); // 更新失败
});
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getFriendApplicationList() → {Promise}
获取 SDK 缓存的好友申请列表。当好友申请列表有更新时,SDK 会派发事件 TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED
注意:v2.13.0起支持,升级指引
Example
let promise = tim.getFriendApplicationList();
promise.then(function(imResponse) {
// friendApplicationList - 好友申请列表 - [FriendApplication]
// unreadCount - 好友申请的未读数
// const { friendApplicationList, unreadCount } = imResponse.data;
}).catch(function(imError) {
console.warn('getFriendApplicationList error:', imError); // 获取好友申请列表失败的相关信息
});
Returns:
- Type
- Promise
acceptFriendApplication(options) → {Promise}
同意好友申请
注意:v2.13.0起支持,升级指引
Example
let promise = tim.acceptFriendApplication({
userID: 'user1',
remark: '客服小亮',
type: TIM.TYPES.SNS_APPLICATION_AGREE_AND_ADD
});
promise.then(function(imResponse) {
// 同意好友成功后,SDK 会触发 TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('acceptFriendApplication error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
refuseFriendApplication(options) → {Promise}
拒绝好友申请
注意:v2.13.0起支持,升级指引
Example
let promise = tim.refuseFriendApplication({
userID: 'user1',
});
promise.then(function(imResponse) {
// 拒绝成功后,SDK 会触发 TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('refuseFriendApplication error:', imError);
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteFriendApplication(options) → {Promise}
删除好友申请
注意:v2.13.0起支持,升级指引
Example
let promise = tim.deleteFriendApplication({
userID: 'user1',
type: TIM.TYPES.SNS_APPLICATION_SENT_TO_ME
});
promise.then(function(imResponse) {
// 删除成功后,SDK 会触发 TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('deleteFriendApplication error:', imError);
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setFriendApplicationRead() → {Promise}
上报好友申请已读
注意:v2.13.0起支持,升级指引
Example
// 上报好友申请已读
let promise = tim.setFriendApplicationRead();
promise.then(function(imResponse) {
// 已读上报成功
}).catch(function(imError) {
console.warn('setFriendApplicationRead error:', imError);
});
Returns:
- Type
- Promise
getFriendGroupList() → {Promise}
获取 SDK 缓存的好友分组列表。当好友分组列表有更新时,SDK 会派发事件 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED
注意:v2.13.0起支持,升级指引
Example
let promise = tim.getFriendGroupList();
promise.then(function(imResponse) {
const friendGroupList = imResponse.data; // 好友分组列表
}).catch(function(imError) {
console.warn('getFriendGroupList error:', imError); // 获取好友分组列表失败的相关信息
});
Returns:
- Type
- Promise
createFriendGroup(options) → {Promise}
创建好友分组
注意:v2.13.0起支持,升级指引
Example
let promise = tim.createFriendGroup({
name: '我的好友分组1',
userIDList: ['user0','user1']
});
promise.then(function(imResponse) {
const { friendGroup,failureUserIDList } = imResponse;
// friendGroup - 好友分组实例
// failureUserIDList - 失败的 userID 列表
// 创建成功后,SDK 会触发 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('getFriendGroupInfo error:', imError); // 获取失败
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteFriendGroup(options) → {Promise}
删除好友分组
注意:v2.13.0起支持,升级指引
Example
let promise = tim.deleteFriendGroup({
name: '我的好友分组1',
});
promise.then(function(imResponse) {
console.log(imResponse.data); // 被删除的分组实例
// 删除成功后,SDK 会触发 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('deleteFriendGroup error:', imError); // 获取失败
});
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
addToFriendGroup(options) → {Promise}
添加好友到分组列表
注意:v2.13.0起支持,升级指引
Example
let promise = tim.addToFriendGroup({
name: '我的好友分组1',
userIDList: ['user1','user2'],
});
promise.then(function(imResponse) {
const { friendGroup, failureUserIDList } = imResponse.data;
// friendGroup - 好友分组实例
// failureUserIDList - 失败的 userID 列表
// 添加成功后,SDK 会触发 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('addToFriendGroup error:', imError); // 获取失败
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
removeFromFriendGroup(options) → {Promise}
从好友分组移除好友
注意:v2.13.0起支持,升级指引
Example
let promise = tim.removeFromFriendGroup({
name: '我的好友分组1',
userIDList: ['user1','user2'],
});
promise.then(function(imResponse) {
const { friendGroup, failureUserIDList } = imResponse.data;
// friendGroup - 好友分组实例
// failureUserIDList - 失败的 userID 列表
// 移除成功后,SDK 会触发 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('addToFriendGroup error:', imError); // 获取失败
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
renameFriendGroup(options) → {Promise}
修改好友分组的名称
注意:v2.13.0起支持,升级指引
Example
let promise = tim.renameFriendGroup({
oldName: '好友',
newName: '闺蜜'
});
promise.then(function(imResponse) {
console.log(imResponse.data); // FriendGroup 实例
// 修改成功后,SDK 会触发 TIM.EVENT.FRIEND_GROUP_LIST_UPDATED 事件
}).catch(function(imError) {
console.warn('updateMyProfile error:', imError);
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getGroupList(options) → {Promise}
需要渲染或刷新【我的群组列表】时,调用该接口获取群组列表,更多详情请参见 Group。
注意:接口返回的群组列表,不包含 TIM.TYPES.GRP_AVCHATROOM(直播群)类型的群组。
- See:
Examples
// 该接口默认只会拉取这些资料:群类型、群名称、群头像、最后一条消息的时间。
let promise = tim.getGroupList();
promise.then(function(imResponse) {
console.log(imResponse.data.groupList); // 群组列表
}).catch(function(imError) {
console.warn('getGroupList error:', imError); // 获取群组列表失败的相关信息
});
// 若默认拉取的字段不满足需求,可以参考下述代码,拉取额外的资料字段。
let promise = tim.getGroupList({
groupProfileFilter: [TIM.TYPES.GRP_PROFILE_OWNER_ID],
});
promise.then(function(imResponse) {
console.log(imResponse.data.groupList); // 群组列表
}).catch(function(imError) {
console.warn('getGroupList error:', imError); // 获取群组列表失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
请求参数 Properties
|
Returns:
- Type
- Promise
getGroupProfile(options) → {Promise}
获取群详细资料
- See:
Example
let promise = tim.getGroupProfile({ groupID: 'group1', groupCustomFieldFilter: ['key1','key2'] });
promise.then(function(imResponse) {
console.log(imResponse.data.group);
}).catch(function(imError) {
console.warn('getGroupProfile error:', imError); // 获取群详细资料失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
createGroup(options) → {Promise}
创建群组
注意1:该接口创建 TIM.TYPES.GRP_AVCHATROOM(直播群) 后,需调用 joinGroup 接口加入群组后,才能进行消息收发流程。
注意2:v2.19.1 起,该接口可以创建支持话题的社群。
Examples
// 创建好友工作群
let promise = tim.createGroup({
type: TIM.TYPES.GRP_WORK,
name: 'WebSDK',
memberList: [{
userID: 'user1',
// 群成员维度的自定义字段,默认情况是没有的,需要开通,详情请参阅自定义字段
memberCustomField: [{key: 'group_member_test', value: 'test'}]
}, {
userID: 'user2'
}] // 如果填写了 memberList,则必须填写 userID
});
promise.then(function(imResponse) { // 创建成功
console.log(imResponse.data.group); // 创建的群的资料
// 创建群时指定了成员列表,但是成员中存在超过了“单个用户可加入群组数”限制的情况
// 一个用户 userX 最多允许加入 N 个群,如果已经加入了 N 个群,此时创建群再指定 userX 为群成员,则 userX 不能正常加群
// SDK 将 userX 的信息放入 overLimitUserIDList,供接入侧处理
console.log(imResponse.data.overLimitUserIDList); // 超过了“单个用户可加入群组数”限制的用户列表,v2.10.2起支持
}).catch(function(imError) {
console.warn('createGroup error:', imError); // 创建群组失败的相关信息
});
// 创建支持话题的社群
let promise = tim.createGroup({
type: TIM.TYPES.GRP_COMMUNITY,
name: 'WebSDK',
isSupportTopic: true,
});
promise.then(function(imResponse) { // 创建成功
console.log(imResponse.data.group); // 创建的群的资料
}).catch(function(imError) {
console.warn('createGroup error:', imError); // 创建群组失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数集 Properties
|
Returns:
- Type
- Promise
dismissGroup(groupID) → {Promise}
群主可调用该接口解散群组。
注意:群主不能解散好友工作群。
Example
let promise = tim.dismissGroup('group1');
promise.then(function(imResponse) { // 解散成功
console.log(imResponse.data.groupID); // 被解散的群组 ID
}).catch(function(imError) {
console.warn('dismissGroup error:', imError); // 解散群组失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
groupID |
String |
群组 ID |
Returns:
- Type
- Promise
updateGroupProfile(options) → {Promise}
修改群组资料
Examples
let promise = tim.updateGroupProfile({
groupID: 'group1',
name: 'new name', // 修改群名称
introduction: 'this is introduction.', // 修改群简介
// v2.6.0 起,群成员能收到群自定义字段变更的群提示消息,且能获取到相关的内容,详见 Message.payload.newGroupProfile.groupCustomField
groupCustomField: [{ key: 'group_level', value: 'high'}] // 修改群组维度自定义字段
});
promise.then(function(imResponse) {
console.log(imResponse.data.group) // 修改成功后的群组详细资料
}).catch(function(imError) {
console.warn('updateGroupProfile error:', imError); // 修改群组资料失败的相关信息
});
// v2.6.2 起,提供了全体禁言和取消禁言的功能。目前群全体禁言后,不支持下发群提示消息。
let promise = tim.updateGroupProfile({
groupID: 'group1',
muteAllMembers: true, // true 表示全体禁言,false表示取消全体禁言
});
promise.then(function(imResponse) {
console.log(imResponse.data.group) // 修改成功后的群组详细资料
}).catch(function(imError) {
console.warn('updateGroupProfile error:', imError); // 修改群组资料失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
请求参数 Properties
|
Returns:
- Type
- Promise
joinGroup(options) → {Promise}
申请加群的接口,申请加入某个群组时调用。
注意:
- 好友工作群不允许申请加群,只能通过 addGroupMember 方式添加
- TIM.TYPES.GRP_AVCHATROOM(直播群)有两种加群方式:
2.1 正常加群,即登录加群。此时 SDK 内的所有接口都能正常调用。
2.2 匿名加群,即不登录加群。此时只能收消息,其他任何需要鉴权的接口都不能调用。 - 只有 TIM.TYPES.GRP_AVCHATROOM(直播群) 支持匿名加群,其他类型的群组不支持。
- 同一用户同时只能加入一个直播群。【例如】用户已在直播群 A 中,再加入直播群 B,SDK 会先退出直播群 A,然后加入直播群 B
- See:
Example
let promise = tim.joinGroup({ groupID: 'group1', type: TIM.TYPES.GRP_AVCHATROOM });
promise.then(function(imResponse) {
switch (imResponse.data.status) {
case TIM.TYPES.JOIN_STATUS_WAIT_APPROVAL: // 等待管理员同意
break;
case TIM.TYPES.JOIN_STATUS_SUCCESS: // 加群成功
console.log(imResponse.data.group); // 加入的群组资料
break;
case TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: // 已经在群中
break;
default:
break;
}
}).catch(function(imError){
console.warn('joinGroup error:', imError); // 申请加群失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
quitGroup(groupID) → {Promise}
退出群组。
注意:群主只能退出好友工作群,退出后该好友工作群无群主。
Example
let promise = tim.quitGroup('group1');
promise.then(function(imResponse) {
console.log(imResponse.data.groupID); // 退出成功的群 ID
}).catch(function(imError){
console.warn('quitGroup error:', imError); // 退出群组失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
groupID |
String |
群组 ID |
Returns:
成功时 then 回调参数中包含退出的群组 ID
- Type
- Promise
searchGroupByID(groupID) → {Promise}
通过 groupID 搜索群组。
注意:TIM.TYPES.GRP_WORK 类型的群组(好友工作群)不能被搜索。
- See:
Example
let promise = tim.searchGroupByID('group1');
promise.then(function(imResponse) {
const group = imResponse.data.group; // 群组信息
}).catch(function(imError) {
console.warn('searchGroupByID error:', imError); // 搜素群组失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
groupID |
String |
群组 ID |
Returns:
- Type
- Promise
getGroupOnlineMemberCount(groupID) → {Promise}
获取群在线人数,此接口只用于查询直播群在线人数。
注意:当不在直播群内或非直播群使用此API查询人数时,SDK 返回的 memberCount 为0。调用此接口查询直播群人数的的频率建议控制在5~10秒一次。
- See:
Example
// v2.8.0起,支持查询直播群在线人数
let promise = tim.getGroupOnlineMemberCount('group1');
promise.then(function(imResponse) {
console.log(imResponse.data.memberCount);
}).catch(function(imError) {
console.warn('getGroupOnlineMemberCount error:', imError); // 获取直播群在线人数失败的相关信息
});
Parameters:
Name | Type | Description |
---|---|---|
groupID |
String |
群组ID |
Returns:
- Type
- Promise
changeGroupOwner(options) → {Promise}
转让群组。只有群主有权限操作。
注意:只有群主拥有转让的权限。TIM.TYPES.GRP_AVCHATROOM(直播群)类型的群组不能转让。
- See:
Example
let promise = tim.changeGroupOwner({
groupID: 'group1',
newOwnerID: 'user2'
});
promise.then(function(imResponse) { // 转让成功
console.log(imResponse.data.group); // 群组资料
}).catch(function(imError) { // 转让失败
console.warn('changeGroupOwner error:', imError); // 转让群组失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
handleGroupApplication(options) → {Promise}
处理申请加群(同意或拒绝)
注意:如果一个群有多位管理员,当有人申请加群时,所有在线的管理员都会收到申请加群的群系统通知。如果某位管理员处理了这个申请(同意或者拒绝),则其他管理员无法重复处理(即不能修改处理的结果)。
- See:
Example
let promise = tim.handleGroupApplication({
handleAction: 'Agree',
handleMessage: '欢迎欢迎',
message: message // 申请加群群系统通知的消息实例
});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 群组资料
}).catch(function(imError){
console.warn('handleGroupApplication error:', imError); // 错误信息
});
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
initGroupAttributes(options) → {Promise}
初始化群属性。业务侧需要根据应用场景控制该接口的操作权限。
注意1:v2.14.0起支持。
注意2:该接口仅适用于直播群,非直播群调用此接口将返回2641错误码。
注意3:该接口使用前必须先调用 joinGroup 加入直播群,未加入直播群调用此接口将返回2642错误码。
注意4:群属性 key 最多支持 16 个,大小限制为 32 字节;value 大小限制为 4k;总的 groupAttributes(包括 key 和 value)大小限制为 16k。
Example
let promise = tim.initGroupAttributes({
groupID: 'group1',
groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) { // 初始化成功
console.log(imResponse.data.groupAttributes); // 初始化成功的群属性
}).catch(function(imError) { // 初始化失败
console.warn('initGroupAttributes error:', imError); // 初始化群属性失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setGroupAttributes(options) → {Promise}
设置群属性。
注意1:v2.14.0起支持。
注意2:该接口仅适用于直播群,非直播群调用此接口将返回2641错误码。
注意3:该接口使用前必须先调用 joinGroup 加入直播群,未加入直播群调用此接口将返回2642错误码。
Example
let promise = tim.setGroupAttributes({
groupID: 'group1',
groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) { // 设置成功
console.log(imResponse.data.groupAttributes); // 设置成功的群属性
}).catch(function(imError) { // 设置失败
console.warn('setGroupAttributes error:', imError); // 设置群属性失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteGroupAttributes(options) → {Promise}
删除群属性。
注意1:v2.14.0起支持。
注意2:该接口仅适用于直播群,非直播群调用此接口将返回2641错误码。
注意3:该接口使用前必须先调用 joinGroup 加入直播群,未加入直播群调用此接口将返回2642错误码。
注意4:keyList 传入非空数组表示删除指定的群属性 key-value,传入空数组表示删除全部群属性。
Examples
// 删除指定的群属性 key-value
let promise = tim.deleteGroupAttributes({
groupID: 'group1',
keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // 删除成功
console.log(imResponse.data.keyList); // 删除成功的群属性 key 列表
}).catch(function(imError) { // 删除失败
console.warn('deleteGroupAttributes error:', imError); // 删除群属性失败的相关信息
});
// 删除全部群属性
let promise = tim.deleteGroupAttributes({
groupID: 'group1',
keyList: []
});
promise.then(function(imResponse) { // 删除成功
console.log(imResponse.data.keyList); // 删除成功的群属性 key 列表
}).catch(function(imError) { // 删除失败
console.warn('deleteGroupAttributes error:', imError); // 删除群属性失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getGroupAttributes(options) → {Promise}
获取群属性。
注意1:v2.14.0起支持。
注意2:该接口仅适用于直播群,非直播群调用此接口将返回2641错误码。
注意3:该接口使用前必须先调用 joinGroup 加入直播群,未加入直播群调用此接口将返回2642错误码。
注意4:keyList 传入非空数组表示获取指定的群属性,传入空数组表示获取全部群属性。
Examples
// 获取指定的群属性
let promise = tim.getGroupAttributes({
groupID: 'group1',
keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // 获取成功
console.log(imResponse.data.groupAttributes); // 指定 key 的群属性
}).catch(function(imError) { // 获取失败
console.warn('getGroupAttributes error:', imError); // 获取群属性失败的相关信息
});
// 获取全部群属性
let promise = tim.getGroupAttributes({
groupID: 'group1',
keyList: []
});
promise.then(function(imResponse) { // 获取成功
console.log(imResponse.data.groupAttributes); // 全部群属性
}).catch(function(imError) { // 获取失败
console.warn('getGroupAttributes error:', imError); // 获取群属性失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getGroupMemberList(options) → {Promise}
获取群成员列表。
注意1:从v2.6.2起,该接口支持拉取群成员禁言截止时间戳(muteUntil),接入侧可根据此值判断群成员是否被禁言,以及禁言的剩余时间。
在低于v2.6.2的版本,该接口获取的群成员列表中的资料是不完整的(仅包括头像、昵称等,能够满足群成员列表的渲染需求),若要查询群成员禁言截止时间戳(muteUntil)等详细资料,请使用:getGroupMemberProfile
注意2:该接口是分页拉取群成员,不能直接用于获取群的总人数。获取群的总人数(memberNum)请使用:getGroupProfile
- See:
Examples
let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
promise.then(function(imResponse) {
console.log(imResponse.data.memberList); // 群成员列表
}).catch(function(imError) {
console.warn('getGroupMemberList error:', imError);
});
// 从v2.6.2 起,该接口支持拉取群成员禁言截止时间戳。
let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // 从0开始拉取30个群成员
promise.then(function(imResponse) {
console.log(imResponse.data.memberList); // 群成员列表
for (let groupMember of imResponse.data.memberList) {
if (groupMember.muteUntil * 1000 > Date.now()) {
console.log(`${groupMember.userID} 禁言中`);
} else {
console.log(`${groupMember.userID} 未被禁言`);
}
}
}).catch(function(imError) {
console.warn('getGroupMemberProfile error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
请求参数 Properties
|
Returns:
- Type
- Promise
getGroupMemberProfile(options) → {Promise}
获取群成员资料,如禁言时间等。
注意1:使用该接口前,需要将SDK版本升级至v2.2.0或更高版本。
注意2:每次查询的用户数上限是50。如果传入的数组长度大于50,则只取前50个用户进行查询,其余丢弃。
- See:
Example
let promise = tim.getGroupMemberProfile({
groupID: 'group1',
userIDList: ['user1', 'user2'], // 请注意:即使只拉取一个群成员的资料,也需要用数组类型,例如:userIDList: ['user1']
memberCustomFieldFilter: ['group_member_custom'], // 筛选群成员自定义字段:group_member_custom
});
promise.then(function(imResponse) {
console.log(imResponse.data.memberList); // 群成员列表
}).catch(function(imError) {
console.warn('getGroupMemberProfile error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
请求参数 Properties
|
Returns:
返回Promise对象
- Type
- Promise
addGroupMember(options) → {Promise}
添加群成员。详细规则如下:
- TIM.TYPES.GRP_WORK(好友工作群):任何群成员都可邀请他人加群,且无需被邀请人同意,直接将其拉入群组中。
- TIM.TYPES.GRP_PUBLIC(陌生人社交群)/ TIM.TYPES.GRP_MEETING(临时会议群):只有 App 管理员可通过 REST API add_group_member 邀请他人入群,且无需被邀请人同意,直接将其拉入群组中。
- TIM.TYPES.GRP_AVCHATROOM(直播群):不允许任何人邀请他人入群(包括 App 管理员)。
- See:
Example
let promise = tim.addGroupMember({groupID: 'group1', userIDList: ['user1','user2','user3']});
promise.then(function(imResponse) {
console.log(imResponse.data.successUserIDList); // 添加成功的群成员 userIDList
console.log(imResponse.data.failureUserIDList); // 添加失败的群成员 userIDList
console.log(imResponse.data.existedUserIDList); // 已在群中的群成员 userIDList
// 一个用户 userX 最多允许加入 N 个群,如果已经加入了 N 个群,此时再尝试添加 userX 为群成员,则 userX 不能正常加群
// SDK 将 userX 的信息放入 overLimitUserIDList,供接入侧处理
console.log(imResponse.data.overLimitUserIDList); // 超过了“单个用户可加入群组数”限制的用户列表,v2.10.2起支持
console.log(imResponse.data.group); // 添加后的群组信息
}).catch(function(imError) {
console.warn('addGroupMember error:', imError); // 错误信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteGroupMember(options) → {Promise}
删除群成员。群主可移除群成员。
- See:
Example
let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: '你违规了,我要踢你!'});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 删除后的群组信息
console.log(imResponse.data.userIDList); // 被删除的群成员的 userID 列表
}).catch(function(imError) {
console.warn('deleteGroupMember error:', imError); // 错误信息
});
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setGroupMemberMuteTime(options) → {Promise}
设置群成员的禁言时间,可以禁言群成员,也可取消禁言。TIM.TYPES.GRP_WORK 类型的群组(即好友工作群)不能禁言。
注意1:只有群主和管理员拥有该操作权限:
- 群主可以禁言/取消禁言管理员和普通群成员。
- 管理员可以禁言/取消禁言普通群成员。
注意2: v2.19.1 起,支持设置社群成员在话题中的禁言时间,groupID 传入 topicID 即可。
- See:
Examples
let promise = tim.setGroupMemberMuteTime({
groupID: 'group1',
userID: 'user1',
muteTime: 600 // 禁言10分钟;设为0,则表示取消禁言
});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 修改后的群资料
console.log(imResponse.data.member); // 修改后的群成员资料
}).catch(function(imError) {
console.warn('setGroupMemberMuteTime error:', imError); // 禁言失败的相关信息
});
// 设置群成员在话题中的禁言时间
let promise = tim.setGroupMemberMuteTime({
groupID: 'topicID',
userID: 'user1',
muteTime: 600 // 禁言10分钟;设为0,则表示取消禁言
});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 修改后的群资料
console.log(imResponse.data.member); // 修改后的群成员资料
}).catch(function(imError) {
console.warn('setGroupMemberMuteTime error:', imError); // 禁言失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setGroupMemberRole(options) → {Promise}
修改群成员角色。只有群主拥有操作的权限。
- See:
Example
let promise = tim.setGroupMemberRole({
groupID: 'group1',
userID: 'user1',
role: TIM.TYPES.GRP_MBR_ROLE_ADMIN // 将群 ID: group1 中的用户:user1 设为管理员
});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 修改后的群资料
console.log(imResponse.data.member); // 修改后的群成员资料
}).catch(function(imError) {
console.warn('setGroupMemberRole error:', imError); // 错误信息
});
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setGroupMemberNameCard(options) → {Promise}
设置群成员名片。
注意!直播群不存储群成员信息,所以此接口不适用于直播群。
- 群主:可设置所有群成员的名片。
- 管理员:可设置自身和其他普通群成员的群名片。
- 普通群成员:只能设置自身群名片。
- See:
Example
let promise = tim.setGroupMemberNameCard({ groupID: 'group1', userID: 'user1', nameCard: '用户名片' });
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 设置后的群资料
console.log(imResponse.data.member); // 修改后的群成员资料
}).catch(function(imError) {
console.warn('setGroupMemberNameCard error:', imError); // 设置群成员名片失败的相关信息
});
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
setGroupMemberCustomField(options) → {Promise}
设置群成员自定义字段。
注意:普通群成员只能设置自己的自定义字段。
- See:
Example
let promise = tim.setGroupMemberCustomField({ groupID: 'group1', memberCustomField: [{key: 'group_member_test', value: 'test'}]});
promise.then(function(imResponse) {
console.log(imResponse.data.group); // 修改后的群资料
console.log(imResponse.data.member); // 修改后的群成员资料
}).catch(function(imError) {
console.warn('setGroupMemberCustomField error:', imError); // 设置群成员自定义字段失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getJoinedCommunityList() → {Promise}
获取支持话题的社群列表。
注意:v2.19.1 起支持,该接口仅适用于获取支持话题的社群。
Example
// 获取支持话题的社群列表
let promise = tim.getJoinedCommunityList();
promise.then(function(imResponse) { // 获取成功
console.log(imResponse.data.groupList); // 支持话题的社群列表
}).catch(function(imError) { // 获取失败
console.warn('getJoinedCommunityList error:', imError); // 失败的相关信息
});
Returns:
- Type
- Promise
createTopicInCommunity(options) → {Promise}
创建话题。
注意1:v2.19.1 起支持,该接口仅适用于支持话题的社群。
注意2:调用该接口前必须先调用 createGroup 创建支持话题的社群。
Examples
// 创建话题
let promise = tim.createTopicInCommunity({
groupID: 'group1',
topicName: 'test',
avatar: 'xxx'
notification: 'xxx',
introduction: 'xxx',
customData: 'xxxx',
});
promise.then(function(imResponse) { // 创建成功
console.log(imResponse.data.topicID); // 话题 ID
}).catch(function(imError) { // 创建失败
console.warn('createTopicInCommunity error:', imError); // 创建话题失败的相关信息
});
// 向话题(Topic)发消息,v2.19.1 起支持
let message = tim.createTextMessage({
to: '@TGS#_@TGS#cWWFWHIM62CL@TOPIC#_@TOPIC#cXWFWHIM62CR', // 话题 ID
conversationType: TIM.TYPES.CONV_GROUP,
payload: {
text: 'Hello world!'
},
});
// 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
deleteTopicFromCommunity(options) → {Promise}
删除话题。
注意:v2.19.1 起支持,该接口仅适用于支持话题的社群。
Examples
// 删除某个社群下指定话题
let promise = tim.deleteTopicFromCommunity({
groupID: 'group1',
topicIDList: ['topicID'],
});
promise.then(function(imResponse) { // 删除成功
const { successTopicList, failureTopicList } = imResponse.data;
// 删除成功的话题列表
successTopicList.forEach((item) => {
const { topicID } = item;
});
// 删除失败的话题列表
failureTopicList.forEach((item) => {
const { topicID, code, message } = item;
})
}).catch(function(imError) { // 删除失败
console.warn('deleteTopicFromCommunity error:', imError); // 删除话题失败的相关信息
});
// 删除某个社群下所有话题
let promise = tim.deleteTopicFromCommunity({
groupID: 'group1',
});
promise.then(function(imResponse) { // 删除成功
const { successTopicList, failureTopicList } = imResponse.data;
// 删除成功的话题列表
successTopicList.forEach((item) => {
const { topicID } = item;
});
// 删除失败的话题列表
failureTopicList.forEach((item) => {
const { topicID, code, message } = item;
})
}).catch(function(imError) { // 删除失败
console.warn('deleteTopicFromCommunity error:', imError); // 删除话题失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
updateTopicProfile(options) → {Promise}
更新话题资料。
注意1:v2.19.1 起支持,该接口仅适用于支持话题的社群。
注意2:话题内其他成员可以收到 TIM.EVENT.TOPIC_UPDATED 事件。
Example
// 更新话题资料
let promise = tim.updateTopicProfile({
groupID: 'group1',
topicID: 'topic1',
topicName: 'test',
avatar: 'xxx'
notification: 'xxx',
introduction: 'xxx',
customData: 'xxxx',
muteAllMembers: true
});
promise.then(function(imResponse) { // 设置话题资料成功
console.log(imResponse.data.topic); // 返回修改后的话题资料
}).catch(function(imError) { // 设置话题资料失败
console.warn('updateTopicProfile error:', imError); // 设置话题资料失败的相关信息
});
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise
getTopicList(options) → {Promise}
获取话题列表。
注意:v2.19.1 起支持,该接口仅适用于支持话题的社群。
Examples
// 获取指定的话题
let promise = tim.getTopicList({
groupID: 'group1',
topicIDList: ['topicID'],
});
promise.then(function(imResponse) { // 获取成功
const { successTopicList, failureTopicList } = imResponse.data;
// 获取成功的话题列表
successTopicList.forEach((item) => {
const { topicID } = item;
});
// 获取失败的话题列表
failureTopicList.forEach((item) => {
const { topicID, code, message } = item;
})
}).catch(function(imError) { // 获取失败
console.warn('getTopicList error:', imError); // 获取话题列表失败的相关信息
});
// 获取全部的话题
let promise = tim.getTopicList({
groupID: 'group1',
});
promise.then(function(imResponse) { // 获取成功
const { successTopicList, failureTopicList } = imResponse.data;
// 获取成功的话题列表
successTopicList.forEach((item) => {
const { topicID } = item;
});
// 获取失败的话题列表
failureTopicList.forEach((item) => {
const { topicID, code, message } = item;
})
}).catch(function(imError) { // 获取失败
console.warn('getTopicList error:', imError); // 获取话题列表失败的相关信息
});
// 向话题(Topic)发消息,v2.19.1 起支持
let message = tim.createTextMessage({
to: '@TGS#_@TGS#cWWFWHIM62CL@TOPIC#_@TOPIC#cXWFWHIM62CR', // 话题 ID
conversationType: TIM.TYPES.CONV_GROUP,
payload: {
text: 'Hello world!'
},
});
// 发送消息
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
// 发送成功
console.log(imResponse);
}).catch(function(imError) {
// 发送失败
console.warn('sendMessage error:', imError);
});
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
参数选项 Properties
|
Returns:
- Type
- Promise