File Transfer Format

Overview

If files are attached to a message, a special content type application/x-acro-filetransfer+json is used.

Format

{
        "body" : "Nice pics",
        "attachments" : [
                {
                        "content-type" : "image/jpeg",
                        "content-url" : "https://the.location.of/the/attachment.jpg",
                        "content-size" : 20000,
                        "filename" : "original_filename_if_any.jpg",
                        "description" : "text for the particular attachment - not used so far",
                        "encryption-key" : "0102f03cab.....",
                        "hash" : "12638292",
                        "preview" :
                        {
                                "content-type" : "image/jpeg",
                                "content" : "BASE64"
                        }
                },
                {
                        "..." : " ... another attachment ... "
                }
        ]
}

body

Optional. Text applying to attachment(s)

attachments

The array of individual attachment dictionaries.

content-type

Optional. If not present image/jpeg is assumed.

content-url

Mandatory. It is the location from where to download the data.

content-size

Optional. It is used to decide whether to download the file automatically or let the user start the download explicitly.

filename

Optional. If it makes sense to preserve it e.g. when sending a named document from the filesystem, it should be set to the original filename on the sending device. It does not make sense to set it for e.g. a photo sent directly from the camera.

encryption-key

Optional. It is hex-encoded AES128 CTR key. AES192 and AES256 are also supported. If present, the binary data downloaded from the content-url need to be decrypted using this key. Example script for decription is available here.

hash

Optional. It is CRC32 digest of the decrypted (if encryption-key is present) binary data downloaded from the content-url. If present, it should be used to verify the integrity of the downloaded and decrypted (if encryption-key is present) data. Example script for decription and integrity check is available here.

preview

Optional. If present it’s a very low quality representation of the data to be downloaded. The preview image is used in the GUI until the actual content is downloaded and better quality local preview is generated.

content-type

Optional, if not present, image/jpeg is assumed.

content

Mandatory. It’s a BASE64 representation of the preview image.