tencent cloud

Message Formats
Download PDF
Last updated: 2025-12-02 10:58:35
Message Formats
Last updated: 2025-12-02 10:58:35
Download PDF

MsgBody

Message content is entered in the fields of MsgBody. Tencent Cloud messaged 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 message
TIMLocationElem
Geographic location
TIMFaceElem
Emoji
TIMCustomElem
Custom message. 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 message
TIMImageElem
Image message
TIMFileElem
File message
TIMVideoFileElem
Video message
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, the content of the message is 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 body 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 running in the background, the offline push text is [Position] for the Chinese version and [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 in the background, the offline push text is [Expression] 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

Note:
When a message contains only one TIMCustomElem custom message element, OfflinePushInfo.Desc field requires filling in to receive offline push for the message.
{
    "MsgType": "TIMCustomElem", 
    "MsgContent": {
        "Data": "message"
    }
}
Field
Type
Description
Data
String
Custom message data.

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 business application 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 is not available and defaults to 0.
VideoFormat
String
Video format, for example, MP4.
VideoDownloadFlag
Number
A flag indicating 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 forwarded messages.
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
Array of strings containing digests of the combined message.
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 forwarded message is a C2C or group message.
To_Account
String
UserID of the message recipient. This field is available only when the forwarded message is a C2C message.
GroupId
String
Group ID. This field is available only when the forwarded 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 receiver and can still be pulled after the app 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"
}



Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback