Message Format Description

Description of MsgBody Message Content

Message content is entered in the fields of MsgBody. Instant Messaging (IM) supports multiple message elements in one message, for example, a message can contain both text and emojis. Therefore, MsgBody is defined as an array that can include as many message elements as needed. The name for a message element is TIMMsgElement. For examples of the TIMMsgElements that constitute the MsgBody, see MsgBody Message Content Examples.

The format of TIMMsgElement is defined as follows:

{
    "MsgType": "",
    "MsgContent": {}
}

The following table lists the message types (MsgType) that are currently supported:

Only TIMTextElem, TIMLocationElem, TIMFaceElem, and TIMCustomElem messages can be sent through RESTful APIs integrated with the server. Other types of messages including TIMSoundElem, TIMImageElem, TIMFileElem, and TIMVideoFileElem messages cannot be sent through RESTful APIs.

Message Element TIMMsgElement

Text message element

{
    "MsgType": "TIMTextElem",
    "MsgContent": {
        "Text": "hello world"
    }
}

When the receiver is an iOS or Android device and the app is working in the background, the Text field in the JSON request packet is displayed as offline push text.

Location message element

{
    "MsgType": "TIMLocationElem", 
    "MsgContent": {
        "Desc": "someinfo", 
        "Latitude": 29.340656774469956, 
        "Longitude": 116.77497920478824
    }
}

When the receiver is an iOS or Android device and the app is working in the background, the offline push text is [Location] for the English version.

Emoji message element

{
    "MsgType": "TIMFaceElem", 
    "MsgContent": {
        "Index": 1, 
        "Data": "content"
    }
}

When the receiver is an iOS or Android device and the app is working in the background, the offline push text is [Face] for the English version.

Custom message element

{
    "MsgType": "TIMCustomElem", 
    "MsgContent": {
        "Data": "message", 
        "Desc": "notification", 
        "Ext": "url", 
        "Sound": "dingdong.aiff"
    }
}

When the receiver is an iOS or Android device and the app is working in the background, the Desc field is delivered as push text, the Ext field is delivered as an Ext key value in APNs request packet payloads, and the Data field is not delivered as a payload field by APNs. Note that a combined message can contain only one TIMCustomElem custom message element.

Audio message element

Audio messages cannot be sent through server-side integrated RESTful APIs. Instead, they can only be sent through client-side integrated APIs.

4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send audio message elements in the following format:

{
    "MsgType": "TIMSoundElem",
    "MsgContent": {
        "Url": "https://1234-5678187359-1253735226.cos.ap-shanghai.myqcloud.com/abc123/c9be9d32c05bfb77b3edafa4312c6c7d",
        "Size": 62351,
        "Second": 1,
        "Download_Flag": 2
    }
}

2.X and 3.X versions of IM SDK (for Android, iOS, Mac, and Windows) send audio message elements in the following format:

{
    "MsgType": "TIMSoundElem",
    "MsgContent": {
        "UUID": "305c0201", //The serial number of the audio in String type. This is the key value the backend uses to index the audio. Audio cannot be downloaded through this field. To obtain the audio, upgrade the IM SDK to 4.X version.
        "Size": 62351,//The audio data size in bytes, in Number type.
        "Second": 1         //The audio duration in seconds, in Number type.
    }
}

Image message element

Image messages cannot be sent through server-side integrated RESTful APIs. Instead, they can only be sent through client-side integrated APIs.

{
    "MsgType": "TIMImageElem",
    "MsgContent": {
        "UUID": "1853095_D61040894AC3DE44CDFFFB3EC7EB720F",
        "ImageFormat": 1,
        "ImageInfoArray": [
            {
                "Type": 1,           //Original image
                "Size": 1853095,
                "Width": 2448,
                "Height": 3264,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/0"
            },
            {
                "Type": 2,      //Large image
                "Size": 2565240,
                "Width": 0,
                "Height": 0,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/720"
            },
            {
                "Type": 3,   //Thumbnail
                "Size": 12535,
                "Width": 0,
                "Height": 0,
                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/198"
            }
        ]
    }
}

File message element

File messages cannot be sent through server-side integrated RESTful APIs. Instead, they can only be sent through client-side integrated APIs.

4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send file message element in the following format:

{
    "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
    }
}

2.X and 3.X versions of IM SDK (for Android, iOS, Mac, and Windows) send file message elements in the following format:

{
   "MsgType": "TIMFileElem",
   "MsgContent": {
       "UUID": "305c02010", //The serial number of the file in String type. This is the key value the backend uses to index the file. The file cannot be downloaded through this field. To obtain the file, upgrade the IM SDK to 4.X version.
       "FileSize": 1773552, //The size of file data in bytes, in Number type.
       "FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV" //The file name in String type.
   }
}

### Video message element

>Video messages cannot be sent through server-side integrated RESTful APIs. Instead, they can only be sent through client-side integrated APIs.

4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send video message element in the following format:

{
"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
}
}

| Field | Type | Description |
|---------|---------|---------|
| VideoUrl | String | The download URL of the video, through which the video can be downloaded directly. |
| VideoSize | Number | The size of video data in bytes. |
| VideoSecond | Number | The video duration in seconds. |
| VideoFormat | String | The video format, such as mp4. |
| VideoDownloadFlag | Number | The flag of the video download method. Currently, the value of `VideoDownloadFlag` must be 2, which means that the video can be downloaded from the URL that is the value of the `VideoUrl` field. |
| ThumbUrl | String | The download URL of the video thumbnail, through which the video thumbnail can be downloaded directly. |
| ThumbSize | Number | The size of thumbnail data in bytes. |
| ThumbWidth | Number | The thumbnail width. |
| ThumbHeight | Number | The thumbnail height. |
| ThumbFormat | String | The video thumbnail format, such as JPG or BMP. |
| ThumbDownloadFlag | Number | The flag of the video thumbnail download method. Currently, the value of `ThumbDownloadFlag` must be 2, which means that the video thumbnail can be downloaded from the URL that is the value of the `ThumbUrl` field. |


>2.X and 3.X versions of IM SDK (for Android, iOS, Mac, and Windows) send video message elements in the following format:
>```
{
    "MsgType": "TIMVideoFileElem",
    "MsgContent": {
        "VideoUUID": "1400123456_dramon_34ca36be7dd214dc50a49238ef80a6b5",//The serial number of the video in String type. This is the key value the backend uses to index videos. The video cannot be downloaded through this field. To obtain the video, upgrade the IM SDK to 4.X version.
        "VideoSize": 1194603, //The size of video data in bytes, in Number type.
        "VideoSecond": 5,     //The video duration in seconds, in Number type.
        "VideoFormat": "mp4", //The video format in String type, such as mp4.
        "ThumbUUID": "1400123456_dramon_893f5a7a4872676ae142c08acd49c18a",//The serial number of the video thumbnail in String type. This is the key value the backend uses to index video thumbnails. The video thumbnail cannot be downloaded through this field. To obtain the video thumbnail, upgrade the IM SDK to 4.X version.
        "ThumbSize": 13907,   //The size of thumbnail data in bytes, in Number type.
        "ThumbWidth": 720,    //The thumbnail width in Number type.
        "ThumbHeight": 1280,  //The thumbnail height in Number type.
        "ThumbFormat": "JPG"  //The video thumbnail format in String type, such as JPG or BMP.
    }
}

MsgBody Message Content Examples

Single text message element

A single message contains only one text message element. The text content is hello world.

{
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello world"
            }
        }
    ]
}

Combined messages

The following single message contains two text message elements and one emoji message element, in the sequence of text + emoji + text.

{
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello"
            }
        }, 
        {
            "MsgType": "TIMFaceElem", 
            "MsgContent": {
                "Index": 1, 
                "Data": "content"
            }
        }, 
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "world"
            }
        }
    ]
}

A combined message can contain only one TIMCustomElem custom message element, and an unlimited number of other message elements.

Description of Apple Push Notification Service (APNs)

Push notification display format on the client

• Account nickname is not set
  If an account has not set a nickname, APNs only displays text content. For one-to-one chat messages, push text is displayed. For group messages, (group name): push text is displayed.
  

• Account nickname is set
  If an account has set a nickname, for one-to-one chat messages, nickname: push text is displayed. For group messages, nickname (group name): push text is displayed.

• Display format of combined messages
  For combined messages, the text displayed shows the push text of each message element in sequence. The following example shows a one-to-one chat message with an account nickname set, and the push text is helloworld. Note that the text contains no spaces. The backend connects message elements in sequence without adding any extra characters. If spaces or other characters need to be added between different message elements, the caller should take control.

  {
    "MsgBody": [
        {
            "MsgType": "TIMTextElem", 
            "MsgContent": {
                "Text": "hello"  
            }
        },
        {
            "MsgType": "TIMCustomElem",
            "MsgContent": {
                "Data": "message",
                "Desc": "world",
                "Ext": "https://www.example.com",               
                "Sound": "dingdong.aiff"
            }
        }
    ] 
  }
  

  

The following table summarizes the push text of different message elements.

RESTful APIs for the nickname and group name settings

RESTful API for setting the account nickname: Setting the Profile.
RESTful API for setting the group name: Modifying Basic Group Information.

Advanced applications

Customizing push sounds and extended fields delivered by APNs

Use TIMCustomElem to customize message elements. In the Sound field, enter the file name of the custom audio. In the Ext field, enter the delivered extended field, which can be obtained from the Ext field in the APNs payload.

{
    "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"
            }
        }
    ]
}

The received APNs JSON payload is displayed as follows on the client:

{
    "aps":{
        "alert": "Nickname:helloworld",   //The push text of each message element is connected in sequence.
        "badge": 5,                       
        "sound": "dingdong.aiff"         //Corresponds to the `Sound` field in `TIMCustomElem`.
    }, 
    "ext": "www.qq.com"                //Corresponds to the `Ext` field in `TIMCustomElem`.
}

Description of Offline Push OfflinePushInfo

OfflinePushInfo is a JSON object dedicated for configuring offline push. OfflinePushInfo allows you to configure whether to disable push, push text description content, and push passthrough strings for a message. With OfflinePushInfo, you can easily set offline push information, removing the need to encapsulate through TIMCustomElem.

If OfflinePushInfo has been filled in, the offline push settings in TIMCustomElem are ignored. Currently, OfflinePushInfo can work with APNs and the push services of various Android device brands, including Xiaomi, Huawei, MEIZU, OPPO, and Vivo.

The following example shows the format of OfflinePushInfo:

{
    // ...
    "MsgBody": [...] //Same with `MsgBody` in this case
    "OfflinePushInfo": {
        "PushFlag": 0,
        "Title":"This is the push title",
        "Desc": "This is the offline push content",
        "Ext": "This is the passthrough content",
        "AndroidInfo": { 
            "Sound": "android.mp3",
            "OPPOChannelID": "test_OPPO_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.mp3",
            "BadgeMode": 1,
            "Title":"apns title",
            "SubTitle":"apns subtitle",
            "Image":"www.image.com"
        }
    }
}

The preceding fields are described as follows:

The maximum data packet size supported by APNs is 4 KB. Therefore, we recommend that the total size of the Desc and Ext fields does not exceed 3 KB.

References

Apple Push Notification Service (APNs) Apple Push Programming Documentation.
Configuration of iOS offline message push: Offline Push (iOS).