SDK

import TIM from 'tim-js-sdk';
// import TIM from 'tim-wx-sdk'; // For WeChat Mini Program, uncomment this line and comment out the following: import TIM from 'tim-js-sdk';
import TIMUploadPlugin from 'tim-upload-plugin'; // Before using the API, upgrade your IM SDK to v2.9.2 or later.
// Create an SDK instance. The TIM.create() method returns the same instance for the same SDKAppID.
let options = {
  SDKAppID: 0 // Replace 0 with the SDKAppID of your IM app when connecting.
};
let tim = TIM.create(options); // The SDK instance is usually represented by tim.
// Set the SDK log output level. For details on each level, see **setLogLevel API description**.
tim.setLogLevel(0); // Common level. You are advised to use this level during access as it covers more logs.
// tim.setLogLevel(1); // Release level, at which the SDK outputs important information. You are advised to use this log level in a production environment.
// Register the Tencent Cloud IM upload plugin. Before sending messages, such as image, audio, video, and file messages, the IM SDK needs to use the upload plugin to upload files to Tencent COS.
tim.registerPlugin({'tim-upload-plugin': TIMUploadPlugin});
// Listened-for events, for example:
tim.on(TIM.EVENT.SDK_READY, function(event) {
  // A notification is received, indicating that the offline message and conversation lists are synchronized successfully. The access side can call APIs that require authentication, such as sendMessage.
  // event.name - TIM.EVENT.SDK_READY
});
tim.on(TIM.EVENT.MESSAGE_RECEIVED, function(event) {
  // A newly pushed one-to-one message, group message, group tip, or group system notification is received. You can traverse event.data to obtain the message list and render it to the UI.
  // event.name - TIM.EVENT.MESSAGE_RECEIVED
  // event.data - An array that stores Message objects - [Message]
});
tim.on(TIM.EVENT.MESSAGE_MODIFIED, function(event)) {
  // This event is triggered when the SDK receives a notification for message modifications by a third-party callback. When this event occurs, the message sender can traverse event.data to obtain the message list and update the content of the message with the same ID on the UI. (Supported from v2.12.1)
  // event.name - TIM.EVENT.MESSAGE_MODIFIED
  // event.data - An array that stores the Message objects modified by a third-party callback - [Message]
});
tim.on(TIM.EVENT.MESSAGE_REVOKED, function(event) {
  // A message recall notification is received. Before using this event, upgrade your SDK to v2.4.0 or later.
  // event.name - TIM.EVENT.MESSAGE_REVOKED
  // event.data - An array that stores Message objects - [Message] - The isRevoked value of each Message object is true.
});
tim.on(TIM.EVENT.MESSAGE_READ_BY_PEER, function(event) {
  // The SDK receives a notification (read receipt) indicating that the peer end has read the message. Before using this event, you need to upgrade your SDK to V2.7.0 or later. This event is supported only for one-to-one conversations.
  // event.name - TIM.EVENT.MESSAGE_READ_BY_PEER
  // event.data - event.data - An array that stores the Message objects - [Message] - The isPeerRead value of each Message object is true.
});
tim.on(TIM.EVENT.CONVERSATION_LIST_UPDATED, function(event) {
  // A conversation list update notification is received. You can traverse event.data to obtain the conversation list and render it to the UI.
  // event.name - TIM.EVENT.CONVERSATION_LIST_UPDATED
  // event.data - An array that stores the Conversation objects - [Conversation]
});
tim.on(TIM.EVENT.GROUP_LIST_UPDATED, function(event) {
  // A group list update notification is received. You can traverse event.data to obtain the group list and render it to the UI.
  // event.name - TIM.EVENT.GROUP_LIST_UPDATED
  // event.data - An array that stores the Group objects - [Group]
});
tim.on(TIM.EVENT.PROFILE_UPDATED, function(event) {
  // A notification is received, indicating that your own profile or your friend's profile is updated.
  // event.name - TIM.EVENT.PROFILE_UPDATED
  // event.data - An array that stores the Profile objects - [Profile]
});
tim.on(TIM.EVENT.BLACKLIST_UPDATED, function(event) {
  // A blocklist update notification is received.
  // event.name - TIM.EVENT.BLACKLIST_UPDATED
  // event.data - An array that stores userIDs - [userID]
});
tim.on(TIM.EVENT.ERROR, function(event) {
  // An SDK error notification is received. The error code and error message can be obtained from this notification.
  // event.name - TIM.EVENT.ERROR
  // event.data.code - Error code
  // event.data.message - Error message
});
tim.on(TIM.EVENT.SDK_NOT_READY, function(event) {
  // An SDK not ready notification is received. At this time, the SDK cannot function normally.
  // event.name - TIM.EVENT.SDK_NOT_READY
});
tim.on(TIM.EVENT.KICKED_OUT, function(event) {
  // A kicked offline notification is received.
  // event.name - TIM.EVENT.KICKED_OUT
  // event.data.type - Reason for being kicked offline, such as:
  //    - TIM.TYPES.KICKED_OUT_MULT_ACCOUNT: kicked offline due to multi-instance login.
  //    - TIM.TYPES.KICKED_OUT_MULT_DEVICE: kicked offline due to multi-device login.
  //    - TIM.TYPES.KICKED_OUT_USERSIG_EXPIRED: kicked offline due to UserSig expiration (supported from v2.4.0).
});
tim.on(TIM.EVENT.NET_STATE_CHANGE, function(event) {
  // The network status changes (supported from v2.5.0).
  // event.name - TIM.EVENT.NET_STATE_CHANGE
  // event.data.state indicates the current network status. The enumerated values are described as follows:
  //   - TIM.TYPES.NET_STATE_CONNECTED: already connected to the network
  //   - TIM.TYPES.NET_STATE_CONNECTING: connecting. This often occurs when the SDK must reconnect due to network jitter. The message "The current network is unstable" or "Connecting..." can be displayed at the access side based on this status.
  //   - TIM.TYPES.NET_STATE_DISCONNECTED: disconnected. The message "The current network is unavailable" can be displayed at the access side based on this status. The SDK will continue to try to reconnect. If the user network recovers, the SDK will automatically synchronize messages.
});
tim.on(TIM.EVENT.FRIEND_LIST_UPDATED, function(event) {
  // A friend list update notification is received. (Supported from v2.13.0)
  // event.name - TIM.EVENT.FRIEND_LIST_UPDATED
  // event.data - An array that stores the Friend objects - [Friend]
});
tim.on(TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED, function(event) {
  // A friend request list update notification is received. (Supported from v2.13.0)
  // event.name - TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED
  // friendApplicationList - Friend request list - [FriendApplication]
  // unreadCount - Unread friend request count
  // const { friendApplicationList, unreadCount } = event.data;
  // Friend requests received by me (friend requests that are sent to you by others)
  // const applicationSentToMe = friendApplicationList.filter((friendApplication) => friendApplication.type === TIM.TYPES.SNS_APPLICATION_SENT_TO_ME);
  // Friend requests sent by me (friend requests that you send to others)
  // const applicationSentByMe = friendApplicationList.filter((friendApplication) => friendApplication.type === TIM.TYPES.SNS_APPLICATION_SENT_BY_ME);
});
tim.on(TIM.EVENT.FRIEND_GROUP_LIST_UPDATED, function(event) {
  // Received a notification on the update of the list of friend lists. (Supported from v2.13.0)
  // event.name - TIM.EVENT.FRIEND_GROUP_LIST_UPDATED
  // event.data - An array that stores the FriendGroup objects - [FriendGroup]
});
// Start to log in to the SDK.
tim.login({userID: 'your userID', userSig: 'your userSig'});

Methods

login(options) → {Promise}

Example

let promise = tim.login({userID: 'your userID', userSig: 'your userSig'});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Login successful
  if (imResponse.data.repeatLogin === true) {
    // Indicates that the account has logged in and that the current login will be a repeated login. This feature is supported from v2.5.1.
    console.log(imResponse.data.errorInfo);
  }
}).catch(function(imError) {
  console.warn('login error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

logout() → {Promise}

Example

let promise = tim.logout();
promise.then(function(imResponse) {
  console.log(imResponse.data); // Logout successful
}).catch(function(imError) {
  console.warn('logout error:', imError);
});

Returns:

Type

Promise

destroy() → {Promise}

Example

tim.destroy();

Returns:

Type

Promise

on(eventName, handler, contextopt)

Example

let onMessageReceived = function(event) {
  // A newly pushed one-to-one message, group message, group tip, or group system notification is received. You can traverse event.data to obtain the message list and render it to the UI.
  // event.name - TIM.EVENT.MESSAGE_RECEIVED
  // event.data - An array that stores Message objects - [Message]
};
tim.on(TIM.EVENT.MESSAGE_RECEIVED, onMessageReceived);

Parameters:

off(eventName, handler, contextopt, onceopt)

Example

let onMessageReceived = function(event) {
  // A newly pushed one-to-one message, group message, group tip, or group system notification is received. You can traverse event.data to obtain the message list and render it to the UI.
  // event.name - TIM.EVENT.MESSAGE_RECEIVED
  // event.data - An array that stores Message objects - [Message]
};
tim.off(TIM.EVENT.MESSAGE_RECEIVED, onMessageReceived);

Parameters:

registerPlugin(options)

Example

// Before using tim-js-sdk or tim-wx-sdk, please upgrade your SDK to v2.9.2 or later.
// To use tim-upload-plugin in Mini Programs, you need to configure the valid domain name https://cos.ap-shanghai.myqcloud.com for uploadFile and downloadFile on the Mini Program backend.
tim.registerPlugin({'tim-upload-plugin': TIMUploadPlugin});

Parameters:

setLogLevel(level)

Example

tim.setLogLevel(0);

Parameters:

createTextMessage(options) → {Message}

Example

// Send a text message. The text message sending process in web apps is the same as that in Mini Programs.
// 1. Create a message instance. The returned instance can be displayed on the screen.
let message = tim.createTextMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: {
    text: 'Hello world!'
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
});
// 2. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

createTextAtMessage(options) → {Message}

Example

// Send a text message. The text message sending process in web apps is the same as that in Mini Programs.
// 1. Create a message instance. The returned instance can be displayed on the screen.
let message = tim.createTextAtMessage({
  to: 'group1',
  conversationType: TIM.TYPES.CONV_GROUP,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: {
    text: '@denny @lucy @all Dinner tonight. Please reply 1 if you receive this message',
    atUserList: ['denny', 'lucy', TIM.TYPES.MSG_AT_ALL] // 'denny' and 'lucy' are userIDs, not nicknames
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
});
// 2. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

createImageMessage(options) → {Message}

Examples

// Example 1 for sending an image message in a web app - Passing in a DOM node
// 1. Create a message instance. The returned instance can be displayed on the screen.
let message = tim.createImageMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: {
    file: document.getElementById('imagePicker'),
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
  onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

// Example 2 for sending an image message in a web app - Passing in a file object
// Add a message input box with the ID set to "testPasteInput", for example, <input type="text" id="testPasteInput" placeholder="Take a screenshot and paste it in the input box" 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];
    // After the image message is successfully sent, the content pointed by "file" may be cleared by the browser. If you have extra rendering requirements, copy the data in advance.
    fileCopy = file.slice();
  }
  if (typeof file === 'undefined') {
    console.warn('file is undefined. Check compatibility of the code or browser.');
    return;
  }
  // 1. Create a message instance. The returned instance can be displayed on the screen.
  let message = tim.createImageMessage({
    to: 'user1',
    conversationType: TIM.TYPES.CONV_C2C,
    payload: {
      file: file
    },
    onProgress: function(event) { console.log('file uploading:', event) }
  });
  // 2. Send the message.
  let promise = tim.sendMessage(message);
  promise.then(function(imResponse) {
    // The message is sent successfully.
    console.log(imResponse);
  }).catch(function(imError) {
    // The message fails to be sent.
    console.warn('sendMessage error:', imError);
  });
});

// Send an image message in a Mini Program.
// 1. Select an image.
wx.chooseImage({
  sourceType: ['album'], // Select an image from the album.
  count: 1, // You can only select one image. The SDK does not support sending multiple images at a time.
  success: function (res) {
    // 2. Create a message instance. The returned instance can be displayed on the screen.
    let message = tim.createImageMessage({
      to: 'user1',
      conversationType: TIM.TYPES.CONV_C2C,
      payload: { file: res },
      onProgress: function(event) { console.log('file uploading:', event) }
    });
    // 3. Send the image.
    let promise = tim.sendMessage(message);
    promise.then(function(imResponse) {
      // The message is sent successfully.
      console.log(imResponse);
    }).catch(function(imError) {
      // The message fails to be sent.
      console.warn('sendMessage error:', imError);
    });
  }
})

// Send an image message via uni-app. Before using this API, upgrade your SDK to v2.11.2 or later and upgrade tim-upload-plugin to v1.0.2 or later.
// 1. Select an image.
uni.chooseImage({
  count: 1,
  sizeType: ['original', 'compressed'], // You can specify whether to use the original or compressed image. Both are included by default.
  sourceType: ['album'], // Select an image from the 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. Send the message.
    let promise = tim.sendMessage(message);
    promise.then(function(imResponse) {
      // The message is sent successfully.
      console.log(imResponse);
    }).catch(function(imError) {
      // The message fails to be sent.
      console.warn('sendMessage error:', imError);
    });
  }
});

Parameters:

Returns:

Type

Message

createAudioMessage(options) → {Message}

Example

//Example: Record an audio message by using the official WeChat RecorderManager. For more information, see https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html.
// 1. Get the globally unique RecorderManager.
const recorderManager = wx.getRecorderManager();
// Recording parameters
const recordOptions = {
  duration: 60000, // Length of the audio message, in ms. Max. value: 600000 ms (10 minutes).
  sampleRate: 44100, // Sample rate
  numberOfChannels: 1, // Number of recording channels
  encodeBitRate: 192000, // Encoding bitrate
  format: 'aac' // Format of the audio message. This audio format is compatible with all IM platforms (Android, iOS, WeChat Mini Programs, and web apps).
};
// 2.1 Listen for recording errors.
recorderManager.onError(function(errMsg) {
  console.warn('recorder error:', errMsg);
});
// 2.2 Listen for recording end event. After recording ends, call createAudioMessage to create an audio message instance.
recorderManager.onStop(function(res) {
  console.log('recorder stop', res);
  // 4. Create a message instance. The returned instance can be displayed on the screen.
  const message = tim.createAudioMessage({
    to: 'user1',
    conversationType: TIM.TYPES.CONV_C2C,
    // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
    // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, TIM.TYPES.MSG_PRIORITY_LOWEST
    // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
    payload: {
      file: res
    },
    // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
    // cloudCustomData: 'your cloud custom data'
  });
  // 5. Send the message.
  let promise = tim.sendMessage(message);
  promise.then(function(imResponse) {
    // The message is sent successfully.
    console.log(imResponse);
  }).catch(function(imError) {
    // The message fails to be sent.
    console.warn('sendMessage error:', imError);
  });
});
3. Start recording.
recorderManager.start(recordOptions);

Parameters:

Returns:

Type

Message

createVideoMessage(options) → {Message}

Examples

// Example of sending a video message in a Mini Program
// 1. Call the Mini Program API to select a video. For more information, see https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseVideo.html.
wx.chooseVideo({
  sourceType: ['album', 'camera'], // You can specify whether the source is an album or a camera. Both are included by default.
  maxDuration: 60, // Maximum duration, which is 60s
  camera: 'back', // Rear camera
  success (res) {
    // 2. Create a message instance. The returned instance can be displayed on the screen.
    let message = tim.createVideoMessage({
      to: 'user1',
      conversationType: TIM.TYPES.CONV_C2C,
      // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
      // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
      // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
      payload: {
        file: res
      },
      // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
      // cloudCustomData: 'your cloud custom data'
      // Starting from v2.12.2, video upload progress callback is supported on mini programs.
      onProgress: function(event) { console.log('file uploading:', event) }
    })
    // 3. Send the message.
    let promise = tim.sendMessage(message);
    promise.then(function(imResponse) {
      // The message is sent successfully.
      console.log(imResponse);
    }).catch(function(imError) {
      // The message fails to be sent.
      console.warn('sendMessage error:', imError);
    });
  }
})

// Example of sending a video message in a web app (supported from v2.6.0):
// 1. Obtain the video file, and pass in the DOM node.
// 2. Create a message instance.
const message = tim.createVideoMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  payload: {
    file: document.getElementById('videoPicker') // Alternatively, use event.target
  },
  onProgress: function(event) { console.log('file uploading:', event) }
});
// 3. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

// Send a video message via uni-app. Before using this API, upgrade your SDK to v2.11.2 or later and upgrade tim-upload-plugin to v1.0.2 or later.
// 1. Select a video.
uni.chooseVideo({
  count: 1,
  sourceType: ['camera', 'album'], // You can specify whether the source is an album or a camera. Both are included by default.
  maxDuration: 60, // Maximum duration, which is 60s
  camera: 'back', // Rear camera
  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. Send the message.
    let promise = tim.sendMessage(message);
    promise.then(function(imResponse) {
      // The message is sent successfully.
      console.log(imResponse);
    }).catch(function(imError) {
      // The message fails to be sent.
      console.warn('sendMessage error:', imError);
    });
  }
})

Parameters:

Returns:

Type

Message

createCustomMessage(options) → {Message}

Example

// Example: use custom messages to implement dice rolling
// 1. Define the random function.
function random(min, max) {
  return Math.floor(Math.random() * (max - min + 1) + min);
}
// 2. Create a message instance. The returned instance can be displayed on the screen.
let message = tim.createCustomMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_HIGH,
  payload: {
    data: 'dice', // Identify that this message is a dice message.
    description: String(random(1,6)), // Get the outcome.
    extension: ''
  }
});
// 3. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

createFaceMessage(options) → {Message}

Example

// Send an emoji message. The emoji message sending process in web apps is the same as that in Mini Programs.
// 1. Create a message instance. The returned instance can be displayed on the screen.
let message = tim.createFaceMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: {
    index: 1, // Number. Emoji index, which is customized by the user.
    data: 'tt00' // String. Additional data.
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
});
// 2. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

createFileMessage(options) → {Message}

Examples

// Example 1 for sending a file message in a web app - Passing in a DOM node
// 1. Create a file message instance. The returned instance can be displayed on the screen.
let message = tim.createFileMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats (supported from v2.4.2). If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: {
    file: document.getElementById('filePicker'),
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
  onProgress: function(event) { console.log('file uploading:', event) }
});
// 2. Send the message.
let promise = tim.sendMessage(message);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

// Example 2 for sending a file message in a web app - Passing in a file object
// Add a message input box with the ID set to "testPasteInput", for example, <input type="text" id="testPasteInput" placeholder="Take a screenshot and paste it in the input box" 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];
    // After the image message is successfully sent, the content pointed by "file" may be cleared by the browser. If you have extra rendering requirements, copy the data in advance.
    fileCopy = file.slice();
  }
  if (typeof file === 'undefined') {
    console.warn('file is undefined. Check compatibility of the code or browser.');
    return;
  }
  // 1. Create a message instance. The returned instance can be displayed on the screen.
  let message = tim.createFileMessage({
    to: 'user1',
    conversationType: TIM.TYPES.CONV_C2C,
    payload: {
      file: file
    },
    onProgress: function(event) { console.log('file uploading:', event) }
  });
  // 2. Send the message.
  let promise = tim.sendMessage(message);
  promise.then(function(imResponse) {
    // The message is sent successfully.
    console.log(imResponse);
  }).catch(function(imError) {
    // The message fails to be sent.
    console.warn('sendMessage error:', imError);
  });
});

// Send a file message via uni-app. Before using this API, upgrade your SDK to v2.11.2 or later and upgrade tim-upload-plugin to v1.0.2 or later.
// 1. Select a file.
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. Send the message.
    let promise = tim.sendMessage(message);
    promise.then(function(imResponse) {
      // The message is sent successfully.
      console.log(imResponse);
    }).catch(function(imError) {
      // The message fails to be sent.
      console.warn('sendMessage error:', imError);
    });
  }
});

Parameters:

Returns:

Type

Message

createMergerMessage(options) → {Message}

Example

// 1. Forward group messages to a C2C conversation.
// message1, message2, and message3 are group messages.
let mergerMessage = tim.createMergerMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  payload: {
    messageList: [message1, message2, message3],
    title: 'Chat Records of the Talent Center in the Greater Bay Area',
    abstractList: ['allen: 666', 'iris: [Image]', 'linda: [File]'],
    compatibleText: 'Please upgrade your IM SDK to v2.10.1 or later to view this message.'
  },
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
});
// 2. Send the message.
let promise = tim.sendMessage(mergerMessage);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

downloadMergerMessage(message) → {Promise}

Example

// If downloadKey exists, the combined message received is stored on the cloud, and you need to download it first.
if (message.type === TIM.TYPES.MSG_MERGER && message.payload.downloadKey !== '') {
  let promise = tim.downloadMergerMessage(message);
  promise.then(function(imResponse) {
    // After the download is successful, the SDK updates information such as message.payload.messageList.
    console.log(imResponse.data);
  }).catch(function(imError) {
    // Download failed
    console.warn('downloadMergerMessage error:', imError);
  });
}

Parameters:

Returns:

Type

Promise

createForwardMessage(options) → {Message}

Example

let forwardMessage = tim.createForwardMessage({
  to: 'user1',
  conversationType: TIM.TYPES.CONV_C2C,
  // Message priority, applicable to group chats. If messages in a group exceed the frequency limit, the backend delivers high-priority messages first. For more information, see 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.
  // Enumerated values supported: TIM.TYPES.MSG_PRIORITY_HIGH, TIM.TYPES.MSG_PRIORITY_NORMAL (default), TIM.TYPES.MSG_PRIORITY_LOW, and TIM.TYPES.MSG_PRIORITY_LOWEST
  // priority: TIM.TYPES.MSG_PRIORITY_NORMAL,
  payload: message, // Message instances, including messages received and sent by yourself
  // Message custom data (saved in the cloud, will be sent to the peer end, and can still be pulled after the app is uninstalled and reinstalled; supported from v2.10.2)
  // cloudCustomData: 'your cloud custom data'
});
// 2. Send the message.
let promise = tim.sendMessage(forwardMessage);
promise.then(function(imResponse) {
  // The message is sent successfully.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be sent.
  console.warn('sendMessage error:', imError);
});

Parameters:

Returns:

Type

Message

sendMessage(message, optionsopt) → {Promise}

Examples

// If the recipient is offline, the message will be stored in the roaming server and pushed offline on the precondition that the recipient's app switches to the background or the process is killed. The default title and content of offline push are kept.
// For more information on offline push, see https://cloud.tencent.com/document/product/269/3604.
tim.sendMessage(message);

// The message sending option is supported from v2.6.4.
tim.sendMessage(message, {
  onlineUserOnly: true // If the recipient is offline, the message is neither stored in the roaming server nor pushed offline.
});

// The message sending option is supported from v2.6.4.
tim.sendMessage(message, {
  offlinePushInfo: {
    disablePush: true // If the recipient is offline, the message is stored in the roaming server, but is not pushed offline.
  }
});

// The message sending option is supported from v2.6.4.
tim.sendMessage(message, {
  // If the recipient is offline, the message will be stored in the roaming server and pushed offline on the precondition that the recipient's app switches to the backend or the process is killed. The title and content of offline push can be customized at the access side.
  offlinePushInfo: {
    title: '', // Offline push title
    description: '', // Offline push content
    androidOPPOChannelID: '' // Offline push channel ID for OPPO phones that run Android 8.0 or later
  }
});

Parameters:

Returns:

Type

Promise

revokeMessage(message) → {Promise}

Examples

// Proactively recall a message.
let promise = tim.revokeMessage(message);
promise.then(function(imResponse) {
  // The message is successfully recalled.
}).catch(function(imError) {
  // The message fails to be recalled.
  console.warn('revokeMessage error:', imError);
});

// The message recall notification is received.
tim.on(TIM.EVENT.MESSAGE_REVOKED, function(event) {
  // event.name - TIM.EVENT.MESSAGE_REVOKED
  // event.data - An array that stores Message objects - [Message] - The isRevoked value of each Message object is true.
});

// Obtain a message list which contains recalled messages.
let promise = tim.getMessageList({conversationID: 'C2Ctest', count: 15});
promise.then(function(imResponse) {
  const messageList = imResponse.data.messageList; // Message list
  messageList.forEach(function(message) {
    if (message.isRevoked) {
      // Handle the recalled messages.
    } else {
      // Handle common messages.
    }
  });
});

Parameters:

Returns:

Type

Promise

resendMessage(message) → {Promise}

Example

// Resend a message.
let promise = tim.resendMessage(message); // Pass in the message instance that needs to be resent.
promise.then(function(imResponse) {
  // The message is successfully resent.
  console.log(imResponse);
}).catch(function(imError) {
  // The message fails to be resent.
  console.warn('resendMessage error:', imError);
});

Parameters:

Returns:

Type

Promise

deleteMessage(messageList) → {Promise}

Example

// Delete message. Supported from v2.12.0.
let promise = tim.deleteMessage([message1, message2, message3, ...]);
promise.then(function(imResponse) {
  // Messages are deleted successfully.
}).catch(function(imError) {
  // Messages fail to be deleted.
  console.warn('deleteMessage error:', imError);
});

Parameters:

Returns:

Type

Promise

getMessageList(options) → {Promise}

See:

• Roaming Message Storage

• Message

Examples

/ Pull the message list for the first time when a conversation is opened.
let promise = tim.getMessageList({conversationID: 'C2Ctest', count: 15});
promise.then(function(imResponse) {
  const messageList = imResponse.data.messageList; // Message list.
  const nextReqMessageID = imResponse.data.nextReqMessageID; // This parameter must be passed in for the next pulling by page.
  const isCompleted = imResponse.data.isCompleted; // It indicates whether all messages have been pulled.
});

// Pull down to see more messages.
let promise = tim.getMessageList({conversationID: 'C2Ctest', nextReqMessageID, count: 15});
promise.then(function(imResponse) {
  const messageList = imResponse.data.messageList; // Message list.
  const nextReqMessageID = imResponse.data.nextReqMessageID; // This parameter must be passed in for the next pulling by page.
  const isCompleted = imResponse.data.isCompleted; // It indicates whether all messages have been pulled.
});

Parameters:

Returns:

Type

Promise

setMessageRead(options) → {Promise}

Example

// Set all unread messages of a conversation to the read state
let promise = tim.setMessageRead({conversationID: 'C2Cexample'});
promise.then(function(imResponse) {
  // Unread messages are set to the read state successfully. The value of the unreadCount property of the corresponding conversation with the specified ID is set to 0.
}).catch(function(imError) {
  // Failed to set unread messages to the read state.
  console.warn('setMessageRead error:', imError);
});

Parameters:

Returns:

Type

Promise

getConversationList() → {Promise}

See:

• Conversation

Example

// Pull the conversation list
let promise = tim.getConversationList();
promise.then(function(imResponse) {
  const conversationList = imResponse.data.conversationList; // This conversation list will overwrite the original conversation list.
}).catch(function(imError) {
  console.warn('getConversationList error:', imError); // Error information
});

Returns:

Type

Promise

getConversationProfile(conversationID) → {Promise}

See:

• Conversation Structure Description

Example

let promise = tim.getConversationProfile(conversationID);
promise.then(function(imResponse) {
  // The conversation profile is successfully obtained.
  console.log(imResponse.data.conversation); // Conversation profile
}).catch(function(imError) {
  console.warn('getConversationProfile error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

deleteConversation(conversationID) → {Promise}

See:

• Conversation Structure Description

Example

let promise = tim.deleteConversation('C2CExample');
promise.then(function(imResponse) {
  // The conversation is deleted successfully.
  const { conversationID } = imResponse.data;// ID of the deleted conversation
}).catch(function(imError) {
  console.warn('deleteConversation error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

pinConversation(options) → {Promise}

Examples

// Pin a conversation to top. Supported from v2.14.0.
let promise = tim.pinConversation({ conversationID: 'C2CExample', isPinned: true });
promise.then(function(imResponse) {
  // The conversation is pinned to top successfully.
  const { conversationID } = imResponse.data; // ID of the conversation pinned to top
}).catch(function(imError) {
  console.warn('pinConversation error:', imError); // Error information
});

// Unpin a conversation from top. Supported from v2.14.0.
let promise = tim.pinConversation({ conversationID: 'C2CExample', isPinned: false });
promise.then(function(imResponse) {
  // The conversation is unpinned from top successfully.
  const { conversationID } = imResponse.data; // ID of the conversation unpinned from top
}).catch(function(imError) {
  console.warn('pinConversation error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getMyProfile() → {Promise}

See:

• Profile Structure Description

Example

let promise = tim.getMyProfile();
promise.then(function(imResponse) {
  console.log(imResponse.data); // Personal profile - profile instance
}).catch(function(imError) {
  console.warn('getMyProfile error:', imError); // Error information
});

Returns:

Type

Promise

getUserProfile(options) → {Promise}

Example

let promise = tim.getUserProfile({
  userIDList: ['user1', 'user2'] // Note: even if you retrieve the profile of only one user, the value must be of array type, for example, userIDList: ['user1'].
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Array that stores other users' profiles - [Profile]
}).catch(function(imError) {
  console.warn('getUserProfile error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

updateMyProfile(options) → {Promise}

Examples

// Modify your personal standard profile.
let promise = tim.updateMyProfile({
  nick: 'My nickname',
  avatar: 'http(s)://url/to/image.jpg',
  gender: TIM.TYPES.GENDER_MALE,
  selfSignature: 'My status',
  allowType: TIM.TYPES.ALLOW_TYPE_ALLOW_ANY
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // The profile is updated.
}).catch(function(imError) {
  console.warn('updateMyProfile error:', imError); // Error information
});

// Modify personal custom profile fields
// Custom profile fields must be configured in the IM console in advance. For more information, see 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({
  // Ensure that you have applied for the custom profile field Tag_Profile_Custom_Test1 in the IM console by clicking the desired app card and choosing Feature Configuration > User Custom Field.
  // Note: even if only this one custom data field exists, the format of profileCustomField must be of array type.
  profileCustomField: [
    {
      key: 'Tag_Profile_Custom_Test1',
      value: 'My custom profile 1'
    }
  ]
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // The profile is updated.
}).catch(function(imError) {
  console.warn('updateMyProfile error:', imError); // Error information
});

// Modify personal standard and custom profile fields
let promise = tim.updateMyProfile({
  nick: 'My nickname',
  // Ensure that you have applied for the custom profile fields Tag_Profile_Custom_Test1 and Tag_Profile_Custom_Test2 in the IM console by clicking the desired app card and choosing Feature Configuration > User Custom Field.
  profileCustomField: [
    {
      key: 'Tag_Profile_Custom_Test1',
      value: 'My custom profile 1'
    },
    {
      key: 'Tag_Profile_Custom_Test2',
      value: 'My custom profile 2'
    },
  ]
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // The profile is updated.
}).catch(function(imError) {
  console.warn('updateMyProfile error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getBlacklist() → {Promise}

Example

let promise = tim.getBlacklist();
promise.then(function(imResponse) {
  console.log(imResponse.data); // Your blocklist. The value is an array that contains userIDs - [userID].
}).catch(function(imError) {
  console.warn('getBlacklist error:', imError); // Error information
});

Returns:

Type

Promise

addToBlacklist(options) → {Promise}

Example

let promise = tim.addToBlacklist({userIDList: ['user1', 'user2']}); // Note: even if you add only one userID to the blocklist, the value must be of array type, for example, userIDList: ['user1'].
promise.then(function(imResponse) {
  console.log(imResponse.data); // Information on the userIDs that are added to the blocklist. The value must be an array that contains userIDs - [userID].
}).catch(function(imError) {
  console.warn('addToBlacklist error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

removeFromBlacklist(options) → {Promise}

Example

let promise = tim.removeFromBlacklist({userIDList: ['user1', 'user2']}); // Note: even if you remove only one userID from the blocklist, the value must be of array type, for example, userIDList: ['user1'].
promise.then(function(imResponse) {
  console.log(imResponse.data); // List of userIDs that are successfully removed from the blocklist. The value is an array that contains the userIDs - [userID].
}).catch(function(imError) {
  console.warn('removeFromBlacklist error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getFriendList() → {Promise}

Example

let promise = tim.getFriendList();
promise.then(function(imResponse) {
  const friendList = event.data; // Friend list
}).catch(function(imError) {
  console.warn('getFriendList error:', imError); // Error information
});

Returns:

Type

Promise

addFriend(options) → {Promise}

Example

// Add a friend
let promise = tim.addFriend({
  to: 'user1',
  source: 'AddSource_Type_Web',
  remark: 'Jane',
  groupName: 'Friend',
  wording: 'I'm user0',
  type: TIM.TYPES.SNS_ADD_TYPE_BOTH,
});
promise.then(function(imResponse) {
  // The friend request is sent successfully.
  const { code } = imResponse.data;
  if (code === 30539) {
    // 30539 indicates that user1 has set the friend request processing method to manually accept friend requests received. The SDK will trigger the TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED event.
  } else if (code === 0) {
    // 0 indicates that user1 has set the friend request processing method to automatically accept all friend requests received. The SDK will trigger the TIM.EVENT.FRIEND_LIST_UPDATED event.
  }
}).catch(function(imError) {
  console.warn('addFriend error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

deleteFriend(options) → {Promise}

Example

let promise = tim.deleteFriend({
  userIDList: ['user1','user2'],
  type: TIM.TYPES.SNS_DELETE_TYPE_BOTH
});
promise.then(function(imResponse) {
  const { successUserIDList, failureUserIDList } = imResponse.data;
  // List of friend userIDs that are successfully deleted
  successUserIDList.forEach((item) => {
    const { userID } = item;
  });
  // List of friend userIDs that fail to be deleted
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
  // If the friend list is updated, the SDK triggers the TIM.EVENT.FRIEND_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('removeFromFriendList error:', imError);
});

Parameters:

Returns:

Type

Promise

checkFriend(options) → {Promise}

Example

let promise = tim.checkFriend({
  userIDList: ['user0','user1'],
  type: TIM.TYPES.SNS_CHECK_TYPE_BOTH,
});
promise.then(function(imResponse) {
  const { successUserIDList, failureUserIDList } = imResponse.data;
  // List of friend userIDs that pass the verification
  successUserIDList.forEach((item) => {
    const { userID, code, relation } = item; // The value of code is always 0.
    // Possible results of one-way friend verification are:
    // - relation: TIM.TYPES.SNS_TYPE_NO_RELATION: B is not on A's friend list, but it cannot determine whether A is on B's friend list.
    // - relation: TIM.TYPES.SNS_TYPE_A_WITH_B: B is on A's friend list, but it cannot determine whether A is on B's friend list.
    // Possible results of two-way friend verification are:
    // - relation: TIM.TYPES.SNS_TYPE_NO_RELATION: A and B are not on each other's friend list
    // - relation: TIM.TYPES.SNS_TYPE_A_WITH_B: B is on A's friend list, but A is not on B's friend list
    // - relation: TIM.TYPES.SNS_TYPE_B_WITH_A: B is not on A's friend list, but A is on B's friend list
    // - relation: TIM.TYPES.SNS_TYPE_BOTH_WAY: A and B are on each other's friend list
  });
  // List of friend userIDs that fail the verification
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
}).catch(function(imError) {
  console.warn('checkFriend error:', imError);
});

Parameters:

Returns:

Type

Promise

getFriendProfile(options) → {Promise}

Example

let promise = tim.getFriendProfile({
  userIDList: ['user0','user1']
});
promise.then(function(imResponse) {
  const { friendList, failureUserIDList } = imResponse.data;
  friendList.forEach((friend) => {
    // Friend object
  });
  // List of failed userIDs
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

updateFriend(options) → {Promise}

Examples

// Update friend remarks
let promise = tim.updateFriend({
  userID: 'user1',
  remark: 'helloworld'
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Friend instance
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // Update failure
});

// Update custom friend fields
let promise = tim.updateFriend({
  userID: 'user1',
  friendCustomField: [
    // Custom friend fields must use the prefix 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 instance
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // Update failure
});

Parameters:

Returns:

Type

Promise

getFriendApplicationList() → {Promise}

Example

let promise = tim.getFriendApplicationList();
promise.then(function(imResponse) {
  // friendApplicationList - Friend request list - [FriendApplication]
  // unreadCount - Unread friend request count
  // const { friendApplicationList, unreadCount } = imResponse.data;
}).catch(function(imError) {
  console.warn('getFriendApplicationList error:', imError); // Error information
});

Returns:

Type

Promise

acceptFriendApplication(options) → {Promise}

Example

let promise = tim.acceptFriendApplication({
  userID: 'user1',
  remark: 'Customer service Jack',
  type: TIM.TYPES.SNS_APPLICATION_AGREE_AND_ADD
});
promise.then(function(imResponse) {
  // When the friend request is successfully accepted, the SDK triggers the TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('acceptFriendApplication error:', imError);
});

Parameters:

Returns:

Type

Promise

refuseFriendApplication(options) → {Promise}

Example

let promise = tim.refuseFriendApplication({
  userID: 'user1',
});
promise.then(function(imResponse) {
// When the friend request is successfully rejected, the SDK triggers the TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('refuseFriendApplication error:', imError);
});

Parameters:

Returns:

Type

Promise

deleteFriendApplication(options) → {Promise}

Example

let promise = tim.deleteFriendApplication({
  userID: 'user1',
  type: TIM.TYPES.SNS_APPLICATION_SENT_TO_ME
});
promise.then(function(imResponse) {
  // When the friend request is successfully deleted, the SDK triggers the TIM.EVENT.FRIEND_APPLICATION_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('deleteFriendApplication error:', imError);
});

Parameters:

Returns:

Type

Promise

setFriendApplicationRead() → {Promise}

Example

// Set a friend request as read
let promise = tim.setFriendApplicationRead();
promise.then(function(imResponse) {
  // Successfully set a friend request as read
}).catch(function(imError) {
  console.warn('setFriendApplicationRead error:', imError);
});

Returns:

Type

Promise

getFriendGroupList() → {Promise}

Example

let promise = tim.getFriendGroupList();
promise.then(function(imResponse) {
  const friendGroupList = event.data; // List of friend lists
}).catch(function(imError) {
  console.warn('getFriendGroupList error:', imError); // Error information
});

Returns:

Type

Promise

createFriendGroup(options) → {Promise}

Example

let promise = tim.createFriendGroup({
  name: 'My friend list 1',
  userIDList: ['user0','user1']
});
promise.then(function(imResponse) {
  const { friendGroup,failureUserIDList } = imResponse;
  // friendGroup - Friend list instance
  // failureUserIDList - List of failed userIDs
  // When the friend list is successfully created, the SDK triggers the TIM.EVENT.FRIEND_GROUP_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('getFriendGroupInfo error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

deleteFriendGroup(options) → {Promise}

Example

let promise = tim.deleteFriendGroup({
  name: 'My friend list 1',
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Friend list instance
  // When the friend list is successfully deleted, the SDK triggers the TIM.EVENT.FRIEND_GROUP_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('deleteFriendGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

addToFriendGroup(options) → {Promise}

Example

let promise = tim.addToFriendGroup({
  name: 'My friend list 1',
  userIDList: ['user1','user2'],
});
promise.then(function(imResponse) {
  const { friendGroup, failureUserIDList } = imResponse.data;
  // friendGroup - Friend list instance
  // failureUserIDList - List of failed userIDs
  // When the friends are successfully added to the friend list, the SDK triggers the TIM.EVENT.FRIEND_GROUP_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('addToFriendGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

removeFromFriendGroup(options) → {Promise}

Example

let promise = tim.removeFromFriendGroup({
  name: 'My friend list 1',
  userIDList: ['user1','user2'],
});
promise.then(function(imResponse) {
  const { friendGroup, failureUserIDList } = imResponse.data;
  // friendGroup - Friend list instance
  // failureUserIDList - List of failed userIDs
  // When the friends are successfully removed from the friend list, the SDK triggers the TIM.EVENT.FRIEND_GROUP_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('addToFriendGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

renameFriendGroup(options) → {Promise}

Example

let promise = tim.renameFriendGroup({
  oldName: 'Friends',
  newName: 'Besties'
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Friend list instance
  // When the name of a friend list is changed successfully, the SDK triggers the TIM.EVENT.FRIEND_GROUP_LIST_UPDATED event.
}).catch(function(imError) {
  console.warn('updateMyProfile error:', imError);
});

Parameters:

Returns:

Type

Promise

getGroupList(options) → {Promise}

See:

• Group

Examples

// This API pulls only the following information by default: group type, group name, group profile photo, and the time of the last message.
let promise = tim.getGroupList();
promise.then(function(imResponse) {
  console.log(imResponse.data.groupList); // Group list
}).catch(function(imError) {
  console.warn('getGroupList error:', imError); // Error information
});

// If the profile fields that are pulled by default fail to meet your requirements, you can pull additional profile fields by referring to the following code.
let promise = tim.getGroupList({
   groupProfileFilter: [TIM.TYPES.GRP_PROFILE_OWNER_ID],
});
promise.then(function(imResponse) {
  console.log(imResponse.data.groupList); // Group list
}).catch(function(imError) {
  console.warn('getGroupList error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getGroupProfile(options) → {Promise}

See:

• Group

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); // Error information
});

Parameters:

Returns:

Type

Promise

createGroup(options) → {Promise}

See:

• Group
• Group Types

Example

// Create a work group
let promise = tim.createGroup({
  type: TIM.TYPES.GRP_WORK,
  name: 'WebSDK',
  memberList: [{
    userID: 'user1',
    // Group member custom field. By default, this parameter is not available and needs to be enabled. For details, see Custom Fields.
    memberCustomField: [{key: 'group_member_test', value: 'test'}]
  }, {
    userID: 'user2'
  }] // If memberList is specified, userID must also be specified.
});
promise.then(function(imResponse) { // Created successfully
  console.log(imResponse.data.group); // Profile of the created group
  // A member list is specified during group creation, but a certain user has exceeded the limit on the number of groups a single user can join.
  // If you specify userX, who has joined N groups (maximum number of groups userX can join), as a member of the group during group creation, userX cannot join the group properly.
  // The SDK places the information of userX in overLimitUserIDList for the access side to process.
  console.log(imResponse.data.overLimitUserIDList); // List of users who have exceeded the limit on the number of groups a single user can join. (Supported from v2.10.2)
}).catch(function(imError) {
  console.warn('createGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

dismissGroup(groupID) → {Promise}

See:

• Group
• Group Management

Example

let promise = tim.dismissGroup('group1');
promise.then(function(imResponse) { // Deleted successfully
  console.log(imResponse.data.groupID); // ID of the deleted group
}).catch(function(imError) {
  console.warn('dismissGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

updateGroupProfile(options) → {Promise}

See:

• Group
• Group Management

Examples

let promise = tim.updateGroupProfile({
  groupID: 'group1',
  name: 'new name', // Modify the group name
  introduction: 'this is introduction.', // Modify the group introduction
  // Starting from v2.6.0, group members can receive group messages about group custom field modifications and obtain related content. For more information, see Message.payload.newGroupProfile.groupCustomField.
  groupCustomField: [{ key: 'group_level', value: 'high'}] // Modify the group custom field
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group) // Detailed group profile after modification
}).catch(function(imError) {
  console.warn('updateGroupProfile error:', imError); // Error information
});

// Starting from v2.6.2, the SDK supports muting and unmuting all. Currently, when all users are muted in a group, group notifications cannot be delivered.
let promise = tim.updateGroupProfile({
  groupID: 'group1',
  muteAllMembers: true, // true: mute all; false: unmute all
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group) // Detailed group profile after modification
}).catch(function(imError) {
  console.warn('updateGroupProfile error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

joinGroup(options) → {Promise}

See:

• Group

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: // Waiting to be approved by the admin
      break;
    case TIM.TYPES.JOIN_STATUS_SUCCESS: // Joined the group successfully
      console.log(imResponse.data.group); // Profile of the group
      break;
    case TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: // The user is already in the group
      break;
    default:
      break;
  }
}).catch(function(imError){
  console.warn('joinGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

quitGroup(groupID) → {Promise}

See:

• Group
• Group Management

Example

let promise = tim.quitGroup('group1');
promise.then(function(imResponse) {
  console.log(imResponse.data.groupID); // ID of the group that the user leaves
}).catch(function(imError){
  console.warn('quitGroup error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

searchGroupByID(groupID) → {Promise}

See:

• Group

Example

let promise = tim.searchGroupByID('group1');
promise.then(function(imResponse) {
  const group = imResponse.data.group; // Group information
}).catch(function(imError) {
  console.warn('searchGroupByID error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getGroupOnlineMemberCount(groupID) → {Promise}

See:

• Group

Example

// Get the number of online users in an audio-video group (supported from 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); // Error information
});

Parameters:

Returns:

Type

Promise

changeGroupOwner(options) → {Promise}

See:

• Group

Example

let promise = tim.changeGroupOwner({
  groupID: 'group1',
  newOwnerID: 'user2'
});
promise.then(function(imResponse) { // Transferred successfully
  console.log(imResponse.data.group); // Group profile
}).catch(function(imError) { // Failed to transfer the group
  console.warn('changeGroupOwner error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

handleGroupApplication(options) → {Promise}

See:

• Group

Example

let promise = tim.handleGroupApplication({
  handleAction: 'Agree',
  handleMessage: 'Welcome',
  message: message // The message instance of the group system notification for an application to join a group.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile
}).catch(function(imError){
  console.warn('handleGroupApplication error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

initGroupAttributes(options) → {Promise}

Example

let promise = tim.initGroupAttributes({
  groupID: 'group1',
  groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) { // Initialized successfully
  console.log(imResponse.data.groupAttributes); // Group attributes initialized successfully
}).catch(function(imError) { // Initialization failed
  console.warn('initGroupAttributes error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setGroupAttributes(options) → {Promise}

Example

let promise = tim.setGroupAttributes({
  groupID: 'group1',
  groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) { // Set successfully
  console.log(imResponse.data.groupAttributes); // Group attributes set successfully
}).catch(function(imError) { // Setting failed
  console.warn('setGroupAttributes error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

deleteGroupAttributes(options) → {Promise}

Examples

// Delete specified group attributes
let promise = tim.deleteGroupAttributes({
  groupID: 'group1',
  keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // Deleted successfully
  console.log(imResponse.data.keyList); // List of group attributes deleted successfully
}).catch(function(imError) { // Deletion failed
  console.warn('deleteGroupAttributes error:', imError); // Error information
});

// Delet all group attributes
let promise = tim.deleteGroupAttributes({
  groupID: 'group1',
  keyList: []
});
promise.then(function(imResponse) { // Deleted successfully
  console.log(imResponse.data.keyList); // List of group attributes deleted successfully
}).catch(function(imError) { // Deletion failed
  console.warn('deleteGroupAttributes error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getGroupAttributes(options) → {Promise}

Examples

// Get specified group attributes
let promise = tim.getGroupAttributes({
  groupID: 'group1',
  keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.groupAttributes); // Specified group attributes
}).catch(function(imError) { // Getting failed
  console.warn('getGroupAttributes error:', imError); // Error information
});

// Get all group attributes
let promise = tim.getGroupAttributes({
  groupID: 'group1',
  keyList: []
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.groupAttributes); // All group attributes
}).catch(function(imError) { // Getting failed
  console.warn('getGroupAttributes error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

getGroupMemberList(options) → {Promise}

See:

• GroupMember

Examples

let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // Pull 30 group members starting from 0
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
}).catch(function(imError) {
  console.warn('getGroupMemberList error:', imError);
});

// Starting from v2.6.2, this API can be used to pull the muting stop timestamps of group members.
let promise = tim.getGroupMemberList({ groupID: 'group1', count: 30, offset:0 }); // Pull 30 group members starting from 0.
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
  for (let groupMember of imResponse.data.memberList) {
    if (groupMember.muteUntil * 1000  > Date.now()) {
      console.log(`${groupMember.userID} muted`);
    } else {
      console.log(`${groupMember.userID} not muted`);
    }
  }
}).catch(function(imError) {
    console.warn('getGroupMemberProfile error:', imError);
});

Parameters:

Returns:

Type

Promise

getGroupMemberProfile(options) → {Promise}

See:

• GroupMember

Example

let promise = tim.getGroupMemberProfile({
  groupID: 'group1',
  userIDList: ['user1', 'user2'], // Note: even if you retrieve the profile of only one group member, the value must be of array type, for example, userIDList: ['user1'].
  memberCustomFieldFilter: ['group_member_custom'], // Group member custom field to query: group_member_custom
});
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
}).catch(function(imError) {
  console.warn('getGroupMemberProfile error:', imError);
});

Parameters:

Returns:

Type

Promise

addGroupMember(options) → {Promise}

See:

• Group
• GroupMember
• Differences in Group Member Operations

Example

let promise = tim.addGroupMember({groupID: 'group1', userIDList: ['user1','user2','user3']});
promise.then(function(imResponse) {
  console.log(imResponse.data.successUserIDList); // userIDList of group members that were added successfully
  console.log(imResponse.data.failureUserIDList); // userIDList of group members that failed to be added
  console.log(imResponse.data.existedUserIDList); // userIDList of group members that were already in the group
  // If you specify userX, who has joined N groups (maximum number of groups userX can join), as a member of the group, userX cannot join the group properly.
  // The SDK places the information of userX in overLimitUserIDList for the access side to process.
  console.log(imResponse.data.overLimitUserIDList); // List of users who have exceeded the limit on the number of groups a single user can join. (Supported from v2.10.2)
  console.log(imResponse.data.group); // Group profile displayed after group members addition
}).catch(function(imError) {
  console.warn('addGroupMember error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

deleteGroupMember(options) → {Promise}

See:

• Group
• GroupMember

Example

let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: 'You are deleted from the group because you have violated the group rules.'});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile displayed after group member deletion
  console.log(imResponse.data.userIDList); // List of userIDs of the deleted group members
}).catch(function(imError) {
  console.warn('deleteGroupMember error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setGroupMemberMuteTime(options) → {Promise}

See:

• Group
• GroupMember
• Differences in Group Message Management

Example

let promise = tim.setGroupMemberMuteTime({
  groupID: 'group1',
  userID: 'user1',
  muteTime: 600 // The user is muted for 10 minutes. If the value is set to 0, the user is unmuted.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.member); // New group member profile
}).catch(function(imError) {
  console.warn('setGroupMemberMuteTime error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setGroupMemberRole(options) → {Promise}

See:

• Group
• GroupMember

Example

let promise = tim.setGroupMemberRole({
  groupID: 'group1',
  userID: 'user1',
  role: TIM.TYPES.GRP_MBR_ROLE_ADMIN // Set user1 as the admin of group1.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.member); // New group member profile
}).catch(function(imError) {
  console.warn('setGroupMemberRole error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setGroupMemberNameCard(options) → {Promise}

See:

• Group
• GroupMember

Example

let promise = tim.setGroupMemberNameCard({ groupID: 'group1', userID: 'user1', nameCard: 'Name card' });
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.member); // New group member profile
}).catch(function(imError) {
  console.warn('setGroupMemberNameCard error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setGroupMemberCustomField(options) → {Promise}

See:

• Group
• GroupMember

Example

let promise = tim.setGroupMemberCustomField({ groupID: 'group1', memberCustomField: [{key: 'group_member_test', value: 'test'}]});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.member); // New group member profile
}).catch(function(imError) {
  console.warn('setGroupMemberCustomField error:', imError); // Error information
});

Parameters:

Returns:

Type

Promise

setMessageRemindType(options) → {Promise}

See:

• Group
• GroupMember

Examples

// Mute notifications
let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_DISCARD });
promise.then(function(imResponse) {
  console.log(imResponse.data.group.selfInfo); // Information of the current user in the group
}).catch(function(imError) {
  console.warn('setMessageRemindType error:', imError);
});

// Enable new message alert after muting notifications
let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_ACPT_AND_NOTE });
promise.then(function(imResponse) {
  console.log(imResponse.data.group.selfInfo); // Information of the current user in the group
}).catch(function(imError) {
  console.warn('setMessageRemindType error:', imError);
});

Parameters:

Returns:

Type

Promise