消息格式描述

最近更新时间:2019-08-28 17:18:31

消息内容 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 语音消息。(服务端集成 Rest API 不支持发送该类消息)
TIMImageElem 图像消息。(服务端集成 Rest API 不支持发送该类消息)
TIMFileElem 文件消息。(服务端集成 Rest API 不支持发送该类消息)
TIMVideoFileElem 视频消息。(服务端集成 Rest API 不支持发送该类消息)
注意:

通过服务端集成的 Rest API 接口,只能发送 TIMTextElem,TIMLocationElem,TIMFaceElem,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]”。

自定义消息元素

{
    "MsgType": "TIMCustomElem", 
    "MsgContent": {
        "Data": "message", 
        "Desc": "notification", 
        "Ext": "url", 
        "Sound": "dingdong.aiff"
    }
}
字段 类型 说明
Data String 自定义消息数据。 不作为 APNs 的 payload 字段下发,故从 payload 中无法获取 Data 字段。
Desc String 自定义消息描述信息;当接收方为 iOS 或 Android 后台在线时,做离线推送文本展示。
Ext String 扩展字段;当接收方为 iOS 系统且应用处在后台时,此字段作为 APNs 请求包 Payloads 中的 Ext 键值下发,Ext 的协议格式由业务方确定,APNs 只做透传。
Sound String 自定义 APNs 推送铃音。

当接收方为 iOS 系统且应用处在后台时,Desc 作为推送文本, Ext 字段作为 APNS 请求包 Payloads 中的 ext 键值下发, Data 字段不作为 APNs 的 Payloads 字段下发。注意,一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。

语音消息元素

注意:

不能通过服务端集成的 Rest API 接口发送语音消息,发送语音消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的语音消息元素的格式如下:

{
    "MsgType": "TIMSoundElem",
    "MsgContent": {
        "Url": "https://1234-5678187359-1253735226.cos.ap-shanghai.myqcloud.com/abc123/c9be9d32c05bfb77b3edafa4312c6c7d",
        "Size": 62351,
        "Second": 1,
        "Download_Flag": 2
    }
}
字段 类型 说明
Url String 语音下载地址,可通过该 URL 地址直接下载相应语音。
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 接口发送图像消息,发送图像消息需要通过客户端集成相应的接口。

{
    "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 接口发送文件消息,发送文件消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的文件消息元素的格式如下:

{
    "MsgType": "TIMFileElem",
    "MsgContent": {
        "Url": "https://7492-5678539059-1253735326.cos.ap-shanghai.myqcloud.com/abc123/49be9d32c0fbfba7b31dafa4312c6c7d",
        "FileSize": 1773552,
        "FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV",
        "Download_Flag": 2
    }
}
字段 类型 说明
Url String 文件下载地址,可通过该 URL 地址直接下载相应文件。
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 接口发送视频消息,发送视频消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的视频消息元素的格式如下:

{
    "MsgType": "TIMVideoFileElem",
    "MsgContent": {
        "VideoUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/f7c6ad3c50af7d83e23efe0a208b90c9",
        "VideoSize": 1194603,
        "VideoSecond": 5,
        "VideoFormat": "mp4",
        "VideoDownloadFlag":2,
        "ThumbUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/a6c170c9c599280cb06e0523d7a1f37b",
        "ThumbSize": 13907,
        "ThumbWidth": 720,
        "ThumbHeight": 1280,
        "ThumbFormat": "JPG",
        "ThumbDownloadFlag":2
    }
}
字段 类型 说明
VideoUrl String 视频下载地址。可通过该 URL 地址直接下载相应视频。
VideoSize Number 视频数据大小,单位:字节。
VideoSecond Number 视频时长,单位:秒。
VideoFormat String 视频格式,例如 mp4。
VideoDownloadFlag Number 视频下载方式标记。目前 VideoDownloadFlag 取值只能为2,表示可通过VideoUrl字段值的 URL 地址直接下载视频。
ThumbUrl String 视频缩略图下载地址。可通过该 URL 地址直接下载相应视频缩略图。
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 等。
    }
}

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 自定义消息元素, 其它消息元素数量无限制。

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": "这是透传的内容",
        "AndroidInfo": { 
            "Sound": "android.mp3"
        },
        "ApnsInfo": {
            "Sound": "apns.mp3",
            "BadgeMode": 1,
            "Title":"apns title",
            "SubTitle":"apns subtitle",
            "Image":"www.image.com"
        }
    }
}

字段说明如下:

字段 类型 属性 说明
PushFlag Integer 选填 0表示推送,1表示不离线推送。
Title String 选填 离线推送标题。该字段为 iOS 和 Android 共用。
Desc String 选填 离线推送内容。
Ext String 选填 离线推送透传内容。
Sound String 选填 离线推送声音文件路径。
ApnsInfo.BadgeMode Integer 选填 这个字段缺省或者为0表示需要计数,为1表示本条消息不需要计数,即右上角图标数字不增加。
ApnsInfo.Title String 选填 该字段用于标识 APNs 推送的标题,若填写则会覆盖最上层 Title。
ApnsInfo.SubTitle String 选填 该字段用于标识 APNs 推送的子标题。
ApnsInfo.Image String 选填 该字段用于标识 APNs 携带的图片地址,当客户端拿到该字段时,可以通过下载图片资源的方式将图片展示在弹窗上。
注意:

由于 APNs 推送限制数据包大小不能超过4K,因此除去其他控制字段,建议 Desc 和 Ext 字段之和不要超过3K。

参考

Apple Push Notification Service(APNs) 苹果推送开发文档
iOS 离线消息推送配置:离线推送(iOS)