Starter Deal! First 3 month from only  $9.9 /month!
Starter Deal! First 3 month from only  $9.9 /month!
Grab It Now 
Chat
  • Web
    • TUIKit
      • Overview
      • Installaton
        • TUIKit
          • Vue
          • React
        • TUIChat Only
          • Vue
      • Features
        • Reactions
        • Read Receipt
        • Typing Status
        • User Online Status
      • Themes
        • Setting UI Styles
          • Web
          • Mobile
      • Customization
        • Customize Messages
      • Localization
    • SDK
      • Install Chat SDK
      • Initialize Chat SDK
      • Login and Logout
      • Client APIs
      • Message
        • Overview
        • Send a Message
        • Receive a Message
        • Historical Message
        • Forward Messages
        • Modify a Message
        • Delete Messages
        • Clear History Message
        • Recall a Message
        • Send an Online Message
        • Message Read Receipt
        • Query Messages
        • Targeted Group Message
        • Do not Notify
        • Key-Value Extensions
        • Translation
      • Conversation
        • Overview
        • Conversation List
        • Get Conversations
        • Unread Count
        • Pin Conversations
        • Delete Conversations
        • Mark
        • Conversation Group
      • Group
        • Overview
        • Group Management
        • Group Profile
        • Group Member Management
        • Group Member Profile
        • Custom Group Attribute
        • Group Counter
      • Community Topic
        • Community Management
      • User Profile and Relationship Chain
        • User Profile
        • User Status
        • Friend Management
        • Friend List
        • Block List
  • Android
    • Run Demo
    • UIKit
      • Overview
      • Getting Started
      • Installation
        • TUIKit
        • TUIChat Only
      • Features
        • Reactions
        • Read Receipt
        • User Online Status
        • Search Messages
      • Customization
        • Customize Messages
        • Customize Emojis and Stickers
      • Localization
    • SDK
      • Install Chat SDK
      • Initialize Chat SDK
      • Login and Logout
      • Message
        • Overview
        • Send a Message
        • Receive a Message
        • Retrieve Messages
        • Forward Messages
        • Modify a Message
        • Insert a Message
        • Delete Messages
        • Clear History Messages
        • Recall a Message
        • Send an Online Message
        • Message Read Receipt
        • Query Messages
        • Metions
        • Targeted Group Message
        • Do not Notify
        • Key-Value Extensions
        • Reactions
        • Translation
        • Pin Messages
      • Conversation
        • Overview
        • Conversation List
        • Get Conversations
        • Unread Count
        • Pin Conversations
        • Delete Conversations
        • Draft
        • Mark
        • Conversation Group
      • Group
        • Overview
        • Manage Group
        • Profile
        • Manage Members
        • Member Profile
        • Attribute
        • Counter
      • Community and Topic
        • Manage Community
        • Permission Group
      • User
        • User Profile
        • User Status
        • Manage Friends
        • Friend Group
        • Block Lists
      • Local Search
        • Search Messages
        • Search Friends
        • Search Groups
        • Search Group Members
      • Signaling
      • API Reference
        • Java
  • iOS and macOS
    • Run Demo
    • UIKit
      • Overview
      • Getting Started
      • Installation
        • TUIKit
        • TUIChat Only
      • Features
        • Reactions
        • Read Receipt
        • User Online Status
        • Search Messages
      • Customization
        • Customize Messages
        • Customize Emojis and Stickers
      • Localization
    • SDK
      • Installation
        • iOS
        • macOS
      • Initialize Chat SDK
      • Login and Logout
      • Message
        • Overview
        • Send a Message
        • Receive a Message
        • Retrieve Messages
        • Forward Messages
        • Modify a Message
        • Insert a Message
        • Delete Messages
        • Clear History Messages
        • Recall a Message
        • Send an Online Message
        • Message Read Receipt
        • Query Messages
        • Metions
        • Targeted Group Messages
        • Do not Notify
        • Key-Value Extensions
        • Reactions
        • Translation
        • Pin Messages
      • Conversation
        • Overview
        • Conversation List
        • Get Conversations
        • Unread Count
        • Pin Conversations
        • Delete Conversations
        • Draft
        • Mark
        • Conversation Group
      • Group
        • Overview
        • Manage Group
        • Profile
        • Manage Members
        • Member Profile
        • Attribute
        • Counter
      • Community and Topic
        • Manage Community
        • Permission Group
      • User
        • User Profile
        • User Status
        • Manage Friends
        • Friend Group
        • Block Lists
      • Local Search
        • Search Messages
        • Search Friends
        • Search Groups
        • Search Group Members
      • Signaling
      • API Reference
        • Swift
        • Objective-C
  • Windows
    • SDK
      • Install Chat SDK
      • Initialize Chat SDK
      • Login and Logout
      • Message
        • Overview
        • Send a Message
        • Receive a Message
        • Retrieve Messages
        • Forward Messages
        • Modify a Message
        • Insert a Message
        • Delete Messages
        • Clear History Messages
        • Recall a Message
        • Send an Online Message
        • Message Read Receipt
        • Query Messages
        • Metions
        • Targeted Group Messages
        • Do not Notify
        • Key-Value Extensions
        • Reactions
        • Translation
        • Pin Messages
      • Conversation
        • Overview
        • Conversation List
        • Get Conversations
        • Unread Count
        • Pin Conversations
        • Delete Conversations
        • Draft
        • Mark
        • Conversation Group
      • Group
        • Overview
        • Manage Group
        • Profile
        • Manage Members
        • Member Profile
        • Attribute
        • Counter
      • Community and Topic
        • Manage Community
        • Permission Group
      • User
        • User Profile
        • User Status
        • Manage Friends
        • Friend Group
        • Block Lists
      • Local Search
        • Search Messages
        • Search Friends
        • Search Groups
        • Search Group Members
      • Signaling
      • API Reference
        • C++
        • C
  • Flutter
    • Run Demo
    • UIKIT
      • Overview
      • Installation
        • integrated
      • Features
        • Local Search
        • Offline Push
        • Online Status
        • Typing Status
        • Message Read Receipt
        • Message Reactions
        • Internationalization
        • Adding Custom Messages
        • Emoji & Stickers
      • Customization
        • Modifying UI Themes
        • Setting UI Styles
    • SDK
      • Install Chat SDK
        • Install
      • Initialize Chat SDK
        • Initialize
      • Login And Logout
        • Login and Logout
      • Message
        • Message Overview
        • Sending Message
        • Receiving Message
        • Historical Message
        • Forwarding Message
        • Modifying Message
        • Message Inserting
        • Deleting Message
        • Clearing Messages
        • Recalling Message
        • Online Message
        • Read Receipt
        • Querying Message
        • Group @ Message
        • Targeted Group Message
        • Notification Muting
        • Message Extension
      • Conversation
        • Conversation Overview
        • Conversation List
        • Getting Conversation
        • Conversation Unread Count
        • Pinning Conversation to the Top
        • Deleting Conversation
        • Conversation Draft
        • Conversation Group
      • Group
        • Group Overview
        • Group Management
        • Group Profile
        • Group Member Management
        • Group Member Profile
        • Custom Group Attribute
      • User
        • User Profile
        • Friend Management
        • Friend List
        • Blocklist
      • Offline Push
        • Offline Push
      • Signaling
        • Signaling Management
      • Local Search
        • Searching for Message
        • Searching for Friend
        • Searching Group
        • Searching for Group Member
      • API Reference
        • Client APIs
  • React Native
    • Run Demo
    • SDK
      • SDK Integration
      • Initialization
      • Login and Logout
      • Message
        • Message Overview
        • Sending Message
        • Receiving Message
        • Historical Message
        • Forwarding Message
        • Modifying Message
        • Message Inserting
        • Deleting Message
        • Clearing Messages
        • Recalling Message
        • Online Message
        • Read Receipt
        • Querying Message
        • Group @ Message
        • Targeted Group Message
        • Notification Muting
        • Message Extension
      • Group
        • Overview
        • Group Management
        • Group Profile
        • Group Member Management
        • Group Member Profile
        • Custom Group Attribute
        • Community Management
      • User
        • User Profile
        • Friend Management
        • Friend List
        • Blocklist
      • Offline Push
        • Offline Push
      • Local Search
        • Searching for Message
        • Searching for Friend
        • Searching Group
        • Searching for Group Member
      • Signaling
        • Signaling Management
  • Unity(Game Solution)
    • Run Demo
    • SDK
      • SDK Integration
      • Initialization
      • Login and Logout
      • Message
        • Message Overview
        • Sending Message
        • Receiving Message
        • Historical Message
        • Forwarding Message
        • Modifying Message
        • Deleting Message
        • Clearing Messages
        • Recalling Message
        • Online Message
        • Read Receipt
        • Querying Message
        • Group @ Message
        • Targeted Group Message
        • Notification Muting
        • Message Extension
      • Conversation
        • Conversation Overview
        • Conversation List
        • Getting Conversation
        • Conversation Unread Count
        • Pinning Conversation to the Top
        • Deleting Conversation
        • Conversation Draft
        • Conversation Mark
        • Conversation Group
      • Group
        • Group Overview
        • Group Management
        • Group Profile
        • Group Member Management
        • Group Member Profile
        • Custom Group Attribute
        • Group Counter
      • User
        • User Profile
        • User Status
        • Friend Management
        • Friend List
        • Blocklist
  • Unreal Engine(Game Solution)
    • SDK
      • SDK Integration
  • Free Demos
  • Server APIs
    • Generating UserSig
    • RESTful APIs
      • RESTful API Overview
      • RESTful API List
      • Message Related
        • Send Message
          • Sending One-to-One Messages to One User
          • Sending One-to-One Messages to Multiple Users
          • Sending Ordinary Messages in a Group
          • Sending System Messages in a Group
          • Broadcast Message of Audio-Video Group
          • Importing One-to-One Messages
          • Importing Group Messages
        • Historical Message
          • Modifying Historical One-to-one Messages
          • Modifying Historical Group Messages
          • Pulling Historical One-to-one Messages
          • Pulling Historical Group Messages
        • Delete Message
          • Deleting Messages Sent by a Specified User
        • Withdraw Message
          • Recalling One-to-One Messages
          • Recalling Group Messages
        • Read Receipt
          • Marking One-to-One Messages as Read
          • Pulling Group Message Read Receipt Details
          • Pulling Read Receipts for Group Messages
        • Message Extension
          • Pulling the Message Extension of a One-to-One Message
          • Configuring Message Extension for a One-to-One Message
          • Pulling Message Extension of a Group Message
          • Configuring Message Extension for a Group Message
        • Pushing to All Users
          • API for Pushing to All Users
          • Pushing to All Users
          • Setting Application Attribute Names
          • Getting Application Attribute Names
          • Getting User Attributes
          • Setting User Attributes
          • Deleting User Attributes
          • Getting User Tags
          • Adding User Tags
          • Deleting User Tags
          • Deleting All Tags of a User
      • Session Related
        • Conversation List
          • Pulling a conversation list
        • Session Unread Count
          • Setting the Unread Message Count of a Member
          • Querying Unread One-to-One Message Count
        • Delete Session
          • Deleting a conversation
        • Session Grouping Tag
          • Creating Conversation Group Data
          • Updating Conversation Group Data
          • Deleting Conversation Group Data
          • Creating or Updating Conversation Mark Data
          • Searching for Conversation Group Marks
          • Pulling Conversation Group Mark Data
      • Group Related
        • Group Management
          • Getting All Groups in an App
          • Creating a Group
          • Disbanding a Group
          • Getting the Groups a User Has Joined
        • Group Information
          • Getting Group Profiles
          • Modifying the Profile of a Group
          • Importing a Group Profile
        • Group Member Management
          • Adding Group Members
          • Deleting Group Members
          • Banning Group Members
          • Unbanning Group Members
          • Bulk Muting and Unmuting
          • Getting the List of Muted Group Members
          • Changing Group Owner
          • Querying the Roles of Users in a Group
          • Importing Group Members
        • Group Member Information
          • Getting Group Member Profiles
          • Modifying the Profile of a Group Member
        • Group Custom Attributes
          • Getting Group Custom Attributes
          • Modifying Group Custom Attributes
          • Clearing Group Custom Attributes
          • Resetting Group Custom Attributes
          • Deleting Group Custom Attributes
        • Live Group Management
          • Getting the Number of Online Users in an Audio-Video Group
          • Getting the List of Online Members in Audio-Video Group
          • Setting Audio-Video Group Member Marks
          • Getting the List of Banned Group Members.
        • Community Management
          • Creating Topic
          • Deleting Topic
          • Getting Topic Profile
          • Modifying Topic Profile
          • Importing Topic Profiles
        • Group Counter
          • Getting Group Counters
          • Updating Group Counters
          • Deleting Group Counters
      • User Management
        • Account Management
          • Importing a Single Account
          • Importing Multiple Accounts
          • Deleting Accounts
          • Querying Accounts
        • User Information
          • Setting Profiles
          • Pulling Profiles
        • User Status
          • Invalidating Account Login States
          • Querying Account Online Status
        • Friend Management
          • Adding Friends
          • Importing Friends
          • Updating Friends
          • Deleting Friends
          • Deleting All Friends
          • Verifying Friends
          • Pulling Friends
          • Pulling Specified Friends
        • Friend Lists
          • Adding Lists
          • Deleting Lists
          • Pulling Lists
        • Blocklist
          • Blocklisting Users
          • Unblocklisting Users
          • Pulling a Blacklist
          • Verifying Users on a Blocklist
      • Global Mute Management
        • Setting Global Mute
        • Querying Global Mute
      • Operations Management
        • Pulling Operations Data
        • Downloading Recent Messages
        • Getting Server IP Addresses
      • Chatbots
        • Pulling Chatbot Accounts
        • Creating Chatbot Accounts
        • Deleting Chatbot Accounts
    • Webhooks
      • Webhook Overview
      • Webhook Command List
      • Operations Management Callbacks
        • API Overclocking Alarm Callbacks
      • Online Status Webhooks
        • Status Change Webhooks
      • Relationship Chain Webhooks
        • After a Profile Is Updated
        • Before a Friend Is Added
        • Before a Friend Request Is Responded
        • After a Friend Is Added
        • After a Friend Is Deleted
        • After a User Is Added to Blocklist
        • After a User Is Removed from Blocklist
      • One-to-One Message Webhooks
        • Before a One-to-One Message Is Sent
        • After a One-to-One Message Is Sent
        • After a One-to-One message Is Marked as Read
        • After A One-to-One Message Is Recalled
      • Group Webhooks
        • Before a Group Is Created
        • After a Group Is Created
        • Before Applying to Join a Group
        • Before Inviting a User to a Group
        • After a User Joins a Group
        • After a User Leaves a Group
        • Before Group Message Is Sent
        • After a Group Message Is Sent
        • After a Group Is Full
        • After a Group Is Disbanded
        • After Group Profile Is Modified
        • Callback After Recalling Group Messages
        • Webhook for Online and Offline Status of Audio-Video Group Members
        • Webhook for Exceptions When Group Messages Are Sent
        • Before a Topic Is Created
        • After a Topic Is Created
        • After a Topic Is Deleted
        • Topic Profile Change Webhook
        • Callback After Group Member Profile Changed
        • Callback After Group Attribute Changed
        • Callback After Read Receipt
        • Callback After the Group Owner Changed
      • Webhook Mutual Authentication Configuration Guide
        • Apache Mutual Authentication Configuration
        • Nginx Mutual Authentication Configuration
      • Chatbot webhooks
        • Chatbot Passthrough Message Callback
  • Console Guide
    • Creating and Upgrading an Application
    • Basic Configuration
    • Feature Configuration
    • Account Management
    • Group Management
    • Webhook Configuration
  • Product Introduction
    • Message Management
      • One-to-One Message
      • Message Storage
      • Offline Push
      • Group Message
      • Message Formats
    • Account System
      • Login Authentication
      • Online Status Management
    • Group Related
      • Group System
      • Group Management
    • User Profile and Relationship Chain
      • Profile Management
      • Relationship Chain Management
  • Purchase Guide
    • Billing Overview
    • Pricing
  • Error Codes
Chat

Message Formats

MsgBody

Message content is entered in the fields of MsgBody. Tencent Cloud Chat supports multiple message elements in one message, for example, a message can contain both text and emojis. Therefore, MsgBody is defined as an array that can include as many message elements as needed. The name for a message element is TIMMsgElement. For examples of the TIMMsgElements that constitute the MsgBody, see MsgBody Message Content Examples.
The format of TIMMsgElement is defined as follows:
{
"MsgType": "",
"MsgContent": {}
}
Field
Type
Description
MsgType
String
The type of the message element. Currently, these message objects are supported: TIMTextElem (text message), TIMLocationElem (location message), TIMFaceElem (emoji message), TIMCustomElem (custom message), TIMSoundElem (audio message), TIMImageElem (image message), TIMFileElem (file message), and TIMVideoFileElem (video message).
MsgContent
Object
The content of the message element. Each MsgType has its own MsgContent format. For more information, see below.
The following table lists the message types (MsgType) that are currently supported:
Value of MsgType
Type
TIMTextElem
Text
TIMLocationElem
Geographic location
TIMFaceElem
Emoji
TIMCustomElem
Custom. When the receiver is an iOS device and the app is working in the background, this type of message provides fields other than text to APNs. A combined message can contain only one TIMCustomElem custom message element.
TIMSoundElem
Voice
TIMImageElem
Image
TIMFileElem
File
TIMVideoFileElem
Video
Caution
Messages of the above types can be sent by server-side integrated RESTful APIs.

TIMMsgElement

Text message element

{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hello world"
}
}
Field
Type
Description
Text
String
Content of the message. When the receiver is an iOS or Android device and the app is working in the background, messages of this type are displayed as offline push text.
When the receiver is an iOS or Android device and the app is working in the background, the Text field in the JSON request packet is displayed as offline push text.

Location message element

{
"MsgType": "TIMLocationElem",
"MsgContent": {
"Desc": "someinfo",
"Latitude": 29.340656774469956,
"Longitude": 116.77497920478824
}
}
Field
Type
Description
Desc
String
Description of the location
Latitude
Number
Latitude
Longitude
Number
Longitude
When the receiver is an iOS or Android device and the app is working in the background, the offline push text is [Location] for the English version.

Emoji message element

{
"MsgType": "TIMFaceElem",
"MsgContent": {
"Index": 1,
"Data": "content"
}
}
Field
Type
Description
Index
Number
Emoji index customized by users
Data
String
Additional data
When the receiver is an iOS or Android device and the app is working in the background, the offline push text is [Face] for the English version.
description
When a message contains only one TIMCustomElem custom message element, if both the Desc and OfflinePushInfo.Desc fields are not entered, the offline push of the message will not be received, unless the OfflinePushInfo.Desc field is entered.

Custom message element

{
"MsgType": "TIMCustomElem",
"MsgContent": {
"Data": "message",
"Desc": "notification",
"Ext": "url",
"Sound": "dingdong.aiff"
}
}
Field
Type
Description
Data
String
Custom message data. This field is not delivered as a payload field by APNs, and therefore the data field cannot be obtained in payload.
Desc
String
Custom message description. When the receiver is an iOS or Android device, and the app is working in the background, the offline push text is displayed.If a custom message is sent with the OfflinePushInfo.Desc field set, the field will be overwritten; therefore, please enter the OfflinePushInfo.Desc field first.
Note:
When a message contains only one TIMCustomElem custom message element, if both the Desc and OfflinePushInfo.Desc fields are not entered, the offline push of the message will not be received, unless the OfflinePushInfo.Desc field is entered.

Ext
String
Extended field. When the receiver is an iOS or Android device and the app is working in the background, this field is delivered as an Ext key value in APNs request packet payloads. The protocol format of Ext is defined by the business end, the APNs is only responsible for passthrough.
Sound
String
Custom APNs push ringtone
When the receiver is an iOS or Android device and the app is working in the background, the Desc field is delivered as push text, the Ext field is delivered as an Ext key value in APNs request packet payloads, and the Data field is not delivered as a payload field by APNs. Note that a combined message can contain only one TIMCustomElem custom message element.

Voice message element

Caution
To send a voice message through the server-side RESTful API, you need to enter the Url, UUID, and Download_Flag fields. Make sure that the voice can be downloaded via the Url and the UUID is a globally unique string value, usually the MD5 value of the voice file. The message recipient can obtain the specified UUID through V2TIMSoundElem.getUUID() and the app can use the UUID to identify the voice. Download_Flag must be set to 2.
4.X or later versions of Chat SDK (for Android, iOS, macOS, and Windows) send voice message elements in the following format:
{
"MsgType": "TIMSoundElem",
"MsgContent": {
"Url": "https://1234-5678187359-1253735226.cos.ap-shanghai.myqcloud.com/abc123/c9be9d32c05bfb77b3edafa4312c6c7d",
"UUID": "1053D4B3D61040894AC3DE44CDF28B3EC7EB7C0F",
"Size": 62351,
"Second": 1,
"Download_Flag": 2
}
}
Field
Type
Description
Url
String
Voice download URL, through which the voice content can be downloaded directly.
UUID
String
Unique identifier of the voice, key value used by the client to index the voice
Size
Number
Voice data size, in bytes.
Second
Number
Voice duration, in seconds.
Download_Flag
Number
Flag of the voice download method. Currently, the value of Download_Flag must be 2, which means that the voice content can be downloaded from the URL specified by the Url field.
Note
2.X and 3.X versions of Chat SDK (for Android, iOS, macOS, and Windows) send voice message elements in the following format:
{
"MsgType": "TIMSoundElem",
"MsgContent": {
"UUID": "305c0201", //Unique identifier of the voice in String type. This is the key value the client uses to index the voice. The voice cannot be downloaded through this field. To obtain the voice, upgrade the Chat SDK to version 4.X.
"Size": 62351, //Voice data size in bytes, in Number type.
"Second": 1 //Voice duration in seconds, in Number type.
}
}

Image message element

Caution
To send an image message through the server-side RESTful API, you need to enter the URL, UUID, Width, and Height fields. Make sure that the image can be downloaded via the URL so that you can obtain the basic image information and process the image. Width and Height are the width and height (unit: pixels) of the image. UUID must be set to a globally unique string value, usually the MD5 value of the image. The message recipient can obtain the V2TIMImage object by calling V2TIMImageElem.getImageList() and then get the specified UUID by calling V2TIMImage.getUUID(). The app can use the UUID to identify the image.
{
"MsgType": "TIMImageElem",
"MsgContent": {
"UUID": "1853095_D61040894AC3DE44CDFFFB3EC7EB720F",
"ImageFormat": 1,
"ImageInfoArray": [
{
"Type": 1, //Original image
"Size": 1853095,
"Width": 2448,
"Height": 3264,
"URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/0"
},
{
"Type": 2, //Large image
"Size": 2565240,
"Width": 0,
"Height": 0,
"URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/720"
},
{
"Type": 3, //Thumbnail
"Size": 12535,
"Width": 0,
"Height": 0,
"URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/198"
}
]
}
}
Field
Type
Description
UUID
String
Unique identifier of the image, key value used by the client to index the image
ImageFormat
Number
Image format. JPG = 1, GIF = 2, PNG = 3, BMP = 4, Others = 255.
ImageInfoArray
Array
Download information of the original image, thumbnail, or large image.
Type
Number
Image type. 1: original image, 2: large image, 3: thumbnail.
Size
Number
Size of image data in bytes.
Width
Number
Image width in pixels
Height
Number
Image height in pixels
URL
String
Download URL of the image.

File message element

Caution
To send a file message through the server-side RESTful API, you need to enter the Url, UUID, and Download_Flag fields. Make sure that the file can be downloaded via the Url and the UUID is a globally unique string value, usually the MD5 value of the file. The message recipient can obtain the specified UUID by calling V2TIMFileElem.getUUID() and the app can use the UUID to identify the file. Download_Flag must be set to 2.
4.X or later versions of Chat SDK (for Android, iOS, macOS, and Windows) send file message elements in the following format:
{
"MsgType": "TIMFileElem",
"MsgContent": {
"Url": "https://7492-5678539059-1253735326.cos.ap-shanghai.myqcloud.com/abc123/49be9d32c0fbfba7b31dafa4312c6c7d",
"UUID": "1053D4B3D61040894AC3DE44CDF28B3EC7EB7C0F",
"FileSize": 1773552,
"FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV",
"Download_Flag": 2
}
}
Field
Type

Description
Url
String
Download URL of the file, through which the file can be downloaded directly.
UUID
String
Unique identifier of the file, key value used by the client to index the file
FileSize
Number
Size of file data in bytes.
fileName
String
File name.
Download_Flag
Number
Flag of the file download method. Currently, the value of Download_Flag must be 2, which means that the file can be downloaded from the URL specified by the Url field.
Note
2.X and 3.X versions of Chat SDK (for Android, iOS, macOS, and Windows) send file message elements in the following format:
{
"MsgType": "TIMFileElem",
"MsgContent": {
"UUID": "305c02010", //Unique identifier of the file in String type. This is the key value the client uses to index the file. The file cannot be downloaded through this field. To obtain the file, upgrade the Chat SDK to version 4.X.
"FileSize": 1773552, //The size of file data in bytes, in Number type.
"FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV" //The file name in String type.
}
}

Video message element

Caution
To send a video message through the server-side RESTful API, you need to enter the `VideoUrl`, `VideoUUID`, `ThumbUrl`, `ThumbUUID`, `ThumbWidth`, `ThumbHeight`, `VideoDownloadFlag`, and `ThumbDownloadFlag` fields. Make sure that the video and video thumbnail can be downloaded via the `VideoUrl` and `ThumbUrl` respectively. `VideoUUID` and `ThumbUUID` must be globally unique string values, usually the MD5 values of the video and video thumbnail. The message recipient can obtain the specified `VideoUUID` and `ThumbUUID` by calling `V2TIMVideoElem.getVideoUUID()` and `V2TIMVideoElem.getSnapshotUUID()` respectively. The app can use the `VideoUUID` to identify the video. `VideoDownloadFlag` and `ThumbDownloadFlag` must be set to `2`.
4.X or later versions of Chat SDK (for Android, iOS, macOS, and Windows) send video message elements in the following format:
{ "MsgType": "TIMVideoFileElem", "MsgContent": { "VideoUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/f7c6ad3c50af7d83e23efe0a208b90c9", "VideoUUID": "5da38ba89d6521011e1f6f3fd6692e35", "VideoSize": 1194603, "VideoSecond": 5, "VideoFormat": "mp4", "VideoDownloadFlag":2, "ThumbUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/a6c170c9c599280cb06e0523d7a1f37b", "ThumbUUID": "6edaffedef5150684510cf97957b7bc8", "ThumbSize": 13907, "ThumbWidth": 720, "ThumbHeight": 1280, "ThumbFormat": "JPG", "ThumbDownloadFlag":2 } }
Field
Type
Description
VideoUrl
String
Download URL of the video, through which the video can be downloaded directly.
VideoUUID
String
Unique identifier of the video, key value used by the client to index the video.
VideoSize
Number
Size of video data, in bytes.
VideoSecond
Number
Video duration, in seconds. For web clients, this field cannot be obtained and the value `0` is used.
VideoFormat
String
Video format, for example, MP4.
VideoDownloadFlag
Number
Flag of the video download method. Currently, the value of `VideoDownloadFlag` must be 2, which means that the video can be downloaded from the URL specified by the `VideoUrl` field.
ThumbUrl
String
Download URL of the video thumbnail, through which the video thumbnail can be downloaded directly.
ThumbUUID
String
Unique identifier of the video thumbnail, key value used by the client to index the video thumbnail
ThumbSize
Number
Size of thumbnail data, in bytes.
ThumbWidth
Number
Thumbnail width in pixels
ThumbHeight
Number
Thumbnail height in pixels
ThumbFormat
String
Video thumbnail format, such as JPG or BMP.
ThumbDownloadFlag
Number
Flag of the video thumbnail download method. Currently, the value of `ThumbDownloadFlag` must be 2, which means that the video thumbnail can be downloaded from the URL specified by the `ThumbUrl` field.
Note:
2.X and 3.X versions of Chat SDK (for Android, iOS, macOS, and Windows) send video message elements in the following format:
{
"MsgType": "TIMVideoFileElem",
"MsgContent": {
"VideoUUID": "1400123456_dramon_34ca36be7dd214dc50a49238ef80a6b5",//Unique identifier of the video in String type. This is the key value the client uses to index the video. The video cannot be downloaded through this field. To obtain the video, upgrade the Chat SDK to version 4.X.
"VideoSize": 1194603, //Size of video data in bytes, in Number type.
"VideoSecond": 5, //Video duration in seconds, in Number type.
"VideoFormat": "mp4", //Video format in String type, for example, MP4.
"ThumbUUID": "1400123456_dramon_893f5a7a4872676ae142c08acd49c18a",//Unique identifier of the video thumbnail in String type. This is the key value the client uses to index the video thumbnail. The video thumbnail cannot be downloaded through this field. To obtain the video thumbnail, upgrade the Chat SDK to version 4.X.
"ThumbSize": 13907, //Size of thumbnail data in bytes, in Number type.
"ThumbWidth": 720, //Thumbnail width in Number type.
"ThumbHeight": 1280, //Thumbnail height in Number type.
"ThumbFormat": "JPG" //Video thumbnail format in String type, such as JPG or BMP.
}
}

Elements of a combined message

Caution
Only native SDK 5.2.210 or later and web SDK 2.10.1 or later support the sending and receiving of combined messages.
{
"MsgType": "TIMRelayElem",
"MsgContent": {
"Title": "Group chat history",
"MsgNum": 2,
"CompatibleText": "The SDK version does not support combined messages. Please upgrade to the latest version.",
"AbstractList": [
"A: What do you think of this?",
"B: I think it's great."
],
"MsgList": [
{
"From_Account": "A",
"GroupId": "group1",
"MsgSeq": 85,
"MsgRandom": 3998651049,
"MsgTimeStamp": 1664437702,
"MsgBody": [
{
"MsgContent": {
"Text": " What do you think of this?"
},
"MsgType": "TIMTextElem"
}
]
},
{
"From_Account": "B",
"GroupId": "group1",
"MsgSeq": 86,
"MsgRandom": 965790,
"MsgTimeStamp": 1664437703,
"MsgBody": [
{
"MsgContent": {
"Text": "I think it's great."
},
"MsgType": "TIMTextElem"
}
]
}
]
}
}
Field
Type
Description
Title
String
Title of the combined message.
MsgNum
Integer
Number of messages combined/forwarded.
CompatibleText
String
Compatible text. When an SDK of an earlier version that does not support combined messages receives a combined message, the Chat backend converts the message into compatible text and delivers it.
AbstractList
Array
Digest list of a combined message, in string array format.
MsgList
Array
Message list. This field is available only when the total length of the combined messages is less than or equal to 12 KB, in which case the JsonMsgKey field is unavailable.
JsonMsgKey
String
Key of the combined message list. This field is available only when the total length of the combined messages is greater than 12 KB, in which case the MsgList field is unavailable.
The structure of each message in MsgList is as follows:
Field
Type
Description
From_Account
String
UserID of the message sender. This field is available when the combined message is a one-to-one or group message.
To_Account
String
UserID of the message recipient. This field is available only when the combined message is a one-to-one message.
GroupId
String
Group ID. This field is available only when the combined message is a group message.
MsgSeq
Integer
Sequence number of the message (a 32-bit unsigned integer).
MsgRandom
Integer
Random number of the message (a 32-bit unsigned integer).
MsgTimeStamp
Integer
Message timestamp, in seconds.
MsgBody
Array
Message body. For details on formats, see Message Formats. (Note: a message can contain multiple message elements, in which case MsgBody is an array.)
CloudCustomData
String
Custom message data. It is saved in the cloud and will be sent to the peer end. Such data can be pulled after the app is uninstalled and reinstalled.

MsgBody Examples

Single text element message

A single message contains only one text message element. The text content is hello world.
{
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hello world"
}
}
]
}

Combined messages

The following single message contains two text message elements and one emoji message element, in the sequence of text + emoji + text.
{
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hello"
}
},
{
"MsgType": "TIMFaceElem",
"MsgContent": {
"Index": 1,
"Data": "content"
}
},
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "world"
}
}
]
}
Caution
A combined message can contain only one TIMCustomElem custom message element, and an unlimited number of other message elements.

Description of Custom Message Data CloudCustomData

Each message can carry custom data CloudCustomData.
CloudCustomData is saved in the cloud together with the MsgBody of the message. It will be sent to the opposite end and can still be pulled after the program is uninstalled and reinstalled.
The following example shows the formats of CloudCustomData and MsgBody:
{
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hello"
}
}
],
"CloudCustomData": "your cloud custom data"
}

Message Formats for Apple Push Notification Service (APNs)

Push notification display format on the client

Account without a nickname For an account without a nickname, APNs displays only text content: push text for one-to-one chat messages, and (group name): push text for group messages.


Account with a nickname For an account with a nickname, APNs displays nickname: push text for one-to-one chat messages, and nickname (group name): push text for group messages.



Display format of combined messages For combined messages, the text displayed shows the push text of each message element in sequence. The following example shows a one-to-one chat message with an account nickname set, and the push text is helloworld. Note that the text contains no spaces. The backend connects message elements in sequence without adding any extra characters. If spaces or other characters need to be added between different message elements, the caller should take control.
{
"MsgBody": [
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "hello"
}
},
{
"MsgType": "TIMCustomElem",
"MsgContent": {
"Data": "message",
"Desc": "world",
"Ext": "https://www.example.com",
"Sound": "dingdong.aiff"
}
}
]
}
The following table summarizes the push text of different message elements.
Value of MsgType
Type
Push Text of the Message Element
TIMTextElem
Text
Text field.
TIMLocationElem
Location
Offline push text is [Location] for the English version.
TIMFaceElem
Emoji
Offline push text is [Face] for the English version.
TIMCustomElem
Custom
Desc field.

RESTful APIs for nickname and group name settings

RESTful API for setting the account nickname: Setting the Profile. RESTful API for setting the group name: Modifying Basic Group Information.

Advanced apps

Customizing push sounds and extended fields delivered by APNs

Use TIMCustomElem to customize message elements. In the Sound field, enter the file name of the custom audio. In the Ext field, enter the delivered extended field, which can be obtained from the Ext field in the APNs payload.
{
"To_Account": "lumotuwe5",
"MsgRandom": 121212,
"MsgBody": [
{
"MsgType": "TIMCustomElem",
"MsgContent": {
"Data": "other information",
"Desc": "hello",
"Ext": "www.qq.com",
"Sound": "dingdong.aiff"
}
},
{
"MsgType": "TIMTextElem",
"MsgContent": {
"Text": "world"
}
}
]
}

The received APNs JSON payload is displayed as follows on the client:
{
"aps": {
"alert": "Nickname:helloworld", //Push text of each message element is connected in sequence
"badge": 5,
"sound": "dingdong.aiff" //Corresponds to the `Sound` field in `TIMCustomElem`
},
"ext": "www.qq.com" //Corresponds to the `Ext` field in `TIMCustomElem`
}


OfflinePushInfo

OfflinePushInfo is a JSON object dedicated for configuring offline push. It allows you to configure whether to disable push, push text description content, and push passthrough strings for a message. With OfflinePushInfo, you can easily set offline push information, eliminating the need to encapsulate through TIMCustomElem.
Caution
If OfflinePushInfo has been filled in, the offline push settings in TIMCustomElem are ignored. Currently, OfflinePushInfo can work with APNs and the push services of various Android device brands, including Mi, Huawei, Meizu, OPPO, and vivo.
The following example shows the format of OfflinePushInfo:
{
// ...
"MsgBody": [...] //Same with `MsgBody` in this case
"OfflinePushInfo": {
"PushFlag": 0,
"Title":"This is the push title",
"Desc": "This is the offline push content",
"Ext": "Passthrough content",
"AndroidInfo": {
"Sound": "android.mp3",
"OPPOChannelID": "test_OPPO_channel_id",
"VIVOClassification": 1
},
"ApnsInfo": {
"Sound": "apns.mp3",
"BadgeMode": 1,
"Title":"apns title",
"SubTitle":"apns subtitle",
"Image":"www.image.com",
"MutableContent": 1
}
}
}
The preceding fields are described as follows:
Field
Type
Required
Description
PushFlag
Integer
Optional
0: enable push, 1: disable offline push.
Title
String
Optional
Offline push title. This field is applicable to both iOS and Android.
Desc
String
Optional
The offline push content. This field overwrites the offline push display text of the TIMMsgElement elements mentioned above.If the message sent has only one TIMCustomElem element, this Desc field will overwrite the Desc field in the TIMCustomElem. If neither of the Desc fields is filled in, the offline push notification for the message will not be received.
Ext
String
Optional
Passthrough content of offline push. To make sure the offline push of all Android vendors are attainable, this field must be in JSON format.
AndroidInfo.Sound
String
Optional
Path to the offline push sound file in Android.
AndroidInfo.HuaWeiChannelID
String
Optional
Notification channel field for Huawei phones with EMUI 10.0 or later. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
AndroidInfo.XiaoMiChannelID
String
Optional
Notification type (Channel) adaptation field for Mi phones with MIUI 10 or later. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
AndroidInfo.OPPOChannelID
String
Optional
NotificationChannel notification adaptation field for OPPO phones with Android 8.0 or later. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
AndroidInfo.GoogleChannelID
String
Optional
Notification channel field for Google mobile phones with Android 8.0 or later. This field is supported by the new Google push API (certificate file upload API) but not the old API (server key entering API).
AndroidInfo.VIVOClassification
Integer
Optional
Push message classification for vivo phones. Valid values: 0: operation message; 1: system message (default value).
AndroidInfo.HuaWeiImportance
String
Optional
Push notification message classification for Huawei phones. Valid values: LOW, NORMAL (default value).
AndroidInfo.ExtAsHuaweiIntentParam
Integer
Optional
After Huawei Push is configured to Open specified in-app page in the console, "1" indicates to use the passthrough content Ext as the Intent parameter, while "0" (default value) indicates to use the passthrough content Ext as the Action parameter. For the differences between the two parameters, see Guides.
AndroidInfo.HuaWeiCategory
String
Optional
Message type identifier for Huawei phones. When this field is not empty, it will overwrite the category value configured in the console; otherwise, it will not. For more information, see the category description here.
ApnsInfo.BadgeMode
Integer
Optional
The default value or 0 indicates that counting is required. 1 indicates that counting is not required for this message, in which case the number in the upper-right icon does not increase.
ApnsInfo.Title
String
Optional
Title of an APNs push message. The top-level title is replaced when this field is filled in.
ApnsInfo.SubTitle
String
Optional
Subtitle of an APNs push message.
ApnsInfo.Image
String
Optional
Image URL carried by APNs. When the client obtains this field, it displays the image in a pop-up window by downloading the image through the URL.
ApnsInfo.MutableContent
Integer
Optional
Valid values: 1: enable the push extension of iOS 10 or later; 0 (default value).
Caution
The maximum data packet size supported by APNs is 4 KB. Therefore, we recommend that the total size of the Desc and Ext fields does not exceed 3 KB.

References