SDK

SDK

即时通信 IM SDK 基本概念:

基本概念 说明
Message(消息) IM SDK 中 Message 表示要发送给对方的内容,消息包括若干属性,例如自己是否为发送者,发送人帐号以及消息产生时间等。
Conversation(会话) IM SDK 中 Conversation 分为两种:
  • C2C(Client to Client)会话,表示单聊情况,自己与对方建立的对话。
  • GROUP(群)会话,表示群聊情况下群内成员组成的会话。
  • 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
    Name Type Attributes Default Description
    SDKAppID Number

    云通信应用的 SDKAppID

    oversea Boolean <optional>
    false

    如果您的应用需要在海外使用,请设置为 true,SDK 将替换域名,避免在某些国家或地区被干扰

    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
    Name Type Description
    userID String

    用户 ID

    userSig String

    用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
    具体生成方法请参见生成 UserSig

    Returns:
    Type
    Promise

    logout() → {Promise}

    登出即时通信 IM,通常在切换帐号的时候调用,清除登录态以及内存中的所有数据。
    注意!

    1. 调用此接口的实例会发布 SDK_NOT_READY 事件,此时该实例下线,无法收、发消息。
    2. 如果您在即时通信 IM 控制台配置的“Web端实例同时在线个数”大于 1,且同一账号登录了a1a2两个实例(含小程序端),当执行a1.logout()后,a1会下线,无法收、发消息。而a2实例不会受影响。
    3. 多实例被踢:基于第 2 点,如果“Web端实例同时在线个数”配置为 2,且您的某一账号已经登录了 a1a2两个实例,当使用此账号成功登录第三个实例a3时,a1a2中的一个实例会被踢下线(通常是最先处在登录态的实例会触发),这种情况称之为**“多实例被踢”**。假设a1实例被踢下线,a1实例内部会执行登出流程,然后抛出KICKED_OUT事件,接入侧可以监听此事件,并在触发时跳转到登录页。此时a1实例下线,而a2a3实例可以正常运行。
    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

    事件名称。所有的事件名称都存放在 TIM.EVENT 变量中,如需要查看可以使用 console.log(TIM.EVENT) 把所有的事件显示出来。事件列表

    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

    事件名称。所有的事件名称都存放在 TIM.EVENT 变量中,如需要查看可以使用 console.log(TIM.EVENT) 把所有的事件显示出来。事件列表

    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
    Name Type Description
    value Class

    插件类

    setLogLevel(level)

    设置日志级别,低于 level 的日志将不会输出。

    Example
    tim.setLogLevel(0);
    Parameters:
    Name Type Description
    level Number

    日志级别

    • 0 普通级别,日志量较多,接入时建议使用
    • 1 release级别,SDK 输出关键信息,生产环境时建议使用
    • 2 告警级别,SDK 只输出告警和错误级别的日志
    • 3 错误级别,SDK 只输出错误级别的日志
    • 4 无日志级别,SDK 将不打印任何日志

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID、groupID 或 topicID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容的容器

    Properties
    Name Type Description
    text String

    消息文本内容

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 groupID

    conversationType String

    会话类型,必须为 TIM.TYPES.CONV_GROUP

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容的容器

    Properties
    Name Type Description
    text String

    消息文本内容

    atUserList Array

    需要 @ 的用户列表,如果需要 @ALL,请传入 TIM.TYPES.MSG_AT_ALL 。 举个例子,假设该条文本消息希望 @ 提醒 denny 和 lucy 两个用户,同时又希望 @ 所有人,atUserList 传 ['denny', 'lucy', TIM.TYPES.MSG_AT_ALL]

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    file HTMLInputElement | File | Object

    用于选择图片的 DOM 节点(Web)或者 File 对象(Web)或者微信小程序 wx.chooseImage 接口的 success 回调参数,或 uni.chooseImage 接口的 success 回调参数。SDK 会读取其中的数据并上传图片。

    onProgress function

    获取上传进度的回调函数

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    file Object

    录音后得到的文件信息

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    file HTMLInputElement | File | Object

    用于选择视频文件的 DOM 节点(Web)或者 File 对象(Web),或微信小程序录制或者从相册选择的视频文件,或 uni.chooseVideo 接口的 success 回调参数。SDK 会读取其中的数据并上传

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    data String

    自定义消息的数据字段

    description String

    自定义消息的说明字段

    extension String

    自定义消息的扩展字段

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    index Number

    表情索引,用户自定义

    data String

    额外数据

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    file HTMLInputElement | File | Object

    用于选择文件的 DOM 节点(Web)或者 File 对象(Web)或者 Object(uni.chooseFile 接口的 success 回调参数),SDK 会读取其中的数据并上传文件。

    onProgress function

    获取上传进度的回调函数

    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
    Name Type Description
    description String

    地理位置描述信息

    longitude Number

    经度

    latitude Number

    纬度

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Object

    消息内容

    Properties
    Name Type Description
    messageList Array.<Message>

    合并的消息列表

    title String

    合并的标题,比如:"大湾区前端人才中心的聊天记录"

    abstractList String

    摘要列表,不同的消息类型可以设置不同的摘要信息,比如:文本消息可以设置为:sender: text,图片消息可以设置为:sender: [图片],文件消息可以设置为:sender: [文件]

    compatibleText String

    兼容文本,低版本 SDK 如果不支持合并消息,默认会收到一条文本消息,文本消息的内容为 ${compatibleText},必填。

    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
    Name Type Attributes Default Description
    to String

    消息接收方的 userID 或 groupID

    conversationType String

    会话类型,取值TIM.TYPES.CONV_C2C(端到端会话) 或 TIM.TYPES.CONV_GROUP(群组会话)

    priority String <optional>
    TIM.TYPES.MSG_PRIORITY_NORMAL

    消息优先级

    payload Message

    消息实例

    Returns:

    消息实例

    Type
    Message

    sendMessage(message, optionsopt) → {Promise}

    发送消息的接口,需先调用下列的创建消息实例的接口获取消息实例后,再调用该接口发送消息实例。

    注意1:调用该接口发送消息实例,需要 sdk 处于 ready 状态,否则将无法发送消息实例。sdk 状态,可通过监听以下事件得到:

    注意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
    Name Type Attributes Default Description
    onlineUserOnly Boolean <optional>
    false

    v2.6.4起支持。消息是否仅发送给在线用户的标识,默认值为 false;设置为 true,则消息既不存漫游,也不会计入未读,也不会离线推送给接收方。适合用于发送广播通知等不重要的提示消息场景。在 AVChatRoom 发送消息不支持此选项。

    offlinePushInfo Object <optional>

    v2.6.4起支持。离线推送配置。

    Properties
    Name Type Attributes Description
    disablePush Boolean <optional>

    true 关闭离线推送;false 开启离线推送(默认)

    title String <optional>

    离线推送标题。该字段为 iOS 和 Android 共用

    description String <optional>

    离线推送内容。该字段会覆盖消息实例的离线推送展示文本。若发送的是自定义消息,该 description 字段会覆盖 message.payload.description。如果 description 和 message.payload.description 字段都不填,接收方将收不到该自定义消息的离线推送

    extension String <optional>

    离线推送透传内容

    ignoreIOSBadge Boolean <optional>

    离线推送忽略 badge 计数(仅对 iOS 生效),如果设置为 true,在 iOS 接收端,这条消息不会使 APP 的应用图标未读计数增加

    androidOPPOChannelID String <optional>

    离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID

    messageControlInfo Object <optional>

    v2.16.0起支持。

    Properties
    Name Type Attributes Default Description
    excludedFromUnreadCount Boolean <optional>
    false

    true 消息不更新会话 unreadCount(消息存漫游)

    excludedFromLastMessage Boolean <optional>
    false

    true 消息不更新会话 lastMessage(消息存漫游)

    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}

    分页拉取指定会话的消息列表的接口,当用户进入会话首次渲染消息列表或者用户“下拉查看更多消息”时,需调用该接口。

    注意:该接口可用于"拉取历史消息"

    See:
    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
    Name Type Attributes Default Description
    conversationID String

    会话 ID。会话 ID 组成方式:

    • C2C${userID}(单聊)
    • GROUP${groupID}(群聊)
    • GROUP${topicID}(话题)v2.19.1 起支持
    • @TIM#SYSTEM(系统通知会话)
    nextReqMessageID String | undefined

    用于分页续拉的消息 ID。第一次拉取时不要传入 nextReqMessageID,续拉时填入上次调用 getMessageList 接口返回的该字段的值。

    count Number <optional>
    15

    需要拉取的消息数量,默认值和最大值为15。

    Returns:
    Type
    Promise

    getMessageListHopping(options) → {Promise}

    根据指定的消息 sequence 或 消息时间拉取会话的消息列表的接口。

    注意:使用该接口前,需要将SDK版本升级至v2.20.0或更高版本

    See:
    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
    Name Type Attributes Default Description
    conversationID String

    会话 ID。会话 ID 组成方式:

    • C2C${userID}(单聊)
    • GROUP${groupID}(群聊)
    • GROUP${topicID}(话题)
    sequence Number

    用于拉群组会话漫游消息的起始 sequence。

    time Number

    消息的服务端时间,用于拉 C2C 会话漫游消息的起始时间。

    direction Number <optional>
    0

    消息拉取方向,默认 0。

    • 0 向上拉,拉更旧的消息
    • 1 向下拉,拉更新的消息
    count Number <optional>
    15

    需要拉取的消息数量,默认值和最大值为15。

    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
    Name Type Description
    message Message

    群消息

    cursor String

    分页拉取的游标,第一次拉取传''

    filter Number

    指定拉取已读或未读群成员列表。0 - 拉取已读成员列表;1 - 拉取未读成员列表

    count Number

    分页拉取的个数,最大支持 100 个

    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
    Name Type Description
    conversationID String

    会话 ID。会话 ID 组成方式:

    • C2C${userID}(单聊)
    • GROUP${groupID}(群聊)
    • @TIM#SYSTEM(系统通知会话)
    • GROUP${topicID}(话题) v2.19.1 起支持
    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

    参数选项

    • options 不传表示获取全部会话
    • options 传入数组参数表示获取指定的多个会话,且不能传入空数组
    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 组成方式:

    • C2C${userID}(单聊)
    • GROUP{groupID}(群聊)
    • @TIM#SYSTEM(系统通知会话)
    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 组成方式:

    • C2C${userID}(单聊)
    • GROUP${groupID}(群聊)
    • @TIM#SYSTEM(系统通知会话)
    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
    Name Type Description
    conversationID String

    会话 ID。会话 ID 组成方式:

    • C2C${userID}(单聊)
    • GROUP${groupID}(群聊)
    isPinned Boolean

    true 表示置顶会话,false 表示取消置顶会话

    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
    Name Type Description
    scope string

    设置消息处理的范围。详细类型如下:

    • TIM.TYPES.READ_ALL_C2C_MSG (设置所有 C2C 会话未读消息为已读)
    • TIM.TYPES.READ_ALL_GROUP_MSG (设置所有群会话未读消息为已读)
    • TIM.TYPES.READ_ALL_MSG (默认值,设置所有 C2C 和群会话未读消息为已读)
    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
    Name Type Description
    groupID String

    群 ID 或 话题 ID

    userIDList Array

    C2C 会话对端 userID 列表,单次请求的 userID 数不得超过30

    messageRemindType String

    群消息提示类型。详细如下:

    • TIM.TYPES.MSG_REMIND_ACPT_AND_NOTE(SDK 接收消息并通知接入侧(抛出 收到消息事件),接入侧做提示)
    • TIM.TYPES.MSG_REMIND_ACPT_NOT_NOTE(SDK 接收消息并通知接入侧(抛出 收到消息事件),接入侧不做提示,一般用于实现“消息免打扰”)
    • TIM.TYPES.MSG_REMIND_DISCARD(SDK 拒收消息)
    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
    Name Type Description
    userIDList Array.<String>

    用户的账号列表,类型为数组

    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
    Name Type Description
    nick String

    昵称

    avatar String

    头像地址

    gender String

    性别:

    • TIM.TYPES.GENDER_UNKNOWN(未设置性别)
    • TIM.TYPES.GENDER_FEMALE(女)
    • TIM.TYPES.GENDER_MALE(男)
    selfSignature String

    个性签名

    allowType String

    当被加人加好友时:

    • TIM.TYPES.ALLOW_TYPE_ALLOW_ANY(允许直接加为好友)
    • TIM.TYPES.ALLOW_TYPE_NEED_CONFIRM(需要验证)
    • TIM.TYPES.ALLOW_TYPE_DENY_ANY(拒绝)
    birthday Number

    生日 推荐用法:20000101

    location String

    所在地 推荐用法:App 本地定义一套数字到地名的映射关系 后台实际保存的是4个 uint32_t 类型的数字: 其中第一个 uint32_t 表示国家; 第二个 uint32_t 用于表示省份; 第三个 uint32_t 用于表示城市; 第四个 uint32_t 用于表示区县

    language Number

    语言

    messageSettings Number

    消息设置 0:接收消息,1:不接收消息

    adminForbidType String

    管理员禁止加好友标识:

    • TIM.TYPES.FORBID_TYPE_NONE(默认值,允许加好友)
    • TIM.TYPES.FORBID_TYPE_SEND_OUT(禁止该用户发起加好友请求)
    level Number

    等级 建议拆分以保存多种角色的等级信息

    role Number

    角色 建议拆分以保存多种角色信息

    profileCustomField Array.<Object>

    自定义资料键值对集合,可根据业务侧需要使用,详细请参考: 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

    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
    Name Type Description
    userIDList Array.<String>

    待添加为黑名单的用户 userID 列表,单次请求的 userID 数不得超过1000

    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
    Name Type Attributes Default Description
    to String

    用户 ID

    source String

    好友来源。

    • 加好友来源字段包含前缀和关键字两部分;
    • 加好友来源字段的前缀是:AddSource_Type_ ;
    • 关键字:必须是英文字母,且长度不得超过 8 字节,建议用一个英文单词或该英文单词的缩写;
    • 示例:加好友来源的关键字是 Android,则加好友来源字段是:AddSource_Type_Android
    wording String <optional>
    ''

    加好友附言:

    • 加好友附言的长度最长不得超过 256 个字节
    type String <optional>
    TIM.TYPES.SNS_ADD_TYPE_BOTH

    加好友方式(默认双向加好友方式)

    • TIM.TYPES.SNS_ADD_TYPE_SINGLE 单向加好友(单向好友:用户 A 的好友表中有用户 B,但 B 的好友表中却没有 A)
    • TIM.TYPES.SNS_ADD_TYPE_BOTH 双向加好友(双向好友:用户 A 的好友表中有用户 B,B 的好友表中也有 A)
    remark String <optional>
    ''

    好友备注

    • 备注长度最长不得超过 96 个字节
    groupName String <optional>
    ''

    分组信息

    • 分组名长度不得超过 30 个字节
    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
    Name Type Attributes Default Description
    userIDList Array.<String>

    待删除的好友的 userID 列表,单次请求的 userID 数不得超过100

    type String <optional>
    TIM.TYPES.SNS_DELETE_TYPE_BOTH

    删除模式(默认双向删除好友),详情可参见 删除好友

    • TIM.TYPES.SNS_DELETE_TYPE_SINGLE 单向删除(只将 B 从 A 的好友表中删除,但不会将 A 从 B 的好友表中删除)
    • TIM.TYPES.SNS_DELETE_TYPE_BOTH 双向删除(将 B 从 A 的好友表中删除,同时将 A 从 B 的好友表中删除)
    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
    Name Type Attributes Default Description
    userIDList Array.<String>

    要校验的 userID 列表,单次请求的 userID 数不得超过1000

    type String <optional>
    TIM.TYPES.SNS_CHECK_TYPE_BOTH

    校验模式(默认双向校验好友关系),详情可参见 校验好友

    • TIM.TYPES.SNS_CHECK_TYPE_SINGLE 单向校验好友关系(只会检查 A 的好友表中是否有 B,不会检查 B 的好友表中是否有 A)
    • TIM.TYPES.SNS_CHECK_TYPE_BOTH 双向校验好友关系(既会检查 A 的好友表中是否有 B,也会检查 B 的好友表中是否有 A)
    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
    Name Type Description
    userIDList Array.<String>

    要获取资料的 userID 列表

    Returns:
    Type
    Promise

    updateFriend(options) → {Promise}

    更新好友的关系链数据,只支持好友备注、关系链自定义字段的更新操作。
    注意!

    1. v2.13.0起支持,升级指引
    2. 更新好友分组,请使用 addToFriendGroupremoveFromFriendGroup 接口
    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
    Name Type Attributes Default Description
    userID Array.<String>

    要更新的好友 userID

    remark String <optional>
    ''

    好友备注

    • 备注长度最长不得超过 96 个字节
    friendCustomField Array.<Object> <optional>

    好友自定义字段键值对集合,可根据业务侧需要使用,详细请参考: https://cloud.tencent.com/document/product/269/1501#.E8.87.AA.E5.AE.9A.E4.B9.89.E5.A5.BD.E5.8F.8B.E5.AD.97.E6.AE.B5

    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
    Name Type Attributes Default Description
    userID String

    待同意的好友申请的 userID

    remark String <optional>
    ''

    给好友设置的备注

    type String

    同意方式

    • TIM.TYPES.SNS_APPLICATION_AGREE 同意添加单向好友
    • TIM.TYPES.SNS_APPLICATION_AGREE_AND_ADD 同意并添加为双向好友
    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
    Name Type Description
    userID String

    拒绝的好友申请的 userID

    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
    Name Type Description
    userID String

    待删除的好友申请的 userID

    type String

    好友申请的类型

    • TIM.TYPES.SNS_APPLICATION_SENT_TO_ME 别人发给我的好友申请
    • TIM.TYPES.SNS_APPLICATION_SENT_BY_ME 我发给别人的好友申请
    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
    Name Type Description
    name String

    分组名称

    userIDList Array.<String>

    要添加到分组的好友 userID 列表

    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
    Name Type Description
    name String

    要删除的分组名称

    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
    Name Type Description
    name String

    分组名称

    userIDList Array.<String>

    要添加的好友 userID 列表

    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
    Name Type Description
    name String

    分组名称

    userIDList Array.<String>

    要移除的好友 userID 列表

    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
    Name Type Description
    oldName String

    旧的分组名称

    newName String

    新的分组名称

    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
    Name Type Attributes Description
    groupProfileFilter Array.<String> <optional>

    群资料过滤器。除默认拉取的群资料外,指定需要额外拉取的群资料,支持的值如下:

    • TIM.TYPES.GRP_PROFILE_OWNER_ID(群主 ID)
    • TIM.TYPES.GRP_PROFILE_CREATE_TIME(群创建时间)
    • TIM.TYPES.GRP_PROFILE_LAST_INFO_TIME(最后一次群资料变更时间)
    • TIM.TYPES.GRP_PROFILE_MEMBER_NUM(群成员数量)
    • TIM.TYPES.GRP_PROFILE_MAX_MEMBER_NUM(最大群成员数量)
    • TIM.TYPES.GRP_PROFILE_JOIN_OPTION(申请加群选项)
    • TIM.TYPES.GRP_PROFILE_INTRODUCTION(群介绍)
    • TIM.TYPES.GRP_PROFILE_NOTIFICATION(群公告)
    • TIM.TYPES.GRP_PROFILE_MUTE_ALL_MBRS (全体禁言设置) v2.6.2起支持
    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
    Name Type Attributes Description
    groupID String

    群组ID

    groupCustomFieldFilter Array.<String> <optional>

    群组维度的自定义字段过滤器,指定需要获取的群组维度的自定义字段,详情请参阅 自定义字段

    Returns:
    Type
    Promise

    createGroup(options) → {Promise}

    创建群组

    注意1:该接口创建 TIM.TYPES.GRP_AVCHATROOM(直播群) 后,需调用 joinGroup 接口加入群组后,才能进行消息收发流程。
    注意2:v2.19.1 起,该接口可以创建支持话题的社群。

    See:
    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
    Name Type Attributes Default Description
    name String

    必填,群组名称,最长30字节

    type String <optional>
    TIM.TYPES.GRP_WORK

    群组类型,包括:

    • TIM.TYPES.GRP_WORK(好友工作群,默认)
    • TIM.TYPES.GRP_PUBLIC(陌生人社交群)
    • TIM.TYPES.GRP_MEETING(临时会议群)
    • TIM.TYPES.GRP_AVCHATROOM(直播群)
    • TIM.TYPES.GRP_COMMUNITY(社群,v2.17.0 起支持)
    groupID String <optional>

    群组ID。不填该字段时,会自动为群组创建一个唯一的群 ID

    introduction String <optional>

    群简介,最长240字节

    notification String <optional>

    群公告,最长300字节

    avatar String <optional>

    群头像 URL,最长100字节

    maxMemberNum Number <optional>

    最大群成员数量,缺省时的默认值:好友工作群是200,陌生人社交群是2000,临时会议群是10000,直播群无限制

    joinOption String <optional>
    TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS

    申请加群处理方式。

    • TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS (自由加入)
    • TIM.TYPES.JOIN_OPTIONS_NEED_PERMISSION (需要验证)
    • TIM.TYPES.JOIN_OPTIONS_DISABLE_APPLY (禁止加群)
      注意:创建 TIM.TYPES.GRP_WORK, TIM.TYPES.GRP_MEETING, TIM.TYPES.GRP_AVCHATROOM 类型的群组不能填写该字段。好友工作群禁止申请加群,临时会议群和直播群自由加入。
    memberList Array.<Object> <optional>

    初始群成员列表,最多500个。创建直播群时不能添加成员

    Properties
    Name Type Attributes Description
    userID String

    必填,群成员的 userID

    role String <optional>

    成员身份,可选值只有Admin,表示添加该成员并设其为管理员

    memberCustomField Array.<Object> <optional>

    群成员维度的自定义字段,默认情况是没有的,需要开通,详情请参阅自定义字段

    groupCustomField Array.<Object> <optional>

    群组维度的自定义字段,默认情况是没有的,需要开通,详情请参阅群成员资料

    isSupportTopic Boolean

    创建支持话题的社群时必填, true - 创建支持话题的社群 false - 创建普通社群。v2.19.1 起支持

    Returns:
    Type
    Promise

    dismissGroup(groupID) → {Promise}

    群主可调用该接口解散群组。

    注意:群主不能解散好友工作群。

    See:
    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}

    修改群组资料

    See:
    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
    Name Type Attributes Default Description
    groupID String

    群ID

    name String <optional>

    群名称,最长30字节

    avatar String <optional>

    群头像URL,最长100字节

    introduction String <optional>

    群简介,最长240字节

    notification String <optional>

    群公告,最长300字节

    maxMemberNum Number <optional>

    最大群成员数量,最大为6000

    muteAllMembers Boolean

    设置全体禁言,true 表示全体禁言,false 表示取消全体禁言,v2.6.2 起支持

    joinOption String <optional>
    TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS

    申请加群处理方式。

    • TIM.TYPES.JOIN_OPTIONS_FREE_ACCESS (自由加入)
    • TIM.TYPES.JOIN_OPTIONS_NEED_PERMISSION (需要验证)
    • TIM.TYPES.JOIN_OPTIONS_DISABLE_APPLY (禁止加群)
      注意:TIM.TYPES.GRP_WORK, TIM.TYPES.GRP_MEETING, TIM.TYPES.GRP_AVCHATROOM 类型群组的该属性不允许修改。好友工作群禁止申请加群,临时会议群和直播群自由加入。
    groupCustomField Array.<Object> <optional>

    群自定义字段。默认情况是没有的。开通群组维度的自定义字段详情请参见 自定义字段

    Properties
    Name Type Description
    key String

    自定义字段的 Key

    value String

    自定义字段的 Value

    Returns:
    Type
    Promise

    joinGroup(options) → {Promise}

    申请加群的接口,申请加入某个群组时调用。

    注意:

    1. 好友工作群不允许申请加群,只能通过 addGroupMember 方式添加
    2. TIM.TYPES.GRP_AVCHATROOM(直播群)有两种加群方式:
      2.1 正常加群,即登录加群。此时 SDK 内的所有接口都能正常调用。
      2.2 匿名加群,即不登录加群。此时只能收消息,其他任何需要鉴权的接口都不能调用。
    3. 只有 TIM.TYPES.GRP_AVCHATROOM(直播群) 支持匿名加群,其他类型的群组不支持。
    4. 同一用户同时只能加入一个直播群。【例如】用户已在直播群 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
    Name Type Attributes Description
    groupID String

    群 ID

    applyMessage String

    附言

    type String <optional>

    要加入群组的类型,加入直播群时该字段必填。可选值:

    • TIM.TYPES.GRP_PUBLIC(陌生人社交群)
    • TIM.TYPES.GRP_MEETING (临时会议群)
    • TIM.TYPES.GRP_AVCHATROOM (直播群)
    • TIM.TYPES.GRP_COMMUNITY(社群,v2.17.0 起支持)
    Returns:
    Type
    Promise

    quitGroup(groupID) → {Promise}

    退出群组。

    注意:群主只能退出好友工作群,退出后该好友工作群无群主。

    See:
    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
    Name Type Description
    groupID String

    待转让的群组 ID

    newOwnerID String

    新群主的 ID

    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
    Name Type Attributes Description
    handleAction String

    处理结果 Agree(同意) / Reject(拒绝)

    handleMessage String <optional>

    附言

    message Message

    对应【群系统通知】的消息实例

    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
    Name Type Description
    groupID String

    群组ID

    groupAttributes Object

    群属性

    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
    Name Type Description
    groupID String

    群组ID

    groupAttributes Object

    群属性

    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
    Name Type Description
    groupID String

    群组ID

    keyList Array.<String>

    群属性 key 列表

    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
    Name Type Description
    groupID String

    群组ID

    keyList Array.<String>

    群属性 key 列表

    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
    Name Type Attributes Default Description
    groupID String

    群组的 ID

    count Number <optional>
    15

    需要拉取的数量。最大值:100,避免回包过大导致请求失败。若传入超过100,则只拉取前100个。

    offset Number <optional>
    0

    偏移量,默认从0开始拉取

    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
    Name Type Attributes Description
    groupID String

    群组 ID

    userIDList Array.<String>

    要查询的群成员用户 ID 列表

    memberCustomFieldFilter Array.<String> <optional>

    群成员自定义字段筛选。可选,若不填,则默认查询所有群成员自定义字段。

    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
    Name Type Description
    groupID String

    群 ID

    userIDList Array.<String>

    待添加的群成员 ID 数组。单次最多添加500个成员

    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
    Name Type Attributes Description
    groupID String

    群ID

    userIDList Array.<String>

    待删除的群成员的 ID 列表

    reason String <optional>

    踢人的原因

    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
    Name Type Description
    groupID String

    群 ID 或 话题 ID

    userID String

    用户 ID

    muteTime Number

    禁言时长,单位秒。如设为1000,则表示从现在起禁言该用户1000秒;设为0,则表示取消禁言。

    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
    Name Type Description
    groupID String

    群 ID

    userID String

    用户 ID

    role String

    可选值:TIM.TYPES.GRP_MBR_ROLE_ADMIN(群管理员),TIM.TYPES.GRP_MBR_ROLE_MEMBER(群普通成员),TIM.TYPES.GRP_MBR_ROLE_CUSTOM(自定义群成员角色,仅社群支持)

    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
    Name Type Attributes Description
    groupID String

    群 ID

    userID String <optional>

    可选,默认修改自身的群名片

    nameCard String

    群成员名片

    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
    Name Type Attributes Description
    groupID String

    群 ID

    userID String <optional>

    可选,不填则修改自己的群成员自定义字段

    memberCustomField Array.<Object>

    群成员自定义字段

    Properties
    Name Type Description
    key String

    自定义字段的 Key

    value String

    自定义字段的 Value

    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
    Name Type Description
    groupID String

    话题所属社群 ID

    topicName String

    话题名称

    topicID String

    自定义话题 ID 时,格式必须是社群 ID 拼接上自定义话题 ID。如:@TGS#_xxx@TOPIC#_xxx

    avatar String

    话题头像

    notification String

    话题公告

    introduction String

    话题简介

    customData String

    话题自定义信息

    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
    Name Type Description
    groupID String

    话题所属社群 ID

    topicIDList Array | undefined

    话题 ID 列表,不传 topicIDList 表示删除全部话题

    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
    Name Type Description
    groupID String

    必填,话题所属社群 ID

    topicID String

    必填,话题 ID

    topicName String

    话题名称

    avatar String

    话题头像

    notification String

    话题公告

    introduction String

    话题简介

    customData String

    话题自定义信息

    muteAllMembers Boolean

    设置全体禁言,true - 全体禁言 false - 取消全体禁言

    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
    Name Type Description
    groupID String

    话题所属社群 ID

    topicIDList Array | undefined

    话题 ID 列表,不传 topicIDList 表示获取全部话题

    Returns:
    Type
    Promise