<a id="x-acro-filetransfer"></a>

# File transfer format

## Overview

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

## Format

```json
{
    "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.

| Field | Required | Description |
| --- | --- | --- |
| `content-type` | No | If not present, `image/jpeg` is assumed. |
| `content-url` | Yes | Location from where to download the data. |
| `content-size` | No | Used to decide whether to download the file automatically or let the user start the download explicitly. |
| `filename` | No | If it makes sense to preserve it, for example when sending a named document from the filesystem, set it to the original filename on the sending device. It does not make sense to set it for a photo sent directly from the camera. |
| `encryption-key` | No | Hex-encoded AES128 CTR key. AES192 and AES256 are also supported. If present, the binary data downloaded from `content-url` needs to be decrypted using this key. Example script for decryption is available [here](decryption.md). |
| `hash` | No | CRC32 digest of the decrypted data, or of the downloaded binary data when `encryption-key` is not present. If present, it should be used to verify integrity. Example script for decryption and integrity check is available [here](decryption.md). |
| `preview` | No | 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 a better quality local preview is generated. |

Preview object:

| Field | Required | Description |
| --- | --- | --- |
| `content-type` | No | If not present, `image/jpeg` is assumed. |
| `content` | Yes | BASE64 representation of the preview image. |