Message Formats

Last updated: 2021-09-23 17:48:05

    MsgBody

    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": {}
    }
    
    Field Type Description
    MsgType String The type of the message element. Currently, these message objects are supported: TIMTextElem (text message), TIMLocationElem (location message), TIMFaceElem (emoji message), TIMCustomElem (custom message), TIMSoundElem (audio message), TIMImageElem (image message), TIMFileElem (file message), and TIMVideoFileElem (video message).
    MsgContent Object The content of the message element. Each MsgType has its own MsgContent format. For more information, see below.

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

    Value of MsgType Type
    TIMTextElem Text
    TIMLocationElem Geographic location
    TIMFaceElem Emoji
    TIMCustomElem Custom. When the receiver is an iOS device and the app is working in the background, this type of message provides fields other than text to APNs. A combined message can contain only one TIMCustomElem custom message element.
    TIMSoundElem Voice
    TIMImageElem Image
    TIMFileElem File
    TIMVideoFileElem Video
    Note:

    Messages of the above types can be sent by server-side integrated RESTful APIs.

    TIMMsgElement

    Text message element

    {
      "MsgType": "TIMTextElem",
      "MsgContent": {
          "Text": "hello world"
      }
    }
    
    Field Type Description
    Text String Content of the message. When the receiver is an iOS or Android device and the app is working in the background, messages of this type are displayed as offline push text.

    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
      }
    }
    
    Field Type Description
    Desc String Description of the location
    Latitude Number Latitude
    Longitude Number Longitude

    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"
      }
    }
    
    Field Type Description
    Index Number Emoji index customized by users
    Data String Additional data

    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.

    Note

    When a message contains only one TIMCustomElem custom message element, if both the Desc and OfflinePushInfo.Desc fields are not entered, the offline push of the message will not be received, unless the OfflinePushInfo.Desc field is entered.

    Custom message element

    {
      "MsgType": "TIMCustomElem", 
      "MsgContent": {
          "Data": "message", 
          "Desc": "notification", 
          "Ext": "url", 
          "Sound": "dingdong.aiff"
      }
    }
    
    Field Type Description
    Data String Custom message data. This field is not delivered as a payload field by APNs, and therefore the data field cannot be obtained in payload.
    Desc String Custom message description. When the receiver is an iOS or Android device, and the application is working in the background, the offline push text is displayed.
    If a custom message is sent with the OfflinePushInfo.Desc field set, the field will be overwritten; therefore, please enter the OfflinePushInfo.Desc field first.
    Note

    When a message contains only one TIMCustomElem custom message element, if both the Desc and OfflinePushInfo.Desc fields are not entered, the offline push of the message will not be received, unless the OfflinePushInfo.Desc field is entered.

    Ext String Extended field. When the receiver is an iOS or Android device and the app is working in the background, this field is delivered as an Ext key value in APNs request packet payloads. The protocol format of Ext is defined by the business end, the APNs is only responsible for passthrough.
    Sound String Custom APNs push ringtone

    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.

    Voice message element

    Note:

    To send voice messages through server-side integrated RESTful APIs, you need to fill in voice URLs through which the voices can be downloaded. The Download_Flag field must be set to 2.

    4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send voice 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
       }
    }
    
    Field Type Description
    Url String Voice download URL, through which the voice content can be downloaded directly.
    Size Number Voice data size, in bytes.
    Second Number Voice duration, in seconds.
    Download_Flag Number Flag of the voice download method. Currently, the value of Download_Flag must be 2, which means that the voice content can be downloaded from the URL specified by the Url field.
    Note:

    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", //Serial number of the voice in String type. This is the key value the backend uses to index the voice. The voice cannot be downloaded through this field. To obtain the voice, upgrade the IM SDK to 4.X versions.
           "Size": 62351,        //Voice data size in bytes, in Number type.
           "Second": 1         //Voice duration in seconds, in Number type.
       }
    }
    

    Image message element

    Note:

    To send image messages through server-side integrated RESTful APIs, you need to fill in image URLs through which the images can be downloaded. The UUID field must be set to a globally unique string value, usually the MD5 value of the image. IM SDK will deliver the value to the message receiver through the message object V2TIMImageElem.V2TIMImage, and service apps can use this field to distinguish images.

    {
      "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"
              }
          ]
      }
    }
    
    Field Type Description
    UUID String Serial number of the image, which is the key value the backend uses to index the image.
    ImageFormat Number Image format. JPG = 1, GIF = 2, PNG = 3, BMP = 4, Others = 255.
    ImageInfoArray Array Download information of the original image, thumbnail, or large image.
    Type Number Image type. 1: original image, 2: large image, 3: thumbnail.
    Size Number Size of image data in bytes.
    Width Number Image width.
    Height Number Image height.
    URL String Download URL of the image.

    File message element

    Note:

    To send file messages through server-side integrated RESTful APIs, you need to fill in file URLs through which the files can be downloaded. The Download_Flag field must be set to 2.

    4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send file message elements 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
       }
    }
    
    Field Type Description
    Url String Download URL of the file, through which the file can be downloaded directly.
    FileSize Number Size of file data in bytes.
    fileName String File name.
    Download_Flag Number Flag of the file download method. Currently, the value of Download_Flag must be 2, which means that the file can be downloaded from the URL specified by the Url field.
    Note:

    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", //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 versions.
    >  "FileSize": 1773552, //Size of file data in bytes, in Number type.
    >  "FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV" //File name in String type.
    }
    }
    >

    Video message element

    Note:

    To send video messages through server-side integrated RESTful APIs, you need to fill in file URLs through which the videos can be downloaded. The VideoDownloadFlag and ThumbDownloadFlag fields must be set to 2.

    4.X versions of IM SDK (for Android, iOS, Mac, and Windows) send video message elements 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 Download URL of the video, through which the video can be downloaded directly.
    VideoSize Number Size of video data, in bytes.
    VideoSecond Number Video duration, in seconds.
    VideoFormat String Video format, for example, MP4.
    VideoDownloadFlag Number 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 specified by the VideoUrl field.
    ThumbUrl String Download URL of the video thumbnail, through which the video thumbnail can be downloaded directly.
    ThumbSize Number Size of thumbnail data, in bytes.
    ThumbWidth Number Thumbnail width.
    ThumbHeight Number Thumbnail height.
    ThumbFormat String Video thumbnail format, such as JPG or BMP.
    ThumbDownloadFlag Number 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 specified by the ThumbUrl field.
    Note:

    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",//Serial number of the video in String type. This is the key value the backend uses to index the video. The video cannot be downloaded through this field. To obtain the video, upgrade the IM SDK to 4.X versions.
    >  "VideoSize": 1194603, //Size of video data in bytes, in Number type.
    >  "VideoSecond": 5,     //Video duration in seconds, in Number type.
    >    "VideoFormat": "mp4", //Video format in String type, for example, MP4.
    >    "ThumbUUID": "1400123456_dramon_893f5a7a4872676ae142c08acd49c18a",//Serial number of the video thumbnail in String type. This is the key value the backend uses to index the video thumbnail. The video thumbnail cannot be downloaded through this field. To obtain the video thumbnail, upgrade the IM SDK to 4.X versions.
    >    "ThumbSize": 13907,   //Size of thumbnail data in bytes, in Number type.
    >    "ThumbWidth": 720,    //Thumbnail width in Number type.
    >    "ThumbHeight": 1280,  //Thumbnail height in Number type.
    >    "ThumbFormat": "JPG"  //Video thumbnail format in String type, such as JPG or BMP.
    }
    }
    >

    MsgBody Examples

    Single text element message

    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"
               }
           }
       ]
    }
    
    Note:

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

    Description of Custom Message Data CloudCustomData

    Each message can carry custom data CloudCustomData.

    CloudCustomData is saved in the cloud together with the MsgBody of the message. It will be sent to the opposite end and can still be pulled after the program is uninstalled and reinstalled.

    The following example shows the formats of CloudCustomData and MsgBody:

    {
       "MsgBody": [
           {
               "MsgType": "TIMTextElem", 
               "MsgContent": {
                   "Text": "hello"
               }
           }
       ],
       "CloudCustomData": "your cloud custom data"
    }
    

    Message Formats for Apple Push Notification Service (APNs)

    Push notification display format on the client

    • Account without a nickname
      For an account without a nickname, APNs displays only text content: push text for one-to-one chat messages, and (group name): push text for group messages.

    • Account with a nickname
      For an account with a nickname, APNs displays nickname: push text for one-to-one chat messages, and nickname (group name): push text for group messages.

    • 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.

    Value of MsgType Type Push Text of the Message Element
    TIMTextElem Text Text field.
    TIMLocationElem Location Offline push text is [Location] for the English version.
    TIMFaceElem Emoji Offline push text is [Face] for the English version.
    TIMCustomElem Custom Desc field.

    RESTful APIs for 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 apps

    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",   //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`
    }
    

    OfflinePushInfo

    OfflinePushInfo is a JSON object dedicated for configuring offline push. It 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, eliminating the need to encapsulate through TIMCustomElem.

    Note:

    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 Mi, 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",
        "VIVOClassification": 1
          },
          "ApnsInfo": {
              "Sound": "apns.mp3",
              "BadgeMode": 1,
              "Title":"apns title",
              "SubTitle":"apns subtitle",
              "Image":"www.image.com",
              "MutableContent": 1
          }
      }
    }
    

    The fields are described as follows:

    Field Type Property Description
    PushFlag Integer Optional 0: enable push, 1: disable offline push.
    Title String Optional Offline push title. This field is applicable to both iOS and Android.
    Desc String Optional Offline push content. This field overwrites the offline push display text of the TIMMsgElement elements mentioned above.
    If the message sent has only one TIMCustomElem element, this Desc field will overwrite the Desc field in the TIMCustomElem. If neither of the Desc fields is filled in, the offline push notification for the message will not be received.
    Ext String Optional Passthrough content of offline push. To make sure the offline push of all Android vendors are attainable, this field must be in JSON format.
    AndroidInfo.Sound String Optional Path to the offline push sound file in Android.
    AndroidInfo.HuaWeiChannelID String Optional Notification channel field for Huawei phones with EMUI 10.0 or above. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
    AndroidInfo.XiaoMiChannelID String Optional Notification type (Channel) adaptation field for Mi phones with MIUI 10 or above. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
    AndroidInfo.OPPOChannelID String Optional NotificationChannel notification adaptation field for OPPO phones with Android 8.0 or above. When this field is not empty, it will overwrite the ChannelID value configured in the console; otherwise, it will not.
    AndroidInfo.GoogleChannelID String Optional Notification channel field for Google mobile phones with Android 8.0 or later. This field is supported by the new Google push API (uploading the certificate file) but not the old API (entering the server key).
    AndroidInfo.VIVOClassification Integer Optional Push message classification for Vivo phones. Valid values: 0: operation message; 1: system message (default value).
    AndroidInfo.HuaWeiImportance String Optional Push notification message classification for Huawei phones. Valid values: LOW, NORMAL (default value).
    AndroidInfo.ExtAsHuaweiIntentParam Integer Optional After Huawei Push is configured to Open specified in-app page in the console, "1" indicates to use the passthrough content Ext as the Intent parameter, while "0" (default value) indicates to use the passthrough content Ext as the Action parameter. For the differences between the two parameters, see Guides.
    ApnsInfo.BadgeMode Integer Optional The default value or 0 indicates that counting is required. 1 indicates that counting is not required for this message, in which case the number in the upper-right icon does not increase.
    ApnsInfo.Title String Optional Title of an APNs push message. The top-level title is replaced when this field is filled in.
    ApnsInfo.SubTitle String Optional Subtitle of an APNs push message.
    ApnsInfo.Image String Optional Image URL carried by APNs. When the client obtains this field, it displays the image in a pop-up window by downloading the image through the URL.
    ApnsInfo.MutableContent Integer Optional Valid values: 1: enable the push extension of iOS 10; 0 (default value).
    Note:

    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

    APNs development documentation
    Configuring iOS offline message push.