Skip to main content

User Content Message Formats

The Instant Messaging Service categorizes messages sent by users as User Content Messages. It provides predefined structures for text, images, GIFs, voice, files, short videos, locations, references, and combined forwarding.

Text Message​

The Instant Messaging Service defines a text message with the ObjectName RC:TxtMsg.

  • Built into the Client SDK, you can send it directly by calling relevant methods.
  • When using the Server API, ensure the correct ObjectName and message content structure are passed:
    • Use RC:TxtMsg in the ObjectName field.
    • Pass the message content structure in the content field.

Text Message Content Structure​

The JSON object structure for a text message is as follows (serialize it into a JSON String for the content field):

{
  \"content\":\"@张三 Hello world!\",
  \"mentionedInfo\":{
    \"type\":2,
    \"userIdList\":[\"zhangsan\"],
    \"mentionedContent\":\"有人@你\"
  },
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}
NameTypeRequiredDescription
contentStringYesThe text content, including emojis.
mentionedInfoObjectNoRequired for group @ messages. Not needed in one-on-one chats. When using the IM Server API, set isMentioned to 1 for @ messages. Otherwise, mentionedInfo is ignored.
mentionedInfo.typeintYes@ type: 1 for @ all, 2 for specific users.
mentionedInfo.userIdListString[]NoList of specific users, valid when type is 2.
mentionedInfo.mentionedContentStringNoCustom Push content for @ messages. Overrides default or custom pushContent.
userStringNoSender's user info. Not recommended unless in live streaming scenarios.
user.idStringNoSender's user ID.
user.nameStringNoSender's nickname.
user.portraitStringNoSender's avatar.
user.extraStringNoExtended info.
extraStringNoExtended info. Can be removed.

Client Default Properties​

  • Stored locally
  • Counted in unread messages
  • Supports offline push
    • Push title: Defaults to sender's nickname for one-on-one and system messages, group name for group messages. Customizable when sending.
    • Push content: Defaults to message content. For group messages, sender's nickname is prefixed. Customizable when sending.

Image Message​

The Instant Messaging Service defines an image message with the ObjectName is RC:ImgMsg.

  • Built into the Client SDK, you can send it directly by calling relevant methods.
  • When using the Server API, ensure the correct ObjectName and message content structure are passed:
    • Use RC:ImgMsg in the ObjectName field.
    • Pass the message content structure in the content field.

Image Message Content Structure​

The JSON object structure for an image message is as follows (serialize it into a JSON String for the content field):

{
  \"content\":\"/9j/4AAQSkZJRgABAgAAZABkAAD\",
  \"localPath\":\"\",
  \"imageUri\":\"http://p1.cdn.com/fds78ruhi.jpg\",
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}

The image resource includes:

  • Thumbnail: content key represents the Base64 encoded thumbnail. When sending from the server, generate the thumbnail (max 240px), Base64 encode it, and place it in content. Remove any Data URI prefix.
  • Large Image: imageUri key represents the remote address. When sending from the server, provide the remote address. When sending from the client, the SDK uploads it to the file server (default: Qiniu Cloud Storage).
NameTypeRequiredDescription
contentStringYesBase64 encoded thumbnail. Max length: 10k. Remove `\r\
, \r, and \
` after encoding.
nameStringNoFile name. Defaults to a generated name if not provided.
localPathStringYesLocal image path. Client-only.
imageUriStringYesRemote image address. Upload to your app's file server when sending via IM Server API.
userStringNoSender's user info. Not recommended unless in live streaming scenarios.
user.idStringNoSender's user ID.
user.nameStringNoSender's nickname.
user.portraitStringNoSender's avatar.
user.extraStringNoExtended info.
extraStringNoExtended info. Can be removed.

Client Default Properties​

  • Stored locally
  • Counted in unread messages
  • Supports offline push
    • Push title: Defaults to sender's nickname for one-on-one and system messages, group name for group messages. Customizable when sending.
    • Push content: Defaults to "[Image]". For group messages, sender's nickname is prefixed. Customizable when sending.

GIF Image Message​

The instant messaging service defines a GIF image message with the message type identifier (ObjectName) as RC:GIFMsg.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:GIFMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

GIF Message Content Structure​

The message content JSON object structure for a GIF image message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
    \"gifDataSize\":34563,
    \"height\":246,
    \"localPath\":\"/var/mobile/.../GIF_53\",
    \"remoteUrl\":\"https://rongcloud-image.cn.ronghub.com/image_jpe64562665566.gif\",
    \"width\":263,
    \"user\":
    {
      \"id\":\"4242\",
      \"name\":\"Robin\",
      \"portrait\":\"http://example.com/p1.png\",
      \"extra\":\"extra\"
    },
    \"extra\":\"\"
}

The parameters of the GIF image message content structure are as follows:

NameTypeRequiredDescription
gifDataSizeIntYesThe size of the GIF image file in bytes.
nameStringNoThe file name. If not passed, the downloadMediaMessage method in the client SDK will generate a default name after downloading.
localPathStringYesThe local address of the GIF image. Only used by the client, not passed by the server.
remoteUrlStringYesThe server address of the GIF image. When sending a GIF image message via the IM Server API, you need to upload the file to your app's file server and generate the GIF image address before sending.
widthIntYesThe width of the GIF image.
heightIntYesThe height of the GIF image.
userObjectYesThe user information carried in the message. The IMKit SDK conversation interface prioritizes displaying the user information carried in the message. This attribute can be removed.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoAdditional information that can contain arbitrary data.
extraStringNoAdditional information that can contain arbitrary data. This attribute can also be removed.

Client Default Properties​

  • Stored Locally on the Client
  • Counted in Unread Message Count
  • Supports Offline Message Push by Default
    • Push Notification Title: For one-on-one and system conversation messages, the push title defaults to the sender's nickname. For group and supergroup messages, the push title defaults to the group name. The default data is from the user registration or group creation passed to the instant messaging server. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push Notification Content: The default Chinese push content is the fixed string: [Image]. For group or supergroup messages, the sender's nickname is prefixed, e.g., Sender's nickname: [Image]. You can customize the push content when sending a message.

High-Quality Voice Message​

The instant messaging service defines a high-quality voice message with the message type identifier (ObjectName) as RC:HQVCMsg.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:HQVCMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

High-Quality Voice Message Content Structure​

The message content JSON object structure for a high-quality voice message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
  \"localPath\":\"/9j/4AAQSkZ/2wBaSiimB//9k=\",
  \"remoteUrl\":\"http://p1.cdn.com/fds78ruhi.aac\",
  \"duration\":7,
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}

The parameters of the high-quality voice message content structure are as follows:

NameTypeRequiredDescription
nameStringNoThe file name. If not passed, the downloadMediaMessage method in the client SDK will generate a default name after downloading.
localPathStringYesThe local path of the media content encoded in AAC format. Only used by the client, not passed by the server.
remoteUrlStringYesThe network address of the media content uploaded to the server. When sending a high-quality voice message via the IM Server API, you need to generate an AAC format file and upload it to your app's file server, then generate the address before sending.
durationIntYesThe duration of the voice message, up to 60 seconds (unit: seconds).
userObjectNoThe user information of the message sender carried in the message. Generally, it is not recommended to carry user information in the message. It is recommended for use in live streaming scenarios.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoAdditional information that can contain arbitrary data.
extraStringNoAdditional information that can contain arbitrary data. This attribute can also be removed.

Client Default Properties​

  • Stored Locally on the Client
  • Counted in Unread Message Count
  • Supports Offline Message Push by Default
    • Push Notification Title: For one-on-one and system conversation messages, the push title defaults to the sender's nickname. For group and supergroup messages, the push title defaults to the group name. The default data is from the user registration or group creation passed to the instant messaging server. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push Notification Content: The default Chinese push content is the fixed string: [Voice]. For group or supergroup messages, the sender's nickname is prefixed, e.g., Sender's nickname: [Voice]. You can customize the push content when sending a message.
tip

About the old version voice message RC:VcMsg:

  • The message with ObjectName RC:VcMsg is the old version voice message. The old version voice message directly sends the BASE64 encoded voice data.
  • It is recommended to use the high-quality voice message RC:HQVCMsg. The high-quality voice message can store the recorded audio data on the server, and only the URL is saved in the message body. It is not limited by the 128K size limit of the message body, so it has higher sound quality. The maximum duration of the voice message is 60 seconds.

File Message​

The instant messaging service defines a file message with the message type identifier (ObjectName) as RC:FileMsg.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:FileMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

File Message Content Structure​

The message content JSON object structure for a file message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
  \"name\":\"file.txt\",
  \"size\":190184,
  \"type\":\"txt\",
  \"localPath\":\"\",
  \"fileUrl\":\"http://www.demo.com/am.ind\",
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}

The parameters of the file message content structure are as follows:

NameTypeRequiredDescription
nameStringNoThe file name. If not passed, the downloadMediaMessage method in the client SDK will generate a default name after downloading.
sizeStringYesThe file size in bytes.
typeStringYesThe file type.
localPathStringYesThe local address of the file. Only used by the client, not passed by the server.
fileUrlStringYesThe server address of the file. When sending a file message via the IM Server API, you need to upload the file to your app's file server and generate the file address before sending.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoAdditional information that can contain arbitrary data.
extraStringNoAdditional information that can contain arbitrary data. This attribute can also be removed.

Client Default Properties​

  • Stored Locally on the Client
  • Counted in Unread Message Count
  • Supports Offline Message Push by Default
    • Push Notification Title: For one-on-one and system conversation messages, the push title defaults to the sender's nickname. For group and supergroup messages, the push title defaults to the group name. The default data is from the user registration or group creation passed to the instant messaging server. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push Notification Content: The default Chinese push content is: [File] + file name, e.g., “[File] 123.txt”. For group or supergroup messages, the sender's nickname is prefixed, e.g., Sender's nickname: [File] + file name. You can customize the push content when sending a message.

Short Video Message​

The instant messaging service defines a short video message with the message type identifier (ObjectName) as RC:SightMsg.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:SightMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

Short Video Message Content Structure​

The message content JSON object structure for a short video message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
  \"sightUrl\":\"http://rongcloud...com/video...\",
  \"content\":\"/9j/4AAQSkZ/2wB...hDSaSiimB//9k=\",
  \"duration\":2,
  \"size\":734320,
  \"name\":\"video_xx.mp4\",
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"extra\"
}

The content key in the message content JSON object of the short video message represents the Base64 encoded value of the thumbnail.

  • When sending a short video message from the server, you need to generate the thumbnail yourself (recommended longest side not exceeding 240 pixels), perform Base64 encoding, and place it in content. Note, some tools may include a Data URI prefix in the Base64 output. For example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD. Discard the Data URI prefix and retain only the data part, e.g., /9j/4AAQSkZJRgABAgAAZABkAAD.
  • When sending a short video message from the client, the SDK automatically generates a thumbnail with the longer side not exceeding 240 pixels. The recipient's conversation page only displays the thumbnail (longest side 240 pixels).

The parameters of the short video message content structure are as follows:

NameTypeRequiredDescription
sightUrlStringYesThe URL of the short video uploaded to the file server. When sending a video message via the Server API, you need to upload the video file to your application's file server and generate the file URL before sending.
contentStringYesThe Base64 encoded result of the first frame image thumbnail of the short video. The Base64 string length is recommended to be 5k, with a maximum of 10k. Note: After Base64 encoding, replace all `\r\
, \r, and \
` with empty strings.
durationIntYesVideo duration in seconds. If selecting a local video file, note that the server's default maximum video duration is 2 minutes. Contact business for adjustments.
sizeStringYesVideo size in bytes.
nameStringYesThe file name of the video on the sending end. The short video file format is MP4. The IMKit SDK currently supports playing video files in mp4 format (H.264+AAC). The IMLib SDK requires developers to implement playback functionality.
userObjectNoThe user information of the message sender carried in the message. Generally, it is not recommended to carry user information in the message. It is recommended for use in live streaming scenarios.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoAdditional information that can contain arbitrary data.
extraStringNoAdditional information that can contain arbitrary data. This attribute can also be removed.

Client Default Properties​

  • Stored Locally on the Client
  • Counted in Unread Message Count
  • Supports Offline Message Push by Default
    • Push Notification Title: For one-on-one and system conversation messages, the push title defaults to the sender's nickname. For group and supergroup messages, the push title defaults to the group name. The default data is from the user registration or group creation passed to the instant messaging server. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push Notification Content: The default Chinese push content is the fixed string: [Short Video]. For group or supergroup messages, the sender's nickname is prefixed, e.g., Sender's nickname: [Short Video]. You can customize the push content when sending a message.

Location Message​

The instant messaging service defines a location message with the message type identifier (ObjectName) as RC:LBSMsg.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:LBSMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

Location Message Content Structure​

The message content JSON object structure for a location message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
  \"content\":\"bhZPzJXimRwrtvc=\",
  \"latitude\":39.9139,
  \"longitude\":116.3917,
  \"poi\":\"Beijing Yunzhong Rongxin Network Technology Co., Ltd.\",
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"portrait\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}

The parameters of the location message content structure are as follows:

NameTypeRequiredDescription
contentStringYesRepresents the location image thumbnail in JPG format. After Base64 encoding, replace all `\r\
, \r, and \
` with empty strings.
latitudeNumberYesThe latitude value of the location.
longitudeNumberYesThe longitude value of the location.
poiStringYesThe poi information of the location.
userObjectNoThe user information of the message sender carried in the message. Generally, it is not recommended to carry user information in the message. It is recommended for use in live streaming scenarios.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoAdditional information that can contain arbitrary data.
extraStringNoAdditional information that can contain arbitrary data. This attribute can also be removed.

Client Default Properties​

PropertyDescription
Stored LocallyAfter sending or receiving the message, it is stored in the local database. Web and mini-program clients do not support local message storage due to unreliable local storage.
Counted in Message CountThe unread message count of the conversation +1. This property only affects the unread count in the conversation list. The app badge can be obtained by accumulating the unread counts of each conversation list.
Supports Push NotificationSupports push to clients (except Web, mini-program, and PC). When there are offline cached messages, a remote push notification is sent.
Push Notification TitleDefaults to the sender's nickname (group nickname). You can specify a custom push title when sending a message.
Push Notification ContentThe default Chinese push content is “[Location]“. You can customize the push content when sending a message.

Reference Message​

The instant messaging service defines a reference message with the message type identifier (ObjectName) as RC:ReferenceMsg.

tip

Generally used in one-on-one and group chat scenarios. A reference message can be sent when replying to a specific message content. Currently, supported referenced messages include: text messages, file messages, image-text messages, and image messages. Referenced messages can be referenced and replied to again.

  • The client SDK has built-in support for this message type, allowing direct method calls to send it.
  • When using the server API to send this message type, ensure the correct message type identifier and message content structure are passed:
    • The message type identifier RC:ReferenceMsg must be passed in the message type field (usually named ObjectName) of the API interface.
    • The message content structure of the current message type must be passed in the message content field (usually named content) of the API interface.

Reference Message Content Structure​

The message content JSON object structure for a reference message is as follows (serialize the message content JSON object below into a JSON String and use it as the value for the content field in the API interface):

{
  \"content\":\"The specific content contained in the reference message's own content structure!\",
  \"referMsgUserId\":\"432432\",
  \"objName\":\"RC:TxtMsg\",
  \"referMsg\":{
    \"content\":\"Hello world!\",
    \"extra\":\"\"
  },
  \"mentionedInfo\":{
    \"type\":2,
    \"userIdList\":[\"123\",\"456\"],
    \"mentionedContent\":\"Someone @you"
  },
  "user":
  {
    "id":"4242",
    "name":"Robin",
    "portrait":"http://example.com/p1.png",
    "extra":"extra"
  },
  "extra":""
}

The parameters for the referenced message content structure are as follows:

NameTypeRequiredDescription
contentStringYesThe text content sent when referencing a message, including emojis.
referMsgUserIdStringYesThe user ID of the sender of the referenced message.
referMsgStringYesThe message structure of the referenced message in JSON format.
objNameStringYesThe message type of the referenced message. Currently supported message types: text RC:TxtMsg, image RC:ImgMsg, file RC:FileMsg.
mentionedInfoObjectNoWhen sending @ messages in a group, the mentioned user information needs to be passed. This property is not required in one-on-one chats. When sending group @ messages using the IM Server API, the isMentioned field must be set to 1 to specify the current message as an @ message. Otherwise, a normal message will be sent by default, and the mentionedInfo data will be invalid.
mentionedInfo.typeintYesThe @ function type, where 1 means @ everyone and 2 means @ specific users.
mentionedInfo.userIdListString[]NoThe list of specified users, valid when type is 2. When type is 1, userIdList can be empty.
mentionedInfo.mentionedContentStringNoThe custom push content for the @ message. The mentionedContent carried by the @ message has the highest priority and will override all default or custom pushContent data.
userObjectNoThe user information of the message sender carried in the message. It is generally not recommended to carry user information in messages. It is recommended to use it only in live streaming scenarios.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoExtended information, which can contain arbitrary data content.
extraStringNoExtended information, which can contain arbitrary data content, or this property can be removed.

Default Client Properties​

  • Stored locally on the client
  • Counted in the unread message count of the conversation
  • Supports offline message push by default
    • Push notification title: The push title for one-on-one and system conversation messages defaults to the sender's nickname. The push title for group and ultra group messages defaults to the group name. The default uses the data passed to the IM server when registering a user or creating a group. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push notification content: The default Chinese push content is the message content. If it is a group or ultra group message, the sender's nickname will be prefixed, for example: Sender's nickname: Message content. You can customize the push content when sending a message.

Combined Forwarded Messages​

The IM service defines a message type identifier (ObjectName) as RC:CombineMsg for combined forwarded messages.

tip

Only the IMKit SDK on the client side supports sending combined forwarded messages. After sending a combined forwarded message from the client, the message is stored on the IM server as an HTML file. The recipient will count it as an unread message and store it.

  • The message type is already built into the client SDK, and you can directly call the relevant methods to send it.
  • If you use the server API to send this type of message, make sure to pass the correct message type identifier and message content structure:
    • You must pass the message type identifier RC:CombineMsg in the message type field (usually named ObjectName) of the API interface.
    • You must pass the message content structure of the current message type in the message content field (usually named content) of the API interface.

Combined Forwarded Message Content Structure​

The message content JSON object structure for combined forwarded messages is as follows (serialize the message content JSON object below into a JSON string and use it as the value of the content field in the API interface):

{
  \"localPath\": \"file:///storage/emulated/0/Android/data/cn.rongcloud.im/cache/combine/157829828.html\",
  \"remoteUrl\": \"https://rongcloud-html-cn.ronghub.com/text_plain__RC-2019-12-17_754_157130.html?e=1592Q=\",
  \"conversationType\": 1,
  \"nameList\": [\"lisx\", \"ddddd\"],
  \"summaryList\": [\"lisx : nzj\", \"ddddd : Remember the promotion match\", \"ddddd : Just sleep\", \"lisx : nznznn\"]
}

The parameters for the combined forwarded message content structure are as follows:

NameTypeRequiredDescription
localPathStringNoThe local HTML file path for the detailed information of the combined forwarded message. Only used by the client, not passed by the server.
remoteUrlStringYesThe remote HTML file path.
conversationTypeIntYesThe conversation type, currently supports one-on-one and group chats. One-on-one is 1, group chat is 3.
nameListStringYesThe user names of the first 4 messages displayed in the conversation interface for the combined forwarded message.
summaryListStringYesThe summary information of the first 4 messages displayed in the conversation interface for the combined forwarded message, corresponding to the nameList property.

Default Client Properties​

  • Stored locally on the client
  • Counted in the unread message count of the conversation
  • Supports offline message push by default
    • Push notification title: The push title for one-on-one and system conversation messages defaults to the sender's nickname. The push title for group and ultra group messages defaults to the group name. The default uses the data passed to the IM server when registering a user or creating a group. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push notification content: The default Chinese push content is the fixed string: [Chat history]. If it is a group or ultra group message, the sender's nickname will be prefixed, for example: Sender's nickname: [Chat history]. You can customize the push content when sending a message.

Image and Text Messages​

The IM service defines a message type identifier (ObjectName) as RC:ImgTextMsg for image and text messages.

  • The message type is already built into the client SDK, and you can directly call the relevant methods to send it.
  • If you use the server API to send this type of message, make sure to pass the correct message type identifier and message content structure:
    • You must pass the message type identifier RC:ImgTextMsg in the message type field (usually named ObjectName) of the API interface.
    • You must pass the message content structure of the current message type in the message content field (usually named content) of the API interface. The message type is already built into the client SDK, and you can directly call the relevant methods to send it.

Image and Text Message Content Structure​

The message content JSON object for image-text messages is as follows (serialize the message content JSON object below into a JSON string and pass it as the content field value in the API):

{
  \"title\":\"Title\",
  \"content\":\"Message description\",
  \"imageUri\":\"http://p1.cdn.com/fds78ruhi.jpg\",
  \"url\":\"http://www.rongcloud.io\",
  \"user\":
  {
    \"id\":\"4242\",
    \"name\":\"Robin\",
    \"icon\":\"http://example.com/p1.png\",
    \"extra\":\"extra\"
  },
  \"extra\":\"\"
}

The image-text message content structure parameters are as follows:

NameTypeRequiredDescription
titleStringYesThe title of the message.
contentStringYesThe text content of the message.
imageUriStringYesThe image address in the message. The image size is 120 x 120 pixels. When sending image messages via the IM Server API, you need to upload the file to your application's file server and generate the image address before sending.
urlStringYesThe URL to jump to after clicking the image message.
userStringNoThe user information of the sender. It is generally not recommended to include user information in messages. It is suggested to use this only in live streaming scenarios.
user.idStringNoThe user ID of the message sender.
user.nameStringNoThe user nickname of the message sender.
user.portraitStringNoThe avatar of the message sender.
user.extraStringNoExtra information, which can contain any data content.
extraStringNoExtra information, which can contain any data content. This attribute can also be removed.

Client Default Properties​

  • Stored locally on the client
  • Counted in the unread message count
  • Supports offline message push by default
    • Push notification title: For one-on-one and system chat messages, the push title defaults to the sender's nickname. For group and ultra group messages, the push title defaults to the group name. The default data is obtained from the instant messaging server when the user registers or the group is created. You can specify the push title when sending a message. The push title specified when sending a message has the highest priority.
    • Push notification content: The default Chinese push content is a fixed string: [Image-Text]. For group or ultra group messages, the sender's nickname is prefixed, e.g., Sender's nickname: [Image-Text]. You can customize the push content when sending a message.

How to Send @ Messages​

@ messages are not predefined message types and do not have a specified ObjectName.

IM services support adding the mentionedInfo object to the message content when sending the following types of messages to groups or ultra groups, to achieve the effect of mentioning others (@).

  • Text messages (ObjectName is RC:TxtMsg)
  • Reference messages (ObjectName is RC:ReferenceMsg)

The message content of an @ message needs to include the mentionedInfo object, with the following structure:

NameTypeRequiredDescription
mentionedInfoObjectNoWhen sending @ messages in a group, the mentioned user information needs to be passed. This attribute is not required in one-on-one chat scenarios. When sending group @ messages using the IM Server API, the isMentioned field must be set to 1 to specify the current message as an @ message. Otherwise, a normal message will be sent by default, and the mentionedInfo data will be invalid.
mentionedInfo.typeintYesThe @ scope. 1 means @ everyone. 2 means @ specific users, and the user list is specified by mentionedInfo.userIdList.
mentionedInfo.userIdListString[]NoThe specified user list, valid when type is 2. When type is 1, userIdList can be empty.
mentionedInfo.mentionedContentStringNoThe custom push content for the @ message. The mentionedContent carried by the @ message has the highest priority and will override all default or custom pushContent data.
tip

If you send an @ message through the IM Server API, you must set isMentioned to 1 to specify the current message as an @ message.

Text Message Content Structure with @ Information​

When sending a text message to a group or ultra group, including the mentionedInfo attribute in the message content allows you to send an @ message. The following example constructs a text message that mentions users with IDs "123" and "456". The mentionedContent carried by the @ message has the highest priority and will override all default or custom pushContent data.

{
  \"content\":\"@张三 @李四 Hello World!\",
  \"mentionedInfo\":{
    \"type\":2,
    \"userIdList\":[\"123\",\"456\"],
    \"mentionedContent\":\"Someone mentioned you\"
  },
  \"extra\":\"\"
}

Note: When sending @ messages from the server, you need to manually fill in the corresponding user nicknames for the IDs in the content field inside the message content JSON object. In this example, the nicknames for user IDs "123" and "456" are "张三" and "李四".

The following is the JSON structure diagram. For specific field descriptions, refer to the text message content structure.

Reference Message Content Structure with @ Information​

When sending a reference message to a group or ultra group, including the mentionedInfo attribute in the message content allows you to send an @ message. The mentionedContent carried by the @ message has the highest priority and will override all default or custom pushContent data.

{
  \"content\":\"@Tom The reference message content structure contains specific content!\",
  \"referMsgUserId\":\"432432\",
  \"objName\":\"RC:TxtMsg\",
  \"referMsg\":{
    \"content\":\"Hello world!\",
    \"extra\":\"\"
  },
  \"mentionedInfo\":{
    \"type\":2,
    \"userIdList\":[\"tom1999\"],
    \"mentionedContent\":\"Someone mentioned you\"
  },
  \"extra\":\"\"
}

Note: When sending @ messages from the server, you need to manually fill in the corresponding user nicknames for the IDs in the content field inside the message content JSON object. In this example, the nickname for user ID "tom1999" is "Tom".

The following is the JSON structure diagram. For specific field descriptions, refer to the text message content structure.

Last updated on