package d2d

Get desktop application:
View/edit binary Protocol Buffers messages

Contact synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • ContactSync.Create create = 1

    Create a Threema contact

  • ContactSync.Update update = 2

    Update a Threema contact

Create a Threema contact.

Used in: ContactSync

• optional sync.Contact contact = 1

Update a Threema contact.

Used in: ContactSync

• optional sync.Contact contact = 1

Unique conversation identifier.

Used in: IncomingMessageUpdate.Update, OutgoingMessage, OutgoingMessageUpdate.Update

• oneof id

  A contact's Threema ID, distribution list ID or group identity to identify the conversation.

  • string contact = 1

  • fixed64 distribution_list = 2

  • common.GroupIdentity group = 3

Metadata about a device, determined by the device itself.

• bytes padding = 1

  Random amount of padding, ignored by the receiver

• DeviceInfo.Platform platform = 2

• string platform_details = 3

  Platform details (smartphone model / browser), e.g. "Firefox 91.0.2" or "iPhone 11 Pro"

• string app_version = 4

  App version, e.g. "4.52" (Android) or "4.6.12b2653" (iOS)

• string label = 5

  User defined device label (e.g. "PC at Work"), may be empty if not set. Recommended to not not exceed 64 grapheme clusters.

Platform

Used in: DeviceInfo

• UNSPECIFIED = 0

  Unknown platform

• ANDROID = 1

  Android

• IOS = 2

  Apple iOS

• DESKTOP = 3

  Desktop application

• WEB = 4

  Web application

Distribution list synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • DistributionListSync.Create create = 1

    Create a distribution list

  • DistributionListSync.Update update = 2

    Update a distribution list

  • DistributionListSync.Delete delete = 3

    Delete a distribution list

Create a distribution list.

Used in: DistributionListSync

• optional sync.DistributionList distribution_list = 1

Delete a distribution list.

Used in: DistributionListSync

• fixed64 distribution_list_id = 1

  Unique ID of the distribution list

Update a distribution list.

Used in: DistributionListSync

• optional sync.DistributionList distribution_list = 1

Root message

• bytes padding = 1

  Random amount of padding, ignored by the receiver

• fixed64 device_id = 13

  Sender device id

• uint32 protocol_version = 3

  D2D (`ProtocolVersion`) the device used when it sent this message. If `0`, assume V0.1 (`0x0001`).

• oneof content

  The enveloped reflected message

  • OutgoingMessage outgoing_message = 2

  • OutgoingMessageUpdate outgoing_message_update = 10

  • IncomingMessage incoming_message = 4

  • IncomingMessageUpdate incoming_message_update = 11

  • UserProfileSync user_profile_sync = 5

  • ContactSync contact_sync = 6

  • GroupSync group_sync = 7

  • DistributionListSync distribution_list_sync = 8

  • SettingsSync settings_sync = 9

  • MdmParameterSync mdm_parameter_sync = 12

Group synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • GroupSync.Create create = 1

    Create a group

  • GroupSync.Update update = 2

    Update a group

  • GroupSync.Delete delete = 3

    Delete a group

Create a group.

Used in: GroupSync

• optional sync.Group group = 1

Delete a group.

Used in: GroupSync

• optional common.GroupIdentity group_identity = 1

  Unique group identity

Update a group. When receiving this variant: 1. Let `current` be a snapshot of the current group state. 2. Persist the update to the group. 3. Let `member-changes` be an empty list. 4. For each `identity`, `state-change` pair of `member_state_changes`: 1. If `state-change` is `ADDED` and `identity` does not exist in `current.members`, add the tuple `identity`, `state-change` to `member-changes`. 2. If `state-change` is `KICKED` or `LEFT` and `identity` does exist in `current.members`, add the tuple `identity`, `state-change` to `member-changes`. 5. Group `member-changes` by their associated `state-change` and add appropriate status messages to the associated conversation.

Used in: GroupSync

• optional sync.Group group = 1

• map<string, Update.MemberStateChange> member_state_changes = 2

  A map of the member identity string to the member state change.

Used in: Update

• ADDED = 0

  The member has been added

• KICKED = 1

  The member has been kicked from the group.

• LEFT = 2

  The member left the group.

An incoming message, reflected to other devices. When sending this message: 1. [...] 2. Set `nonce` to the nonce of `e2e.message-with-metadata` (or `e2e.legacy-message`) that contained the `body` in encrypted form. When receiving this message: 1. Add `nonce` to the CSP nonce storage (discard a nonces that already exist in the nonce storage). 2. If a message with the same `message_id` exists within the associated `conversation`, discard the message and abort these steps. 3. [...]

Used in: Envelope, history.PastIncomingMessage

• string sender_identity = 1

  Sender's Threema ID

• fixed64 message_id = 2

  Unique ID of the enclosed message

• uint64 created_at = 3

  Unix-ish timestamp in milliseconds for when the enclosed message has been created. Note: Take this value from the `csp.payload.legacy-message`/`csp.payload.message-with-metadata-box` that enclosed the message.

• common.CspE2eMessageType type = 5

  Enclosed message's type.

• bytes body = 6

  The message's body, i.e. the unpadded `csp.e2e.container.padded-data`

• bytes nonce = 7

  Nonce the message was encrypted with by the sender (the shared secret derived from the long-term keys). Optional for now, always required in a future version.

Update one or more existing incoming messages.

Used in: Envelope

• repeated IncomingMessageUpdate.Update updates = 1

  Updates

Mark the referred message as read. Note: This may only be used when _read receipts_ have been turned off, i.e. as a replacement for reflecting `delivery-receipt` type _read_ (`0x02`).

Used in: Update

• uint64 at = 1

  Unix-ish timestamp in milliseconds for when the referred message has been read.

Used in: IncomingMessageUpdate

• optional ConversationId conversation = 1

  Conversation ID of the referred message.

• fixed64 message_id = 2

  Unique ID of the referred message

• oneof update

  Update type

  • Read read = 3

    Mark the referred message as read

MDM parameter synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • MdmParameterSync.Update update = 1

Update MDM parameters. When receiving this variant, run the _MDM Merge And Apply Steps_.

Used in: MdmParameterSync

• optional sync.MdmParameters parameters = 1

An outgoing message, reflected to other devices. When sending this message: 1. [...] 2. Set `nonces` to the nonces of the associated CSP `e2e.message-with-metadata` (or `e2e.legacy-message`) messages that contained the `body` in encrypted form.¹ When receiving this message: 1. Add all `nonces` to the CSP nonce storage (discarding any nonces that already exist in the nonce storage). 2. If a message with the same `message_id` exists within the associated `conversation`, discard the message and abort these steps. 3. [...] ¹: For contacts and distribution lists, there will be exactly one nonce. For groups, there will be as many nonces as there are group members minus one.

Used in: Envelope, history.PastOutgoingMessage

• optional ConversationId conversation = 1

  Conversation ID of the enclosed message. Note: If the conversation is of type group, group and group creator id of the enclosed CSP E2E message must match the values of the supplied group identity. Otherwise, the message must be considered invalid.

• fixed64 message_id = 2

  Unique ID of the enclosed message

• optional fixed64 thread_message_id = 6

  Optional thread message ID (the message ID of the last incoming message in the current conversation)

• uint64 created_at = 3

  Unix-ish timestamp in milliseconds for when the enclosed message has been created Note: Take this value from the `csp.payload.legacy-message`/`csp.payload.message-with-metadata-box` that enclosed the message.

• common.CspE2eMessageType type = 4

  Enclosed message's type

• bytes body = 5

  The message's body, i.e. the unpadded `csp.e2e.container.padded-data`

• repeated bytes nonces = 7

  Nonces the message was encrypted with towards each receiver (the shared secret derived from the long-term keys). Optional for now, always required in a future version.

Update one or more existing outgoing messages.

Used in: Envelope

• repeated OutgoingMessageUpdate.Update updates = 1

  Updates

Mark the referred message as sent (acknowledged by the chat server). Note 1: The timestamp of the `reflect-ack`/`reflected` message determines the timestamp for when the referred message has been sent. Note 2: This indicates that the referred message has been successfully stored in the message queue of the server. It does NOT indicate that the referred message has been delivered to the intended receiver.

Used in: Update

(message has no fields)

Used in: OutgoingMessageUpdate

• optional ConversationId conversation = 1

  Conversation ID of the referred message.

• fixed64 message_id = 2

  Unique ID of the referred message

• oneof update

  Update type

  • Sent sent = 3

    Mark the referred message as sent

D2D protocol versions. Note 1: The most significant byte is the major version and the least significant byte is the minor version. Note 2: Once the D2D protocol is more stable, an unknown major version can be interpreted as incompatible. For now, we only have 0.X versions that define in which way they break compatibility.

• UNSPECIFIED = 0

  The version is unspecified.

• V0_1 = 1

  V0.1 Devices using this version use the opportunistic (but problematic) group sync mechanism via pure CSP reflection. D2D group sync reflection was totally underspecified but is partially supported on the receiving side.

• V0_2 = 2

  V0.2 Builds on V0.1 with backwards compatibility to V0.1. Devices using this version use the explicit group sync mechanism via D2D sync reflection. Upon reception, V0.2 devices detecting a reflected message will switch over the version, and: - for V0.1 in combination with a CSP group message, fall back to the backwards compatibility mode and update the group according to the message. - for V0.2+ in combination with a CSP group message, ignore it.

• V0_3 = 3

  V0.3 Builds on V0.2 but removes the backwards compatibility to V0.1. Upon reception, V0.2 devices detecting a reflected message will switch over the version, and: - for V0.1 in combination with a CSP group message, spit out a warning that the group is going to desync. - for V0.2+ in combination with a CSP group message, ignore it.

Settings synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • SettingsSync.Update update = 1

Update settings.

Used in: SettingsSync

• optional sync.Settings settings = 1

Data shared across all devices and transmitted during the handshake.

• bytes padding = 1

  Random amount of padding, ignored by the receiver

• uint32 version = 2

  Current lowest protocol version that must be supported by all devices

A transaction scope. Used in the d2m transaction messages.

• TransactionScope.Scope scope = 1

Used in: TransactionScope

• USER_PROFILE_SYNC = 0

• CONTACT_SYNC = 1

• GROUP_SYNC = 2

• DISTRIBUTION_LIST_SYNC = 3

• SETTINGS_SYNC = 4

• MDM_PARAMETER_SYNC = 5

• NEW_DEVICE_SYNC = 6

User profile synchronisation message.

Used in: Envelope

• oneof action

  Synchronisation type

  • UserProfileSync.Update update = 1

Update the user's profile

Used in: UserProfileSync

• optional sync.UserProfile user_profile = 1