tencent cloud

实时音视频

动态与公告
产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
产品简介
产品概述
基本概念
产品功能
产品优势
应用场景
性能数据
购买指南
计费概述
免费时长说明
月订阅
现收现付
TRTC 逾期与暂停政策
常见问题解答
退款说明
新手指引
Demo 体验
视频通话 SDK
组件介绍
开通服务
跑通 Demo
快速接入
离线唤醒
会话聊天
云端录制
AI 降噪
界面定制
Chat 集成通话能力
更多特性
无 UI 集成
服务端 API
客户端 API
解决方案
错误码表
发布日志
常见问题
视频会议 SDK
组件介绍（TUIRoomKit）
开通服务（TUIRoomKit）
跑通 Demo（TUIRoomKit）
快速接入（TUIRoomKit）
屏幕共享（TUIRoomKit）
预定会议（TUIRoomKit）
会中呼叫（TUIRoomKit）
界面定制（TUIRoomKit）
虚拟背景（TUIRoomKit）
会议控制（TUIRoomKit）
云端录制（TUIRoomKit）
AI 降噪（TUIRoomKit）
会中聊天（TUIRoomKit）
机器人推流（TUIRoomKit）
更多特性（TUIRoomKit）
客户端 API（TUIRoomKit）
服务端 API（TUIRoomKit）
常见问题（TUIRoomKit）
错误码 (TUIRoomKit)
SDK更新日志（TUIRoomKit）
直播与语聊 SDK
Live 视频直播计费说明
组件介绍
开通服务（TUILiveKit）
跑通 Demo
无 UI 集成
UI 自定义
直播监播
视频直播
语聊房
高级功能
客户端 API
服务端 API
错误码
发布日志
常见问题
RTC Engine
开通服务
SDK 下载
API-Example
接入指引
API-参考手册
高级功能
AI 集成
概述
MCP 配置
Skills 配置
集成指南
常见问题
RTC RESTFUL API
History
Introduction
API Category
Room Management APIs
Stream mixing and relay APIs
On-cloud recording APIs
Data Monitoring APIs
Pull stream Relay Related interface
Web Record APIs
AI Service APIs
Cloud Slicing APIs
Cloud Moderation APIs
Making API Requests
Call Quality Monitoring APIs
Usage Statistics APIs
Data Types
Appendix
Error Codes
控制台指南
应用管理
套餐包管理
用量统计
监控仪表盘
开发辅助
解决方案
实时合唱
常见问题
迁移指南
计费相关
功能相关
UserSig 相关
应对防火墙限制相关
缩减安装包体积相关
Andriod 与 iOS 相关
Web 端相关
Flutter 相关
Electron 相关
TRTCCalling Web 相关
音视频质量相关
其他问题
旧版文档
RTC RoomEngine SDK（旧）
集成 TUIRoom (Web)
集成 TUIRoom (Android)
集成 TUIRoom (iOS)
集成 TUIRoom (Flutter)
集成 TUIRoom (Electron)
TUIRoom API 查询
实现云端录制与回放（旧）
监控仪表盘计费（旧）
协议与策略
安全合规认证
安全白皮书
信息安全说明
服务等级协议
苹果隐私策略：PrivacyInfo.xcprivacy
TRTC 政策
隐私协议
数据处理和安全协议
词汇表
Documentation实时音视频直播与语聊 SDK服务端 APIREST API消息管理消息格式描述

消息格式描述

PDF
Focus Mode
Font Size
Last updated: 2026-03-26 17:39:57

消息内容 MsgBody 说明

MsgBody 中所填写字段是消息内容。 Chat 支持一条消息中包括多种消息元素类别，例如一条消息中既包括文本消息元素，还包括表情消息元素。因此 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
视频消息。
注意：
上述类型的消息均能通过服务端集成的 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 自定义消息元素时，如果 Desc 字段和 OfflinePushInfo.Desc 字段都不填写，将收不到该条消息的离线推送，需要填写 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 及以上版本 Chat 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 版本 Chat 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 及以上版本 Chat 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 版本 Chat 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）发出的视频消息元素的格式如下：

视频消息元素

注意：
通过服务端集成的 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 及以上版本 Chat 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 版本 Chat 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 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 收到此类消息时，Chat 后台会将该消息转化成兼容文本再下发。
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"
}



Previous Topic: 发送自定义消息Next Topic: 第三方回调简介

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback