Type of the message.

• 0x01: text
• 0x17: file
• 0x10: location
• 0x80: delivery-receipt
• 0x15: poll-setup
• 0x16: poll-vote

Inner message struct. Needs to be parsed according to the type field. Padded with a random amount from 1 to 255 bytes in PKCS#7 format.

Additionally, for security reasons, the total size of padded-data should be at least 32 bytes, to avoid leaking information about the contents.

Example padding (hex representation):

• 1 byte: 01
• 3 bytes: 030303
• 10 bytes: 0A0A0A0A0A0A0A0A0A0A

To add padding without information leaks, run the following steps:

1. Let data be the data to be padded.
2. Let pad-length be a random number between (inclusive) 1 and 255.
3. If the sum of the byte length of data and pad-length is less than 32, update pad-length so the sum is precisely 32.
4. Let pad-byte be the encoded unsigned 8-bit integer representation of pad-length.
5. Let padded-data be the padded data by adding pad-length trailing pad-byte bytes to data.

To remove padding:

1. Let pad-length be the decoded unsigned 8-bit integer representation of the last byte of padded-data.
2. Let data be the unpadded data by ignoring the trailing pad-length bytes of padded-data.

UTF-8 encoded text.

UTF-8, JSON-encoded object with the following fields:

• Rendering type ('j'):

  • 0: Render as a file.
  • 1: Render as media (e.g. an image, audio or video).
  • 2: Render as a sticker (for transparent images).

  If this field is not set, fall back to the value of 'i'. If no value could be determined or the rendering type is unassigned, assume 0.

• Deprecated ('i'): Set this to the integer 1 if the rendering type is 1 or 2, otherwise set this to the integer 0.

• Encryption key ('k'): Random symmetric key used to encrypt the blobs (file and thumbnail data) in lowercase hex string.

• File blob ID ('b'): Blob ID in lowercase hex string representation to obtain the file data.

• File media type ('m'): The media type of the file.

• File name ('n'): Optional filename of the file.

• File size ('s'): File size in bytes.

• Thumbnail Blob ID ('t'): Optional blob containing the thumbnail file data.

• Thumbnail media type ('p'): Media type of the thumbnail. If not set, assume image/jpeg.

• Caption ('d'): Optional caption text.

• Correlation ID ('c'): Optional random 32 byte ASCII string to collocate multiple media files.

• Metadata ('x'): An optional metadata object as defined below.

Metadata object fields depend on the media type of the file. All fields are optional but recommended to set in order to determine the layout logic while the file is being downloaded. Once the file has been parsed, the parsed data supersedes this object.

For images:

• Width ('w'): The width as an integer in px.
• Height ('h'): The height as an integer in px.
• Animated ('a'): Set this to the boolean true if the image is animated (e.g. an animated GIF).

For audio:

• Duration ('d'): The duration as a float in seconds.

For video:

• Width ('w'): The width as an integer in px.
• Height ('h'): The height as an integer in px.
• Duration ('d'): The duration as a float in seconds.

Note that the rendering logic depends on three key fields which should be set accordingly:

• Media type,
• Rendering type,
• Animated flag in the metadata object.

Location coordinates and meta information encoded in comma- and line-separated UTF-8:

<latitude>,<longitude>[,<accuracy>]

or

<latitude>,<longitude>[,<accuracy>]
<address>

or

<latitude>,<longitude>[,<accuracy>]
<name>
<address>

Values:

• latitude and longitude are the geographic coordinates represented in a WGS-84 string.
• accuracy is the accuracy in meters represented by a floating point number formatted as a string.
• address is a full address. If it contains multiple lines, each line feed must be escaped (literal \n).
• name is the name of a point of interest.

Latitude and longitude must always be present while accuracy is optional and should only be provided when the current location of the device is being sent. These values are comma-separated.

Following values are optional and separated by line feeds (\n). This may be either:

• a single line containing the address representing the closest address matching the coordinates, or
• two lines containing a point of interest name and address (which means that the coordinates refer to the point of interest).

Message status:

• 0x01: Message was received.
• 0x02: Message was read.
• 0x03: Message has been explicitly acknowledged.
• 0x04: Message has been explicitly declined.

The following replacement logic is to be applied on a message's status when displayed:

1. 0x03 or 0x04 replace each other and groups listed below,
2. 0x02 replaces groups listed below,
3. 0x01 replaces the unlisted created status.

One or more message-ids whose status should be updated.

Random unique (per creator within this conversation) ID of the poll.

UTF-8, JSON-encoded object with the following fields:

• Description ('d'): A short description/topic string for the poll.

• State ('s'):

  • 0: Poll is open for votes.
  • 1: Poll has been closed.

  A state transition from closed to open is illegal and must be ignored by the receiving client.

• Answer type ('a'):

  • 0: Single choice poll.
  • 1: Multiple choice poll.

  Any transition from one of the types to another is illegal and must be ignored by the receiving client.

• Announce type ('t'):

  • 0: Announce votes in form of the poll-vote message only to the creator of the ballot. Results are invisible until the creator closes the vote and reports the final results.
  • 1: Announce votes in form of the poll-vote message to everyone in the conversation. Interim results are therefore visible to everyone.

  Any transition from one of the types to another is illegal and must be ignored by the receiving client.

• Display mode ('u'):

  • 0: List mode. List choices of all participants as presented by this message.
  • 1: Summary mode. Only display the total amount of votes per choice and the user's vote (if any).

  If the field is not present, assume list mode (0). Any transition from one of the modes to another is illegal and must be ignored by the receiving client.

• Choices type ('o', DEPRECATED): Always set this to the integer 0.

• Participants ('p'): A list of Threema IDs that participated in the poll (i.e. they cast a vote). This field must only be present if the poll is being closed. In display mode summary, this field should be an empty list and must be ignored by the receiver.

• Choices ('c'): A list of choice objects as defined below.

Choice object fields:

• Choice ID ('i'): A per-poll unique ID of the choice in form of an integer. Used when casting a vote.
• Description ('n'): Choice description in form of a string.
• Sort key ('o', DEPRECATED): Set this to the index of the choice object within the choices list.
• Participant votes ('r'): A list of indices referring to the index of the participant (as defined in the participants list) that cast a vote for this choice. This field must only be present if the poll is being closed. In display mode summary this should be an empty list and must be ignored by the receiver.
• Total amount of votes ('t'): The total amount of votes for this choice. This field must only be present if the poll is being closed. In display mode normal this field should not be present and must be ignored by the receiver.

ID of the associated poll.

The Threema ID of the creator of the poll.

UTF-8, JSON-encoded list containing one or more choice tuples. Each choice tuple contains the following two integer values:

• Choice ID, referring to the Choice ID defined in the poll-setup message.
• Selected:
  • 0: The choice has not been selected.
  • 1: The choice has been selected.

Note: For protocol simplicity, a vote must always include all possible choices, whether or not they have been selected.