云服务器特惠 99/年起
  1. 腾讯云优惠网首页
  2. 腾讯云产品

即时通信 IM 消息格式描述

• 腾讯云产品

MsgBody 中所填写字段是消息内容。即时通信 IM 支持一条消息中包括多种消息元素类别，例如一条消息中既包括文本消息元素，还包括表情消息元素。因此 MsgBody 定义为 Array 格式，可按照需求加入多类消息元素。消息元素名称为 TIMMsgElement，消息元素 TIMMsgElement 组成 MsgBody 的示例。

相关产品
即时通信 IM 产品页，含版本规格、价格与购买入口。

一、消息内容 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 接口发送。

二、文本消息元素

{ "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 自定义消息数据。
Desc String 消息描述信息。注意与 OfflinePushInfo.Desc 不是同一字段，此字段主要用于本地消息搜索。

六、语音消息元素

注意：通过服务端集成的 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 = 1GIF = 2PNG = 3BMP = 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 消息自定义数据（云端保存，会发送到对端，程序卸载重装后还能拉取到）。

十一、单一文本元素消息

单条消息中只包括一个文本消息元素，文本内容为 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"}

十四、公共参数（OfflinePushInfo 说明）

OfflinePushInfo 是专用于离线推送配置的 JSON 对象，允许配置该条消息是否关闭推送、推送文本、推送透传字符串等。如果填写了 OfflinePushInfo 中对应字段，那么 TIMCustomElem 中与离线推送相关配置会被忽略，详情参见 公共参数（OfflinePushInfo 说明）。

MsgBody 与 OfflinePushInfo 的格式示例如下：

{ "MsgBody": […], // 这里同 MsgBody 相关描述 "OfflinePushInfo": { "PushFlag": 0, "Title":"离线推送标题", "Desc": "离线推送内容", "Ext": "{\\"entity\\":{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}}", // 透传字段，推送使用json格式字符串 "AndroidInfo": { // … }, "ApnsInfo": { // … } }}

相关内容：

  1. 即时通信 IM 添加自定义消息 https://xxxxxx/v4/live_engine_http_srv/send_custom_msg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json。...
  2. 即时通信 IM 集成自建 AI 或第三方大模型 可以以通过此方案对接自建或者第三方的 AI 机器人，依托智能客服丰富的开放接口，自定义开发客服场景。智能客服已提供 用户端集成方案 和 客服工作台，用户可通过移动端、小程序或网页端给客服号发送消息，与自建或第三方的 AI 机器人对话，转人工成功后，客服人员可在 工作台 接待用户咨询。...
  3. 即时通信 IM AI 聊天机器人方案 随着 AI 已成为当下开发者最为关注的焦点，AI+ 即时通信的结合也得到了进一步的发展和应用。腾讯云即时通信 IM 作为全球领先的通信云服务商，快速发布了相关 AI 能力调用接口，开发者基于腾讯云 IM 提供的通信底座，可以自由调用业内领先的大模型能力，用丰富的 AI 能力赋能业务，实现社交娱乐、在线教育、智能客服等场景的智能化。同时，腾讯云即时通信 IM 还配备有完善的 AI 聊天场景 UI 组件，即开即用，基于 。...
  4. 即时通信 IM 互动游戏场景方案 在游戏中，即时通信需求很常见，在多人游戏中即时聊天也成为了必不可少的功能。由于游戏平台本身所涉及到的多种群组类型、自定义消息类型（如游戏内道具赠送、交易等业务）、全球接入等需求往往比较复杂，这篇梳理了在搭建游戏聊天过程中常见的需求的实现方法，以及可能遇到的问题、需要注意的细节等，希望能帮助开发者们快速的理解业务，实现需求。...
  5. 即时通信 IM 发送红包 这篇档介绍了基于腾讯云 IM（即时通信）实现红包功能的实践方案。红包功能支持两种场景。...
  6. 即时通信 IM 配置场景和策略 开通 AI 内容理解及审核服务后，默认开启了六大通用场景的音视图文审核。如果需要调整关闭某一场景的某一消息类型的开关，请单击修改场景配置。 在弹窗中勾选/取消勾选对应项目，单击确定即可。...
  7. 即时通信 IM 自定义点击推送跳转 自定义点击跳转功能允许你在推送消息中携带特定参数（如下发附加字段），客户端应用据此执行精准的业务逻辑跳转（例如直达指定页面、触发特定功能）。这里说明各厂商通道对自定义点击跳转的支持情况以及如何实现该功能。...
  8. 即时通信 IM 集成指引 插件市场是集合了即时通信 IM 可扩展功能的平台，可以根据需要从插件市场中选择插件使用，以帮助你更高效、便捷地集成业务所需能力。可以以在插件市场中浏览提供插件的功能介绍、支持平台、支持语言、版本大小等信息，也可以领取免费试用、付费购买插件服务。可以以根据集成指引完成插件功能配置：概述及开通指引。...
赞 (0)
上一篇 4天前
下一篇 4天前