文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>直播与语聊房>服务端 API>REST API>消息管理>消息格式描述

消息格式描述

最近更新时间：2025-12-02 11:50:41

我的收藏

本页目录：

消息内容 MsgBody 说明

MsgBody 中所填写字段是消息内容。即时通信 IM 支持一条消息中包括多种消息元素类别，例如一条消息中既包括文本消息元素，还包括表情消息元素。因此 MsgBody 定义为 Array 格式，可按照需求加入多类消息元素。消息元素名称为 TIMMsgElement，消息元素 TIMMsgElement 组成 MsgBody 的示例请参见 消息内容 MsgBody 实例。
消息元素 TIMMsgElement 的格式统一为：
{
    "MsgType": "",
    "MsgContent": {}
}
字段
类型
说明
MsgType
String
消息元素类别；目前支持的消息对象包括：TIMTextElem(文本消息)，TIMLocationElem(位置消息)，TIMFaceElem(表情消息)，TIMCustomElem(自定义消息)，TIMSoundElem(语音消息)，TIMImageElem(图像消息)，TIMFileElem(文件消息)，TIMVideoFileElem(视频消息)。
MsgContent
Object
消息元素的内容，不同的 MsgType 有不同的 MsgContent 格式，具体参见下文。
目前支持消息类别 MsgType 见下表：
MsgType 值
类型
TIMTextElem
文本消息。
TIMLocationElem
地理位置消息。
TIMFaceElem
表情消息。
TIMCustomElem
自定义消息，当接收方为 iOS 系统且应用处在后台时，此消息类型可携带除文本以外的字段到 APNs。一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。
TIMSoundElem
语音消息。
TIMImageElem
图像消息。
TIMFileElem
文件消息。
TIMVideoFileElem
视频消息。
TIMRelayElem
合并转发消息。
注意：
上述类型的消息均能通过服务端集成的 REST API 接口发送。

消息元素 TIMMsgElement

文本消息元素

{
    "MsgType": "TIMTextElem",
    "MsgContent": {
        "Text": "hello world"
    }
}
字段
类型
说明
Text
String
消息内容。当接收方为 iOS 或 Android 后台在线时，作为离线推送的文本展示。
说明：
当接收方为 iOS 或 Android，且应用处在后台时，JSON 请求包体中的 Text 字段作为离线推送的文本展示。

地理位置消息元素

{
    "MsgType": "TIMLocationElem", 
    "MsgContent": {
        "Desc": "someinfo", 
        "Latitude": 29.340656774469956, 
        "Longitude": 116.77497920478824
    }
}
字段
类型
说明
Desc
String
地理位置描述信息。
Latitude
Number
纬度。
Longitude
Number
经度。
当接收方为 iOS 或 Android，且应用处在后台时，中文版离线推送文本为“[位置]”，英文版离线推送文本为“[Location]”。

表情消息元素

{
    "MsgType": "TIMFaceElem", 
    "MsgContent": {
        "Index": 1, 
        "Data": "content"
    }
}
字段
类型
说明
Index
Number
表情索引，用户自定义。
Data
String
额外数据。
当接收方为 iOS 或 Android，且应用处在后台时，中文版离线推送文本为“[表情]”，英文版离线推送文本为“[Face]”。

自定义消息元素

注意：
当消息中只有一个 TIMCustomElem 自定义消息元素时，需要填写 OfflinePushInfo.Desc 字段才能收到该消息的离线推送。
{
    "MsgType": "TIMCustomElem", 
    "MsgContent": {
        "Data": "message"
    }
}
字段
类型
说明
Data
String
自定义消息数据。

语音消息元素

注意：
通过服务端集成的 REST API 接口发送语音消息时，必须填入语音的 Url、UUID、Download_Flag 字段。需保证通过 Url 能下载到对应语音。UUID 字段需填写全局唯一的 String 值，一般填入语音文件的 MD5 值。消息接收者可以通过 V2TIMSoundElem.getUUID() 拿到设置的 UUID 字段，业务 App 可以用这个字段做语音的区分。Download_Flag 字段必须填2。
4.X 及以上版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的语音消息元素的格式如下：
{
    "MsgType": "TIMSoundElem",
    "MsgContent": {
        "Url": "https://1234-5678187359-1253735226.cos.ap-shanghai.myqcloud.com/abc123/c9be9d32c05bfb77b3edafa4312c6c7d",
        "UUID": "1053D4B3D61040894AC3DE44CDF28B3EC7EB7C0F",
        "Size": 62351,
        "Second": 1,
        "Download_Flag": 2
    }
}
字段
类型
说明
Url
String
语音下载地址，可通过该 URL 地址直接下载相应语音。
UUID
String
语音的唯一标识，客户端用于索引语音的键值。
Size
Number
语音数据大小，单位：字节。
Second
Number
语音时长，单位：秒。
Download_Flag
Number
语音下载方式标记。目前 Download_Flag 取值只能为2，表示可通过Url字段值的 URL 地址直接下载语音。
说明
2.X和3.X版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的语音消息元素如下：
{
    "MsgType": "TIMSoundElem",
    "MsgContent": {
        "UUID": "305c0201", //语音的唯一标识，类型为 String。客户端用于索引语音的键值。无法通过该字段下载相应的语音。若需要获取该语音，请升级 IM SDK 版本至4.X。
        "Size": 62351,      //语音数据大小，类型为 Number，单位：字节。
        "Second": 1         //语音时长，类型为 Number，单位：秒。
    }
}

图像消息元素

注意：
通过服务端集成的 REST API 接口发送图像消息时，必须填入图像的以下字段：URL、UUID、Width、Height。需保证通过 URL 能下载到对应图像。可据此 获取图片基本信息 并 处理图片。Width 和 Height 分别为图片的宽度和高度，单位为像素。UUID 字段需填写全局唯一的 String 值，一般填入图片的 MD5 值。消息接收者通过调用 V2TIMImageElem.getImageList() 拿到 V2TIMImage 对象，然后通过调用 V2TIMImage.getUUID() 拿到设置的 UUID 字段，业务 App 可以用这个字段做图片的区分。
{
    "MsgType": "TIMImageElem",
    "MsgContent": {
        "UUID": "1853095_D61040894AC3DE44CDFFFB3EC7EB720F",
        "ImageFormat": 1,
        "ImageInfoArray": [
            {
                "Type": 1,           //原图
                "Size": 1853095,
                "Width": 2448,
                "Height": 3264,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/0"
            },
            {
                "Type": 2,      //大图
                "Size": 2565240,
                "Width": 0,
                "Height": 0,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/720"
            },
            {
                "Type": 3,   //缩略图
                "Size": 12535,
                "Width": 0,
                "Height": 0,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/198"
            }
        ]
    }
}
字段
类型
说明
UUID
String
图片的唯一标识，客户端用于索引图片的键值。
ImageFormat
Number
图片格式。
JPG = 1
GIF = 2
PNG = 3
BMP = 4
其他 = 255
ImageInfoArray
Array
原图、缩略图或者大图下载信息。
Type
Number
图片类型：
1-原图
2-大图
3-缩略图
Size
Number
图片数据大小，单位：字节。
Width
Number
图片宽度，单位为像素。
Height
Number
图片高度，单位为像素。
URL
String
图片下载地址。

文件消息元素

注意：
通过服务端集成的 REST API 接口发送文件消息时，需要填入文件的 Url、UUID、Download_Flag 字段。需保证通过该 Url 能下载到对应文件。UUID 字段需填写全局唯一的 String 值，一般填入文件的 MD5 值。消息接收者可以通过调用 V2TIMFileElem.getUUID() 拿到设置的 UUID 字段，业务 App 可以用这个字段做文件的区分。Download_Flag字段必须填2。
4.X 及以上版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的文件消息元素的格式如下：
{
    "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
    }
}
字段
类型
说明
Url
String
文件下载地址，可通过该 URL 地址直接下载相应文件。
UUID
String
文件的唯一标识，客户端用于索引文件的键值。
FileSize
Number
文件数据大小，单位：字节。
FileName
String
文件名称。
Download_Flag
Number
文件下载方式标记。目前 Download_Flag 取值只能为2，表示可通过Url字段值的 URL 地址直接下载文件。
说明：
2.X和3.X版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的文件消息元素如下：
{
    "MsgType": "TIMFileElem",
    "MsgContent": {
        "UUID": "305c02010", //文件的唯一标识，类型为 String。客户端用于索引文件的键值。无法通过该字段下载相应的文件。若需要获取该文件，请升级 IM SDK 版本至4.X。
        "FileSize": 1773552, //文件数据大小，类型为 Number，单位：字节。
        "FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV" //文件名称，类型为 String。
    }
}

视频消息元素

注意：
通过服务端集成的 REST API 接口发送视频消息时，必须填入 VideoUrl、VideoUUID、ThumbUrl、ThumbUUID、ThumbWidth、ThumbHeight、VideoDownloadFlag 和 ThumbDownloadFlag字段。
需保证通过 VideoUrl 能下载到对应视频，通过 ThumbUrl 能下载到对应的视频缩略图。
VideoUUID 和 ThumbUUID 字段需填写全局唯一的 String 值，一般填入对应视频和视频缩略图的 MD5 值。
消息接收者可以通过调用 V2TIMVideoElem.getVideoUUID() 和 V2TIMVideoElem.getSnapshotUUID() 分别拿到设置的 UUID 字段，业务 App 可以用这个字段做视频的区分。
VideoDownloadFlag 和 ThumbDownloadFlag 字段必须填2。
4.X 及以上版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的视频消息元素的格式如下：
{
    "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
    }
}
字段
类型
说明
VideoUrl
String
视频下载地址。可通过该 URL 地址直接下载相应视频。
VideoUUID
String
视频的唯一标识，客户端用于索引视频的键值。
VideoSize
Number
视频数据大小，单位：字节。
VideoSecond
Number
视频时长，单位：秒。Web 端不支持获取视频时长，值为0。
VideoFormat
String
视频格式，例如 mp4。
VideoDownloadFlag
Number
视频下载方式标记。目前 VideoDownloadFlag 取值只能为2，表示可通过 VideoUrl 字段值的 URL 地址直接下载视频。
ThumbUrl
String
视频缩略图下载地址。可通过该 URL 地址直接下载相应视频缩略图。
ThumbUUID
String
视频缩略图的唯一标识，客户端用于索引视频缩略图的键值。
ThumbSize
Number
缩略图大小，单位：字节。
ThumbWidth
Number
缩略图宽度，单位为像素。
ThumbHeight
Number
缩略图高度，单位为像素。
ThumbFormat
String
缩略图格式，例如 JPG、BMP 等。
ThumbDownloadFlag
Number
视频缩略图下载方式标记。目前 ThumbDownloadFlag 取值只能为2，表示可通过 ThumbUrl 字段值的 URL 地址直接下载视频缩略图。
说明：
2.X和3.X版本 IM SDK（Android、iOS、Mac 以及 Windows）发出的视频消息元素如下：
{
    "MsgType": "TIMVideoFileElem",
    "MsgContent": {
        "VideoUUID": "1400123456_dramon_34ca36be7dd214dc50a49238ef80a6b5",//视频的唯一标识，类型为 String。客户端用于索引视频的键值。无法通过该字段下载相应的视频。若需要获取该视频，请升级 IM SDK 版本至4.X。
        "VideoSize": 1194603, //视频数据大小，类型为 Number，单位：字节。
        "VideoSecond": 5,     //视频时长，类型为 Number，单位：秒。
        "VideoFormat": "mp4", //视频格式，类型为 String，例如 mp4。
        "ThumbUUID": "1400123456_dramon_893f5a7a4872676ae142c08acd49c18a",//视频缩略图的唯一标识，类型为 String。客户端用于索引视频缩略图的键值。无法通过该字段下载相应的视频缩略图。若需要获取该视频缩略图，请升级 IM SDK 版本至4.X。
        "ThumbSize": 13907,   //缩略图大小，类型为 Number，单位：字节。
        "ThumbWidth": 720,    //缩略图宽度。类型为 Number。
        "ThumbHeight": 1280,  //缩略图高度。类型为 Number。
        "ThumbFormat": "JPG"  //缩略图格式，类型为 String，例如 JPG、BMP 等。
    }
}

合并转发消息元素

注意：
终端 5.2.210 及以上版本，Web & 小程序 & uni-app 2.10.1 及以上版本才支持收发合并转发消息。
{
  "MsgType": "TIMRelayElem",
  "MsgContent": {
    "Title": "群聊的聊天记录",
    "MsgNum": 2,
    "CompatibleText": "该SDK版本不支持合并转发消息，请升级到新版本。",
    "AbstractList": [
      "A:大家觉得这个怎么样？",
      "B:我觉得挺好的"
    ],
    "MsgList": [
      {
        "From_Account": "A",
        "GroupId": "group1",
        "MsgSeq": 85,
        "MsgRandom": 3998651049,
        "MsgTimeStamp": 1664437702,
        "MsgBody": [
          {
            "MsgContent": {
              "Text": "大家觉得这个怎么样？"
            },
            "MsgType": "TIMTextElem"
          }
        ]
      },
      {
        "From_Account": "B",
        "GroupId": "group1",
        "MsgSeq": 86,
        "MsgRandom": 965790,
        "MsgTimeStamp": 1664437703,
        "MsgBody": [
          {
            "MsgContent": {
              "Text": "我觉得挺好的"
            },
            "MsgType": "TIMTextElem"
          }
        ]
      }
    ]
  }
}
字段
类型
说明
Title
String
合并转发消息的标题。
MsgNum
Integer
被转发的消息条数。
CompatibleText
String
兼容文本。当不支持合并转发消息的老版本 SDK 收到此类消息时，IM 后台会将该消息转化成兼容文本再下发。
AbstractList
Array
合并消息的摘要列表，是一个 String 数组。
MsgList
Array
消息列表。当被转发的消息长度之和小于等于12K时才会有此字段，此时不会有 JsonMsgKey 字段。
JsonMsgKey
String
合并转发的消息列表 Key。当被转发的消息长度之和大于12K时才会有此字段，此时不会有 MsgList 字段。
MsgList 中每条消息的结构如下：
字段
类型
说明
From_Account
String
消息发送方 UserID。被转发的消息为单聊或群聊时都有此字段。
To_Account
String
消息接收方 UserID。被转发的消息为单聊才有此字段。
GroupId
String
群 ID。被转发的消息为群聊才有此字段。
MsgSeq
Integer
消息序列号（32位无符号整数）。
MsgRandom
Integer
消息随机数（32位无符号整数）。
MsgTimeStamp
Integer
消息的秒级时间戳。
MsgBody
Array
消息内容，具体格式请参见 消息格式描述（注意，一条消息可包括多种消息元素，MsgBody 为 Array 类型）。
CloudCustomData
String
消息自定义数据（云端保存，会发送到对端，程序卸载重装后还能拉取到）。

MsgBody 消息内容实例

单一文本元素消息

单条消息中只包括一个中文本消息元素，文本内容为 hello world。
{
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello world"
            }
        }
    ]
}

组合消息

下述的单条消息中包括两个文本消息元素和一个表情元素，消息元素顺序是文本 + 表情 + 文本。
{
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello"
            }
        }, 
        {
            "MsgType": "TIMFaceElem", 
            "MsgContent": {
                "Index": 1, 
                "Data": "content"
            }
        }, 
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "world"
            }
        }
    ]
}
注意：
一条组合消息中只能带一个 TIMCustomElem 自定义消息元素， 其它消息元素数量无限制。

消息自定义数据 CloudCustomData 说明

每条消息可以携带自定义数据 CloudCustomData。
CloudCustomData 会跟该条消息的 MsgBody 一起保存在云端，CloudCustomData 会发送到对端，程序卸载重装后还能拉取到。
CloudCustomData 与 MsgBody 的格式示例如下：
{
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello"
            }
        }
    ],
    "CloudCustomData": "your cloud custom data"
}



中国站
目录