.. _x-acro-filetransfer:

====================
File Transfer Format
====================

.. contents::
   :local:
   :depth: 3

Overview
~~~~~~~~

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

Format
~~~~~~~

.. code-block:: 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.

	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 :ref:`here <decryption>`.

	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 :ref:`here <decryption>`.

	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.