Send Message

This document introduces how to send messages from the client, applicable to one-to-one chat, group chat, and chatroom.

Please note that the client SDK has a message sending rate limit, with a maximum of 5 messages per second.

Send Message

sendMessage is the basic interface for sending messages, which can be used to send built-in message types or custom messages in IMLib. For specific message types, IMLib also provides multiple convenient syntactic sugar methods.

Take calling sendMessage to send a text message mentioning @张三 in a group chat as an example.

Define the target group conversation and instantiate the message to be sent. Since it's a group @ message, mentionedInfo needs to be added.

// Define the target conversation, here we define a group type conversation
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<Target ID>' }
// Instantiate the message to be sent, RongIMLib.TextMessage is a built-in text message
const message = new RongIMLib.TextMessage({
  // Text content
  content: 'Text content',
  // (Optional) Additional information in the message, passed to the receiver
  extra: 'Additional information',
  // For group messages, if you need to send @ messages, add the mentionedInfo field
  mentionedInfo: {
    // @ type: all, individual
    type: RongIMLib.MentionedType.SINGAL,
    // @ user list
    userIdList: [zhangsan],
    // @ content
    mentionedContent: ''
  }
})

Construct the send options ISendMessageOptions, used to define some optional configurations in the sending behavior. Since it's a group @ message, isMentioned in options must be set to true.

// Configuration properties
const options = {
  // If you need to send @ messages, isMentioned needs to be set to true
  isMentioned: true,
  // Callback before sending the message, you can use the message returned by this callback for list rendering
  onSendBefore: (message) => {
    console.log('Callback before sending the message', message)
  }
}

Send the message. If the message is sent successfully, you can change the status of the message in the list to "sent successfully" based on the messageId field in the returned result.

// Send the message
RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // The message is sent successfully, you can change the status of the message in the list to "sent successfully" based on the messageId field in the returned result.
    console.log('Message sent successfully', res.data)
  } else {
    console.log('Message sending failed', res.code, res.msg)
  }
})

If the message fails to send, you can change the status of the message in the list to "failed to send" based on the messageId field in the returned result and resend the message.

When the client encounters a message sending failure, the following situations may occur:
1. The message was not delivered to the RC server, or the RC server returned a failure after delivery (others did not receive it).
2. In some extreme cases (such as a weak network environment), the message may have been successfully delivered to the recipient. However, the sender did not receive the RC server's receipt in time, and after a timeout, it was considered a failure. In this case, resending the message on the client side will cause the recipient to receive the message repeatedly. For a detailed explanation of this issue, please refer to the FAQ.
Resend the message. The resent message must be consistent with the original message.

tip

Starting from version 5.5.1, the SDK supports passing the original message's messageId in options when resending a message. The RC server will not deduplicate messages, and the application layer can use this ID to determine whether the message is a duplicate and handle it accordingly. This ID can be obtained from the message object returned by the onSendBefore callback or from the returned result.

    // Define the target conversation, here we define a group type conversation
    const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<Target ID>' }
    // Instantiate the message to be sent, RongIMLib.TextMessage is a built-in text message
    const message = new RongIMLib.TextMessage({ content: 'Text content' })
    // Configuration properties
    const options = {
      // The messageId of the resent message, which can be obtained from the message object returned by the onSendBefore callback or from the returned result
      messageId: 0
    }

    RongIMLib.sendMessage(conversation, message, options).then(res => {
      if (res.code === RongIMLib.ErrorCode.SUCCESS) {
        // The message is sent successfully, you can change the status of the message in the list to "sent successfully" based on the messageId field in the returned result.
        console.log('Message sent successfully', res.data)
      } else {
        // The message failed to send, you can change the status of the message in the list to "failed to send" based on the messageId field in the returned result.
        console.log('Message sending failed', res.code, res.msg)
      }
    })

sendMessage Interface Description

sendMessage method accepts three parameters: conversation, message, and options.

conversation defines the target conversation. See IConversationOption.

Parameter Type Description
conversationType ConversationType Conversation type
targetId string Receiver ID
message is the content of the message to be sent, supporting IMLib built-in messages (e.g., RongIMLib.TextMessage) or custom message instances implemented via RongIMLib.registerMessageType().

Parameter	Type	Description
conversationType	ConversationType	Conversation type
targetId	string	Receiver ID

options defines some optional configurations in the sending behavior, such as whether it can be expanded, push notifications, etc. See ISendMessageOptions

Parameter	Type	Description
~~isStatusMessage~~	boolean	(Deprecated) Whether it is a status message (optional)
disableNotification	boolean	Whether to send a silent message (optional)
pushContent	string	Push information (optional)
pushData	string	Additional information carried by the push notification (optional)
isMentioned	boolean	Whether it is an @ message. Only valid when `conversationType` is group or ultra group (optional)
~~mentionedType~~	`1｜2`	(Deprecated) @ message type, 1: @ all 2: @ specified users (optional) Deprecated
~~mentionedUserIdList~~	string[]	(Deprecated) List of user IDs being @ (optional)
directionalUserIdList	string[]	Used to send targeted messages, only valid when `conversationType` is group or ultra group. Note, if SDK version < 5.9.4, only groups support targeted messages. (optional)
isVoipPush	boolean	When the recipient is an iOS device and offline, they will receive a Voip Push. This configuration has no effect on Android. (optional)
canIncludeExpansion	boolean	Whether the message can be expanded
expansion	[key: string]: string	Message expansion content data (optional)
isFilerWhiteBlacklist	boolean	Blocklist/Allowlist (optional)
pushConfig	IPushConfig	Mobile push configuration (optional) (similar to MessagePushConfig on Android and iOS)
onSendBefore	Function	Callback before sending the message, supported from version 5.4.0
messageId	number	When resending a message, pass the messageId of the message to be resent. All parameters of the resent message must be consistent with the original message. Supported from version 5.5.1
disableUpdateLastMessage	boolean	Disable updating the last message of the conversation, default is false. Supported from version 5.12.2.

IPushConfig Parameter Description

Parameter	Type	Description
pushTitle	string	Push title, if not set: for one-to-one chat, the sender's name is displayed as the notification title; for group chat, the group name is displayed as the notification title; for custom messages, no title is displayed by default;
pushContent	string	Push content
pushData	string	Additional information for remote push
iOSConfig	IiOSPushConfig	(optional)
androidConfig	IAndroidPushConfig	(optional)
disablePushTitle	boolean	Whether to display the push title. Only effective for iOS platform
forceShowDetailContent	boolean	Whether to force push
templateId	string	Push template ID
harmonyOSConfig	IHarmonyOSPushConfig	(optional))

Built-in Message Types

IMLib provides predefined message types such as text, voice, image, GIF, file, etc.

Text Message

ITextMessageBody Parameter Description

Key	Type	Required	Description
content	string	Yes	Text content

Code Example

new RongIMLib.TextMessage({ content: '' })

Image Message

IImageMessageBody Parameter Description

Key	Type	Required	Description
content	string	Yes	Image thumbnail, should be a Base64 string. Generate the thumbnail yourself (suggested longest side not exceeding 240 pixels), encode it in Base64, and place it in `content`. The Base64 string length is recommended to be 5k, with a maximum of 10k. Note that some tools may include a Data URI prefix when converting images to Base64. For example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD`. Please discard the Data URI prefix and only keep the data part, for example: `/9j/4AAQSkZJRgABAgAAZABkAAD`.
imageUri	string	Yes	Remote access address of the image

Code Example

new RongIMLib.ImageMessage({
  content: '', // Image thumbnail, should be a Base64 string, and must not exceed 80KB
  imageUri: '' // Remote access address of the image
})

File Message

IFileMessageBody Parameter Description

Key	Type	Required	Description
name	string	Yes	File name
size	number	Yes	Image size, unit `Byte`
type	string	Yes	File type
fileUrl	string	Yes	Remote download address of the file

Code Example

new RongIMLib.FileMessage({
  name: '',
  size: 1000,
  type: '',
  fileUrl: ''
})

HQ Voice

IHQVoiceMessageBody Parameter Description

Key	Type	Required	Description
remoteUrl	string	Yes	Remote media resource address
duration	number	Yes	Voice duration, unit `s`. Please ensure the voice duration to be sent is within 60s
type	string	No	Encoding type, default `aac`. If your business also uses the Global IM UIKit SDK on Android/iOS, please use the default `aac` format, because Global IM UIKit's audio recording and playback only support the `aac` format by default and cannot play other formats. If your Android/iOS App will handle audio recording and playback on its own, you can choose the format as needed.

Code Example

new RongIMLib.HQVoiceMessage({
  remoteUrl: '<aac file address>',
  duration: 60,
})

Short Video Message

ISightMessageBody Parameter Description

Key	Type	Required	Description
sightUrl	string	Yes	Remote video resource address. If your business also uses the Global IM UIKit SDK on Android/iOS, you must use `H.264` + `AAC` encoded files, because Global IM UIKit's short video recording and playback only support this encoding combination.
content	string	Yes	Base64 string of the first frame thumbnail of the short video. Generate the thumbnail yourself (suggested longest side not exceeding 240 pixels), encode it in Base64, and place it in `content`. The Base64 string length is recommended to be 5k, with a maximum of 10k. Note that some tools may include a Data URI prefix when converting images to Base64. For example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD`. Please discard the Data URI prefix and only keep the data part, for example: `/9j/4AAQSkZJRgABAgAAZABkAAD`.
duration	number	Yes	Video duration. Please note that the default video duration limit on the server is 2 minutes. If you need to adjust the limit, please contact business.
size	number	Yes	Video size, unit `Byte`
name	number	Yes	Video name

Code Example

new RongIMLib.SightMessage({
  sightUrl: "<Remote address of the video resource>",
  content: "<Base64 of the thumbnail>"
  duration: 10,
  size: 100,
  name: "Video name"
})

GIF Message

IGIFMessageBody Parameter Description

Key	Type	Required	Description
gifDataSize	number	Yes	GIF image file size, unit `Byte`
remoteUrl	string	Yes	Remote storage address of the GIF image
width	number	Yes	Image width
height	number	Yes	Image height

Code Example

new RongIMLib.GIFMessage({
  gifDataSize: 30,
  remoteUrl: '<Image address>',
  width: 300,
  height: 200
})

Reference Message

IReferenceMessageBody Parameter Description

Parameter	Type	Required	Description
referMsgUserId	string	Yes	User ID of the referenced message sender
referMsg	any	Yes	Referenced message object
content	string	Yes	Input text message content
objName	string	Yes	Referenced message type

Code Example

new RongIMLib.ReferenceMessage({
  referMsgUserId: '<User ID of the referenced message>',
  referMsg: {
    content: 'Referenced message text'
  },
  referMsgUid: 'Message UId of the referenced message',
  content: 'Sent message content',
  objName: RongIMLib.MessageType.TEXT
})

Location Message

ILocationMessageBody Parameter Description

Parameter	Type	Required	Description
longitude	number	Yes	Longitude
latitude	number	Yes	Latitude
poi	string	Yes	Location information
content	string	Yes	Location thumbnail, the image needs to be a Base64 string without a prefix

Code Example

new RongIMLib.LocationMessage({
  latitude: '<Longitude of the location>',
  longitude: '<Latitude of the location>',
  poi: 'Location information',
  content: '<base64>'
})

Rich Text Message

IRichContentMessageBody Parameter Description

Parameter	Type	Required	Description
title	string	Yes	Title
content	string	Yes	Introduction content
imageUri	string	Yes	Displayed image address
url	string	Yes	Article link address

Code Example

new RongIMLib.RichContentMessage({
  title: 'Title',
  content: 'Introduction content',
  imageUri: '<Image address>',
  url: '<Article link address>'
})

Gray Bar Message

tip

Supported from version 5.8.1

IInformationNotificationMessageBody Parameter Description

Parameter	Type	Required	Description
message	string	Yes	Prompt bar message content
extra	string	No	Additional information of the prompt bar

Code Example

new RongIMLib.InformationNotificationMessage({
  message: 'Prompt bar message content',
  extra: 'Additional information of the prompt bar',
})

Command Message

tip

Supported from version 5.8.1

ICommandMessageBody Parameter Description

Parameter	Type	Required	Description
name	string	Yes	Command name
data	string	Yes	Command content

Code Example

new RongIMLib.CommandMessage({
  name: 'Command name',
  data: 'Command content',
})

Group Notification Message

tip

Supported from v5.8.1

IGroupNotificationMessageBody Parameters

Parameter	Type	Required	Description
operatorUserId	string	Yes	Operator ID
operation	string	Yes	Operation name
data	string	Yes	Operation data
message	string	Yes	Message content
extra	string	No	Extension info

Example:

new RongIMLib.GroupNotificationMessage({
  operatorUserId: 'Operator ID',
  operation: 'Operation name',
  data: 'Operation data',
  message: 'Message content'
})

Emoji Message

For Web, send Emoji messages as text messages (TextMessage).

RC provides an Emoji plugin with 128 built-in Emoji images. Can be used in message input or extended.
Must send native Emoji characters when sending messages. Use symbolToEmoji for conversion.
Web SDK receives Emoji as Unicode. Convert to display correctly.

Example:

const conversation = { conversationType: RongIMLib.ConversationType.PRIVATE, targetId: '<Target Id>' }
const message = new RongIMLib.TextMessage({ content: '😀' })
RongIMLib.sendMessage(conversation, message).then(res => {})

Emoji Plugin

Compatibility

Chrome Firefox Safari IE Edge iPhone Android
30+ 30+ 10+ 7+ ✔️ iOS 8.0+ Safari & WeChat Browser Android 4.4+ Chrome & WeChat Browser

Chrome	Firefox	Safari	IE	Edge	iPhone	Android
30+	30+	10+	7+	✔️	iOS 8.0+ Safari & WeChat Browser	Android 4.4+ Chrome & WeChat Browser

Include Plugin

<!-- Uncompressed -->
<script src=\"https://cdn.ronghub.com/RongEmoji-2.2.11.js\"></script>
<!-- Compressed -->
<script src=\"https://cdn.ronghub.com/RongEmoji-2.2.11.min.js\"></script>

tip

Emoji demo: https://rongcloud.github.io/web-emoji-demo/src/index.html

danger

When using import * as RongIMLib from '@rongcloud/imlib-next', prefix Emoji plugin calls with window. E.g., window.RongIMLib.RongIMEmoji.init()
RongEmoji plugin only supports CDN inclusion, not npm

Initialize Emoji (default)
```
RongIMLib.RongIMEmoji.init();
```

Initialize Emoji (custom config)

config parameters:

Parameter	Type	Required	Description	Min Version
size	Number	No	Emoji size (default 24, 18-58 recommended)	2.2.6
url	String	No	Emoji background image URL	2.2.6
lang	String	No	Emoji name language (default zh)	2.2.6
extension	Object	No	Extended Emoji	2.2.6

var config = {
  size: 25,
  url: '//f2e.cn.ronghub.com/sdk/emoji-48.png',
  lang: 'en',
  extension: {
    dataSource: {
      u1F914: { // Custom u1F914 Emoji
        en: 'thinking face',
        zh: '思考',
        tag: '🤔',
        position: '0 0'
      }
    },
    url: '//cdn.ronghub.com/thinking-face.png'
  }
};
RongIMLib.RongIMEmoji.init(config);

Get List

var list = RongIMLib.RongIMEmoji.list;
/*list => [{
  unicode: 'u1F600',
  emoji: '😀',
  node: span,
  symbol: '[笑嘻嘻]'
}]
*/

Emoji to Text

Display Emoji names when native Emoji isn't supported.

var message = '😀😁Test Emoji';
RongIMLib.RongIMEmoji.emojiToSymbol(message);
// => '[笑嘻嘻][露齿而笑]Test Emoji'

Text to Emoji

Must use native Emoji characters when sending.

var message = '[笑嘻嘻][露齿而笑]Test Emoji';
RongIMLib.RongIMEmoji.symbolToEmoji(message);
// => '😀😁Test Emoji'

Emoji to HTML

Convert received Emoji (Unicode) to HTML for display.

var message = '\\uf600Test Emoji';
RongIMLib.RongIMEmoji.emojiToHTML(message);
// => \"<span class='rong-emoji-content' name='[笑嘻嘻]'>😀</span>Test Emoji\"

Text to HTML

var message = '[露齿而笑]Test Emoji';
RongIMLib.RongIMEmoji.symbolToHTML(message);
// => \"<span class='rong-emoji-content' name='[露齿而笑]'>😁</span>Test Emoji\"

Extension Attributes

All messages support user and extra extension attributes for custom data.

user: Carries user data (id, name, portraitUri, extra)
extra: String data (custom serialization/deserialization)

Example

new RongIMLib.TextMessage({
  content: '',
  extra: '',
  user: {
    id: '',
    name: '',
    portraitUri: '',
    extra: ''
  }
})

Syntactic Sugar

IMLib provides syntactic sugar methods for sending FileMessage, ImageMessage, HQVoiceMessage, SightMessage, and GIFMessage, simplifying local resource upload and message construction.

Send File Message

Parameters

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation
msgBody	[ISendFileMessageOptions]	Yes	Message content
hooks	[IUploadHooks]	No	Upload callbacks
sendOptions	[IUploadMessageOption]	No	Message config

Example

const conversation = {
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: ''
}
const msgBody = {
  file, // File to upload
  user: { id: '', name: '', portraitUri: '', extra: '' }, // Optional user info
  extra: '' // Optional pass-through data
}
const hooks = {
  onProgress (progress) {},  // Upload progress
  onComplete (fileInfo) { // Upload complete
    console.log(fileInfo.url) // File URL
    // Return custom message if needed
  }
}
const options = {
  contentDisposition: 'attachment' // 'inline' | 'attachment'
},

RongIMLib.sendFileMessage(
  conversation,
  msgBody,
  hooks,
  options
).then(({ code, data: message }) => {
  if (code === 0) {
    // Success
  }
})

Send Image Message

Parameters

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation
msgBody	[ISendImageMessageOptions]	Yes	Message content
hooks	[IUploadHooks]	No	Upload callbacks
sendOptions	[IImageMessageOption]	No	Message config

Example

const conversation = {
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: ''
}
const msgBody = {
  file, // File to upload
  user: { id: '', name: '', portraitUri: '', extra: '' }, // Optional user info
  extra: '' // Optional pass-through data
}
const hooks = {
  onProgress (progress) {},  // Upload progress
  onComplete (fileInfo) { // Upload complete
    console.log(fileInfo.url) // File URL
    // Return custom message if needed
  }
}
const options = {
  contentDisposition: 'inline' // 'inline' | 'attachment'
},

RongIMLib.sendImageMessage(
  conversation,
  msgBody,
  hooks,
  options
).then(({ code, data: message }) => {
  if (code === 0) {
    // Success
  }
})

Send High-Quality Voice Message

tip

Use default aac format if using Global IM UIKit on Android/iOS. Custom format supported if handling audio separately.

Parameters

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation
msgBody	[ISendHQVoiceMessageOptions]	Yes	Message content
hooks	[IUploadHooks]	No	Upload callbacks
sendOptions	[IUploadMessageOption]	No	Message config

Example

const conversation = {
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: ''
}
const msgBody = {
  file, // File to upload
  user: { id: '', name: '', portraitUri: '', extra: '' }, // Optional user info
  extra: '' // Optional pass-through data
}
const hooks = {
  onProgress (progress) {},  // Upload progress
  onComplete (fileInfo) { // Upload complete
    console.log(fileInfo.url) // File URL
    // Return custom message if needed
  }
}
const options = {
  contentDisposition: 'attachment' // 'inline' | 'attachment'
},

RongIMLib.sendHQVoiceMessage(
  conversation,
  msgBody,
  hooks,
  options
).then(({ code, data: message }) => {
  if (code === 0) {
    // Success
  }
})

Send Short Video Message

tip

Must use H.264 + AAC encoded files if using Global IM UIKit on Android/iOS.

Parameters

Parameter	Type	Required	Description
conversation	IConversationOption	Yes	Conversation
msgBody	[ISendSightMessageOptions]	Yes	Message content
hooks	[IUploadHooks]	No	Upload callbacks
sendOptions	[IUploadMessageOption]	No	Message config

Example

const conversation = {
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: ''
}
const msgBody = {
  file, // File to upload
  user: { id: '', name: '', portraitUri: '', extra: '' }, // Optional user info
  extra: '', // Optional pass-through data
  duration: 10, // Duration
  thumbnail: '' // Thumbnail
}
const hooks = {
  onProgress (progress) {},  // Upload progress
  onComplete (fileInfo) { // Upload complete
    console.log(fileInfo.url) // File URL
    // Return custom message if needed
  }
}
const options = {
  contentDisposition: 'attachment' // 'inline' | 'attachment'
},

RongIMLib.sendSightMessage(
  conversation,
  msgBody,
  hooks,
  options
).then(({ code, data: message }) => {
  if (code === 0) {
    // Success
  }
})

Send Typing Status

Use sendTypingStatusMessage to sync typing status to a conversation.

Example

RongIMLib.sendTypingStatusMessage({
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: '<targetId>'
}, RongIMLib.MessageType.TEXT)

Why Resending Failed Messages May Cause Duplicates

Occurs when sender has poor network.

Scenario

A sends message to B. Message reaches server and is delivered to B, but A doesn't receive acknowledgment due to network issues. If A resends, B receives duplicate.

Solution

Server doesn't deduplicate. From SDK v5.5.1, include original messageId when resending. Handle duplicates at application level using senderUserId and messageId.

Legacy Issues

When recalling resent messages, only one may be recalled
When receiving duplicates, unread count still increases

How to Forward/Broadcast Messages

Forward: IMLib SDK doesn't provide forward API. Implement by calling send message API.

Broadcast: Broadcast means sending to multiple users (or Target IDs). Consider these approaches:

Loop through client send message API (max 5 messages/sec)
Use IM Server API from your backend:
- Send Private Message supports sending to multiple users
- Send Group Message, Send Chatroom Message support sending to multiple groups/chatrooms

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Send Message​

sendMessage Interface Description​

Built-in Message Types​

Text Message​

Image Message​

File Message​

HQ Voice​

Short Video Message​

GIF Message​

Reference Message​

Location Message​

Rich Text Message​

Gray Bar Message​

Command Message​

Group Notification Message​

Emoji Message​

Emoji Plugin​

Extension Attributes​

Syntactic Sugar​

Send File Message​

Send Image Message​

Send High-Quality Voice Message​

Send Short Video Message​

Send Typing Status​

Why Resending Failed Messages May Cause Duplicates​

Scenario​

Solution​

Legacy Issues​

How to Forward/Broadcast Messages​

Send Message

sendMessage Interface Description

Built-in Message Types

Text Message

Image Message

File Message

HQ Voice

Short Video Message

GIF Message

Reference Message

Location Message

Rich Text Message

Gray Bar Message

Command Message

Group Notification Message

Emoji Message

Emoji Plugin

Extension Attributes

Syntactic Sugar

Send File Message

Send Image Message

Send High-Quality Voice Message

Send Short Video Message

Send Typing Status

Why Resending Failed Messages May Cause Duplicates

Scenario

Solution

Legacy Issues

How to Forward/Broadcast Messages