消息格式描述

Recent Pages

消息格式描述

最后更新时间：2024-12-16 18:07:25

消息内容 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
视频消息。
注意
上述类型的消息均能通过服务端集成的 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", 
        "Desc": "notification", 
        "Ext": "url", 
        "Sound": "dingdong.aiff"
    }
}
字段
类型
说明
Data
String
自定义消息数据。 不作为 APNs 的 payload 字段下发，故从 payload 中无法获取 Data 字段。
Desc
String
自定义消息描述信息。当接收方为 iOS 或 Android 后台在线时，做离线推送文本展示。若发送自定义消息的同时设置了 OfflinePushInfo.Desc 字段，此字段会被覆盖，请优先填 OfflinePushInfo.Desc 字段。
说明：
当消息中只有一个 TIMCustomElem 自定义消息元素时，如果 Desc 字段和 OfflinePushInfo.Desc 字段都不填写，将收不到该条消息的离线推送，需要填写 OfflinePushInfo.Desc 字段才能收到该消息的离线推送。
﻿
Ext
String
扩展字段。当接收方为 iOS 系统且应用处在后台时，此字段作为 APNs 请求包 Payloads 中的 Ext 键值下发，Ext 的协议格式由业务方确定，APNs 只做透传。
Sound
String
自定义 APNs 推送铃音。
当接收方为 iOS 系统且应用处在后台时，Desc 作为推送文本， Ext 字段作为 APNS 请求包 Payloads 中的 ext 键值下发， Data 字段不作为 APNs 的 Payloads 字段下发。注意，一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。
语音消息元素
注意
通过服务端集成的 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）发出的视频消息元素的格式如下：
视频消息元素
注意：
通过服务端集成的 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&quot;,
        "VideoUUID": "5da38ba89d6521011e1f6f3fd6692e35",
        "VideoSize": 1194603,
        "VideoSecond": 5,
        "VideoFormat": "mp4",
        "VideoDownloadFlag":2,
        "ThumbUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/a6c170c9c599280cb06e0523d7a1f37b&quot;,
        "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 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"
}
Apple Push Notification Service（APNs）相关说明
客户端推送展示格式说明
未设置账号昵称
如果账号没有设置昵称，APNs 推送只展示推送文本内容。单聊消息只展示“推送文本”，群组消息展示“(群名称):推送文本”。
﻿
已设置账号昵称
如果账号设置昵称，单聊消息展示格式为“昵称：推送文本内容”，群组消息展示格式为昵称(群名称)：推送文本内容。
﻿
组合消息展示格式
对于组合消息，按顺序叠加各个消息元素的推送文本作为展示文本。下述为已设置帐户昵称的单聊消息，推送文本为"helloworld"。注意 helloworld 中间没有空格，后台按照顺序叠加，各个消息元素推送文本之间不添加任何字符。如需要在各个不同的消息元素间添加空格或其他字符，需调用方自己控制。
{
  "MsgBody": [
      {
          "MsgType": "TIMTextElem", 
          "MsgContent": {
              "Text": "hello"  
          }
      },
      {
          "MsgType": "TIMCustomElem",
          "MsgContent": {
              "Data": "message",
              "Desc": "world",
              "Ext": "https://www.example.com",               
              "Sound": "dingdong.aiff"
          }
      }
  ] 
}
各类消息元素推送文本字段汇总。
MsgType 的值
类型
消息元素推送文本
TIMTextElem
文本消息。
Text 字段。
TIMLocationElem
地理位置消息。
中文版离线推送文本为“[位置]”；英文版为“[Location]”。
TIMFaceElem
表情消息。
中文版离线推送文本为“[表情]”；英文版为“[Face]”。
TIMCustomElem
自定义消息。
Desc 字段。
昵称和群名称 REST API 设置接口
设置账号昵称 REST API 接口：设置资料。
设置群名称 REST API 接口：修改群组基础资料。
高级应用
自定义推送声音，APNs 下发扩展字段.
利用自定义消息元素 TIMCustomElem，Sound 填写自定义声音文件名称， Ext 填写下发的扩展字段，请求扩展字段可以从 APNs 推送 PayLoad 中的 Ext 字段获取。
{
    "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"
            }
        }
    ]
}
﻿
客户端收到 APNs 推送 JSON Payload 为：
{
    "aps": {
        "alert": "Nickname:helloworld",   //各个消息元素推送文本顺序叠加
        "badge": 5,                       
        "sound": "dingdong.aiff"         //对应 TIMCustomElem 中 Sound 字段
    }, 
    "ext": "www.qq.com"                //对应 TIMCustomElem 中 Ext 字段
}
﻿
离线推送 OfflinePushInfo 说明
OfflinePushInfo 是专用于离线推送配置的 JSON 对象，允许配置该条消息是否关闭推送、推送文本描述内容、推送透传字符串等。使用 OfflinePushInfo 可以方便地设置离线推送信息，无需再通过 TIMCustomElem 封装实现。
注意
如果填写了 OfflinePushInfo，那么 TIMCustomElem 中与离线推送有关的信息配置会被忽略。目前 OfflinePushInfo 适用于 APNs 推送，以及 Android 厂商推送（小米、华为、魅族、OPPO 和 vivo 推送）。
OfflinePushInfo 的格式示例如下：
{
    // ...
    "MsgBody": [...] // 这里同 MsgBody 相关描述
    "OfflinePushInfo": {
        "PushFlag": 0,
        "Title":"这是推送标题",
        "Desc": "这是离线推送内容",
        "Ext": "{\\"entity\\":{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}}",  // 透传字段，推送使用json格式字符串
        "AndroidInfo": { 
            "Sound": "shake",  // 铃声文件名，不带后缀
            "XiaoMiChannelID": "xiaomi_channel_id",
            "OPPOChannelID": "OPPO_channel_id",
            "OPPOCategory": "MARKETING",   // OPPO 消息分类
            "VIVOCategory": "MARKETING",   // VIVO 消息分类
            "HuaWeiCategory": "MARKETING", // 华为消息分类
            "HonorImportance": "LOW"       // 荣耀消息分类
        },
        "ApnsInfo": {
            "Sound": "apns.mp3", // 铃声文件名，带后缀
            "BadgeMode": 1,
            "Title":"apns title",
            "SubTitle":"apns subtitle",
            "Image":"www.image.com",
            "MutableContent": 1
        }
    }
}
字段说明如下：
字段
类型
属性
说明
PushFlag
Integer
选填
0表示推送，1表示不离线推送。
Title
String
选填
离线推送标题。该字段为 iOS 和 Android 共用。
Desc
String
选填
离线推送内容。该字段会覆盖上面各种消息元素 TIMMsgElement 的离线推送展示文本。若发送的消息只有一个 TIMCustomElem 自定义消息元素，该 Desc 字段会覆盖 TIMCustomElem 中的 Desc 字段。如果两个 Desc 字段都不填，将收不到该自定义消息的离线推送。
Ext
String
选填
离线推送透传内容。由于国内各 Android 手机厂商的推送平台要求各不一样，请保证此字段为 JSON 格式，否则可能会导致收不到某些厂商的离线推送。
AndroidInfo.Sound
String
选填
Android 离线推送声音文件路径。
AndroidInfo.PushStyle
Integer
选填
Android通知栏样式，“0”代表默认样式，“1”代表大文本样式，不填默认为0。仅对华为/荣耀/OPPO生效。
AndroidInfo.HuaWeiChannelID
String
选填
华为手机 EMUI 10.0 及以上的通知渠道字段。
该字段不为空时，会覆盖控制台推送证书配置的 ChannelID 值。
AndroidInfo.XiaoMiChannelID
String
选填
小米手机 MIUI 10 及以上的通知类别（Channel）适配字段。
该字段不为空时，会覆盖控制台推送证书配置的 ChannelID 值。
AndroidInfo.GoogleChannelID
String
选填
Google 手机 Android 8.0 及以上的通知渠道字段。
AndroidInfo.OPPOChannelID
String
选填
OPPO 手机 Android 8.0 及以上的 NotificationChannel 通知适配字段。该字段不为空时，会覆盖控制台配置的 ChannelID 值；该字段为空时，不会覆盖控制台配置的 ChannelID 值。
AndroidInfo.OPPOCategory
String
选填
OPPO 手机消息分类，用于标识消息类型，详细参见 category 描述。
该字段不为空时，会覆盖控制台推送证书配置的 category 值。
AndroidInfo.VIVOClassification
Integer
选填
vivo 手机推送消息分类，“0”代表运营消息，“1”代表系统消息，不填默认为1。(vivo推送服务于 2023 年 4 月 3 日优化消息分类规则，推荐使用 AndroidInfo.VIVOCategory 设置消息类别)
AndroidInfo.VIVOCategory
String
选填
vivo 手机消息分类，用于标识消息类型，详细参见 category 描述 。
该字段不为空时，会覆盖控制台推送证书配置的 category 值。
AndroidInfo.HuaWeiImportance
String
选填
华为推送通知消息分类，取值为 LOW、NORMAL，不填默认为 NORMAL。
AndroidInfo.HuaWeiCategory
String
选填
华为手机用来标识消息类型，该字段不为空时，会覆盖控制台配置的 category 值；该字段为空时，不会覆盖控制台配置的 category 值。详见 category 描述。
AndroidInfo.HuaWeiImage
String
选填
华为推送通知栏消息右侧小图标URL，URL必须使用HTTPS协议，取值样例：https://example.com/image.png。图片文件须小于512KB，规格建议为40dp x 40dp，弧角大小为8dp。超出建议规格的图片会存在图片压缩或图片显示不全的情况。图片格式建议使用JPG/JPEG/PNG。
AndroidInfo.HonorImage
String
选填
荣耀推送通知栏消息右侧小图标 URL，URL 必须使用 HTTPS 协议，取值样例：https://example.com/image.png。 图标文件须小于512KB，图标建议规格大小：40dp x 40dp，弧角大小为8dp，超出建议规格大小的图标会存在图片压缩或显示不全的情况。
AndroidInfo.HonorImportance
String
选填
荣耀推送通知消息分类，取值为 LOW、NORMAL。
AndroidInfo.GoogleImage
String
选填
Google 推送通知栏消息右侧图标 URL，图片资源不超过1M，支持 JPG/JPEG/PNG 格式，取值样例：https://example.com/image.png。
ApnsInfo.BadgeMode
Integer
选填
为0表示需要计数，为1表示本条消息不需要计数，即右上角图标数字不增加。
注意：
IM 场景下默认值为0。非 IM 场景（例如 REST API 调用 timpush/batch 接口）默认值为1。
ApnsInfo.Title
String
选填
该字段用于标识 APNs 推送的标题，若填写则会覆盖最上层 Title。
ApnsInfo.SubTitle
String
选填
该字段用于标识 APNs 推送的子标题。
ApnsInfo.Image
String
选填
该字段用于标识 APNs 携带的图片地址，当客户端拿到该字段时，可以通过下载图片资源的方式将图片展示在弹窗上。
ApnsInfo.MutableContent
Integer
选填
为1表示开启 iOS 10+ 的推送扩展，默认为0。
ApnsInfo.Sound
String
选填
iOS 系统通知铃声文件名，带后缀。自定义铃声长度不能超过30s，需要先把语音文件链接进 Xcode工程。取值样例：shake.mp3。
注意
由于 APNs 推送限制数据包大小不能超过4K，因此除去其他控制字段，建议 Desc 和 Ext 字段之和不要超过3K。
参考
Apple Push Notification Service(APNs) 苹果推送开发文档。
iOS 离线消息推送配置：离线推送(iOS)。

联系我们

联系我们，为您的业务提供专属服务。

技术支持

如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

7x24 电话支持

tencent cloud

Recent Pages

消息格式描述

消息内容 MsgBody 说明

消息元素 TIMMsgElement

文本消息元素

地理位置消息元素

表情消息元素

自定义消息元素

语音消息元素

图像消息元素

文件消息元素

视频消息元素

合并转发消息元素

MsgBody 消息内容实例

单一文本元素消息

组合消息

消息自定义数据 CloudCustomData 说明

Apple Push Notification Service（APNs）相关说明

客户端推送展示格式说明

昵称和群名称 REST API 设置接口

高级应用

自定义推送声音，APNs 下发扩展字段.

离线推送 OfflinePushInfo 说明

参考

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？

字段	类型	说明
MsgType	String	消息元素类别；目前支持的消息对象包括：TIMTextElem(文本消息)，TIMLocationElem(位置消息)，TIMFaceElem(表情消息)，TIMCustomElem(自定义消息)，TIMSoundElem(语音消息)，TIMImageElem(图像消息)，TIMFileElem(文件消息)，TIMVideoFileElem(视频消息)。
MsgContent	Object	消息元素的内容，不同的 MsgType 有不同的 MsgContent 格式，具体参见下文。

MsgType的值	类型
TIMTextElem	文本消息。
TIMLocationElem	地理位置消息。
TIMFaceElem	表情消息。
TIMCustomElem	自定义消息，当接收方为 iOS 系统且应用处在后台时，此消息类型可携带除文本以外的字段到 APNs。一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。
TIMSoundElem	语音消息。
TIMImageElem	图像消息。
TIMFileElem	文件消息。
TIMVideoFileElem	视频消息。

MsgType 的值	类型	消息元素推送文本
TIMTextElem	文本消息。	Text 字段。
TIMLocationElem	地理位置消息。	中文版离线推送文本为“[位置]”；英文版为“[Location]”。
TIMFaceElem	表情消息。	中文版离线推送文本为“[表情]”；英文版为“[Face]”。
TIMCustomElem	自定义消息。	Desc 字段。

字段	类型	属性	说明
PushFlag	Integer	选填	0表示推送，1表示不离线推送。
Title	String	选填	离线推送标题。该字段为 iOS 和 Android 共用。
Desc	String	选填	离线推送内容。该字段会覆盖上面各种消息元素 TIMMsgElement 的离线推送展示文本。若发送的消息只有一个 TIMCustomElem 自定义消息元素，该 Desc 字段会覆盖 TIMCustomElem 中的 Desc 字段。如果两个 Desc 字段都不填，将收不到该自定义消息的离线推送。
Ext	String	选填	离线推送透传内容。由于国内各 Android 手机厂商的推送平台要求各不一样，请保证此字段为 JSON 格式，否则可能会导致收不到某些厂商的离线推送。
AndroidInfo.Sound	String	选填	Android 离线推送声音文件路径。
AndroidInfo.PushStyle	Integer	选填	Android通知栏样式，“0”代表默认样式，“1”代表大文本样式，不填默认为0。仅对华为/荣耀/OPPO生效。
AndroidInfo.HuaWeiChannelID	String	选填	华为手机 EMUI 10.0 及以上的通知渠道字段。该字段不为空时，会覆盖控制台推送证书配置的 ChannelID 值。
AndroidInfo.XiaoMiChannelID	String	选填	小米手机 MIUI 10 及以上的通知类别（Channel）适配字段。该字段不为空时，会覆盖控制台推送证书配置的 ChannelID 值。
AndroidInfo.GoogleChannelID	String	选填	Google 手机 Android 8.0 及以上的通知渠道字段。
AndroidInfo.OPPOChannelID	String	选填	OPPO 手机 Android 8.0 及以上的 NotificationChannel 通知适配字段。该字段不为空时，会覆盖控制台配置的 ChannelID 值；该字段为空时，不会覆盖控制台配置的 ChannelID 值。
AndroidInfo.OPPOCategory	String	选填	OPPO 手机消息分类，用于标识消息类型，详细参见 category 描述。该字段不为空时，会覆盖控制台推送证书配置的 category 值。
AndroidInfo.VIVOClassification	Integer	选填	vivo 手机推送消息分类，“0”代表运营消息，“1”代表系统消息，不填默认为1。(vivo推送服务于 2023 年 4 月 3 日优化消息分类规则，推荐使用 AndroidInfo.VIVOCategory 设置消息类别)
AndroidInfo.VIVOCategory	String	选填	vivo 手机消息分类，用于标识消息类型，详细参见 category 描述。该字段不为空时，会覆盖控制台推送证书配置的 category 值。
AndroidInfo.HuaWeiImportance	String	选填	华为推送通知消息分类，取值为 LOW、NORMAL，不填默认为 NORMAL。
AndroidInfo.HuaWeiCategory	String	选填	华为手机用来标识消息类型，该字段不为空时，会覆盖控制台配置的 category 值；该字段为空时，不会覆盖控制台配置的 category 值。详见 category 描述。
AndroidInfo.HuaWeiImage	String	选填	华为推送通知栏消息右侧小图标URL，URL必须使用HTTPS协议，取值样例：`https://example.com/image.png`。图片文件须小于512KB，规格建议为40dp x 40dp，弧角大小为8dp。超出建议规格的图片会存在图片压缩或图片显示不全的情况。图片格式建议使用JPG/JPEG/PNG。
AndroidInfo.HonorImage	String	选填	荣耀推送通知栏消息右侧小图标 URL，URL 必须使用 HTTPS 协议，取值样例：`https://example.com/image.png`。图标文件须小于512KB，图标建议规格大小：40dp x 40dp，弧角大小为8dp，超出建议规格大小的图标会存在图片压缩或显示不全的情况。
AndroidInfo.HonorImportance	String	选填	荣耀推送通知消息分类，取值为 LOW、NORMAL。
AndroidInfo.GoogleImage	String	选填	Google 推送通知栏消息右侧图标 URL，图片资源不超过1M，支持 JPG/JPEG/PNG 格式，取值样例：`https://example.com/image.png`。
ApnsInfo.BadgeMode	Integer	选填	为0表示需要计数，为1表示本条消息不需要计数，即右上角图标数字不增加。注意： IM 场景下默认值为0。非 IM 场景（例如 REST API 调用 timpush/batch 接口）默认值为1。
ApnsInfo.Title	String	选填	该字段用于标识 APNs 推送的标题，若填写则会覆盖最上层 Title。
ApnsInfo.SubTitle	String	选填	该字段用于标识 APNs 推送的子标题。
ApnsInfo.Image	String	选填	该字段用于标识 APNs 携带的图片地址，当客户端拿到该字段时，可以通过下载图片资源的方式将图片展示在弹窗上。
ApnsInfo.MutableContent	Integer	选填	为1表示开启 iOS 10+ 的推送扩展，默认为0。
ApnsInfo.Sound	String	选填	iOS 系统通知铃声文件名，带后缀。自定义铃声长度不能超过30s，需要先把语音文件链接进 Xcode工程。取值样例：`shake.mp3`。

tencent cloud

注册

登录

Recent Pages

消息格式描述

消息内容 MsgBody 说明

消息元素 TIMMsgElement

文本消息元素

地理位置消息元素

表情消息元素

自定义消息元素

语音消息元素

图像消息元素

文件消息元素

视频消息元素

合并转发消息元素

MsgBody 消息内容实例

单一文本元素消息

组合消息

消息自定义数据 CloudCustomData 说明

Apple Push Notification Service（APNs）相关说明

客户端推送展示格式说明

昵称和群名称 REST API 设置接口

高级应用

自定义推送声音，APNs 下发扩展字段.

离线推送 OfflinePushInfo 说明

参考

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？