package sync

Get desktop application:
View/edit binary Protocol Buffers messages

Threema contact.

Used in: d2d.ContactSync.Create, d2d.ContactSync.Update, join.EssentialData.AugmentedContact

• string identity = 1

  Threema ID of the contact Always required.

• optional bytes public_key = 2

  Public key of the contact Required towards a new device and for a new contact. Should not be set for existing contacts and must be ignored (a public key for an identity cannot be changed).

• optional uint64 created_at = 3

  Unix-ish timestamp in milliseconds when the contact has been created (added) locally. Required towards a new device and for a new contact. Optional for an existing contact.

• optional string first_name = 4

  First name of the contact Always optional. An empty string is valid. When both `first_name` and `last_name` are empty string, the `nickname` should be used as display name.

• optional string last_name = 5

  Last name of the contact Always optional. An empty string is valid. When both `first_name` and `last_name` are empty string, the `nickname` should be used as display name.

• optional string nickname = 6

  Nickname of the contact (without `~` prefix) Always optional. An empty string is valid. If `first_name`, `last_name` and `nickname` are empty string, the Threema ID should be used as display name.

• optional Contact.VerificationLevel verification_level = 7

• optional Contact.WorkVerificationLevel work_verification_level = 21

• optional Contact.IdentityType identity_type = 8

• optional Contact.AcquaintanceLevel acquaintance_level = 9

• optional Contact.ActivityState activity_state = 10

• optional uint64 feature_mask = 18

  Features available for the contact (64 bit mask, `common.CspFeatureMaskFlag` logically or-ed). Required towards a new device and for a new contact. Optional for an existing contact.

• optional Contact.SyncState sync_state = 13

• optional Contact.ReadReceiptPolicyOverride read_receipt_policy_override = 16

• optional Contact.TypingIndicatorPolicyOverride typing_indicator_policy_override = 17

• optional Contact.NotificationTriggerPolicyOverride notification_trigger_policy_override = 19

• optional Contact.NotificationSoundPolicyOverride notification_sound_policy_override = 20

• optional common.DeltaImage contact_defined_profile_picture = 14

  Contact-defined profile picture as received from the contact in a `set-profile-picture` message. Always optional.

• optional common.DeltaImage user_defined_profile_picture = 15

  User-defined profile picture set by the user or imported from the address book. Always optional.

• optional ConversationCategory conversation_category = 11

  Conversation category of the contact Required towards a new device and for a new contact. Optional for an existing contact.

• optional ConversationVisibility conversation_visibility = 12

  Conversation visibility of the contact Required towards a new device and for a new contact. Optional for an existing contact.

Acquaintance level of the contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• DIRECT = 0

  The contact was explicitly added by the user or a 1:1 conversation with the contact has been initiated.

• GROUP_OR_DELETED = 1

  This level covers the following cases: - The contact is part of a group the user is also part of. The contact was not explicitly added and no 1:1 conversation has been initiated. - The contact was part of a group the user was/is also part of before but either of them has since been removed from all common groups. - The contact has been explicitly removed by the user. The protocol refers to contacts with this level as either acquaintance level _group_ or _deleted_. They are interchangeable and there's no semantic difference between them beyond the context in which they are referred to.

Activity state of the contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• ACTIVE = 0

  The ID is active (used recently and not deleted).

• INACTIVE = 1

  The ID has not been used for a prolonged time (typically 3 months) and may have been abandoned. Such IDs can be marked as "inactive" in the client's contact database, and the user may be alerted to the fact that messages to this ID may not arrive (e.g. alert box, gray color in contact list etc.). An inactive ID can become active again at any time, so the client should keep checking it.

• INVALID = 2

  ID has never been assigned, or it has been permanently deleted. Such IDs should be marked as "deleted" in the client's contact database, and no further messages should be sent or received from them. Since deletion is permanent, once an ID has been reported as invalid by the server, it should not be checked again in the future.

Identity type of the contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• REGULAR = 0

  Regular contact (uses the regular Threema app)

• WORK = 1

  Work contact (uses the Threema work app)

Notification sound policy for the contact Required towards a new device and for a new contact. Optional for an existing contact. Custom sounds are not reflected but are to be (re-)applied in case the policy is _default_.

Used in: Contact

• oneof override

  • common.Unit default = 1

    Apply the notification sound policy specified in the settings (i.e. always emit a sound when notifying of a _conversation_ message).

  • NotificationSoundPolicy policy = 2

    Apply the following notification sound policy

Notification trigger policy for the contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• oneof override

  • common.Unit default = 1

    Apply the trigger policy specified in the settings (i.e. trigger on every _conversation_ message).

  • NotificationTriggerPolicyOverride.Policy policy = 2

    Apply the following notification trigger policy

Used in: NotificationTriggerPolicyOverride

• Policy.NotificationTriggerPolicy policy = 1

• optional uint64 expires_at = 2

  Unix-ish timestamp in milliseconds when the provided policy should expire and fall back to the default. If not provided, the policy does not expire.

Apply the following notification trigger policy

Used in: Policy

• NEVER = 0

  Never trigger a notification message.

_Read_ receipt policy override for this contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• oneof override

  • common.Unit default = 1

    Apply the _read_ receipt policy specified in the settings

  • ReadReceiptPolicy policy = 2

    Apply the following _read_ receipt policy

Contact synchronisation state Required towards a new device and for a new contact. Optional for an existing contact. These states are strict monotonic. When a downgrade is being detected, log the incident and ignore the update.

Used in: Contact

• INITIAL = 0

  The contact data has not been imported and has not been edited by the user either.

• IMPORTED = 1

  The contact data has been imported (e.g. via a local address book and an identity link). In this state, subsequent contact synchronisations must not alter the contact's data.

• CUSTOM = 2

  The contact data has been edited by the user. In this state, subsequent contact synchronisations must not alter the contact's data.

Typing indicator policy override for this contact Required towards a new device and for a new contact. Optional for an existing contact.

Used in: Contact

• oneof override

  • common.Unit default = 1

    Apply the typing indicator policy specified in the settings

  • TypingIndicatorPolicy policy = 2

    Apply the following typing indicator policy

Verification level of the contact Required towards a new device and for a new contact. Optional for an existing contact. Note: When applying logic depending on the verification level, a `WorkVerificationLevel` of `WORK_SUBSCRIPTION_VERIFIED` virtually raises the verification level to `SERVER_VERIFIED`. However, the contact verification level takes precedence if it is `FULLY_VERIFIED`.

Used in: Contact

• UNVERIFIED = 0

  Unverified, public key has been obtained from the server

• SERVER_VERIFIED = 1

  Verified with one of the account links via the server, or the contact has been obtained via the Work API.

• FULLY_VERIFIED = 2

  Verified, public key has been obtained via a secure channel

Threema Work verification level of the contact. Required towards a new device and for a new contact. Optional for an existing contact. Note: When not using a Threema Work client, the Threema Work verification level must always be `NONE`.

Used in: Contact

• NONE = 0

  The user does not use Threema Work or the contact is not in the same Threema Work subscription.

• WORK_SUBSCRIPTION_VERIFIED = 1

  The contact is in the same Threema Work subscription.

Category of a conversation.

Used in: Contact, DistributionList, Group

• DEFAULT = 0

  No specific (default) category

• PROTECTED = 1

  Protected conversation (_private chat_)

Visibility of a conversation.

Used in: Contact, DistributionList, Group

• NORMAL = 0

  Appears normally in the list of conversations

• PINNED = 2

  Appears pinned in the list of conversations

• ARCHIVED = 1

  Appears in the archived list of conversations

Threema contacts associated to a distribution list.

Used in: d2d.DistributionListSync.Create, d2d.DistributionListSync.Update, join.EssentialData.AugmentedDistributionList

• fixed64 distribution_list_id = 1

  Unique ID of the distribution list Always required.

• optional string name = 2

  Name of the distribution list Required towards a new device and for a new distribution list. Optional for an existing distribution list. An empty string is valid. In such a case, the display name of the distribution list is the list of its members.

• optional uint64 created_at = 3

  Unix-ish timestamp in milliseconds when the group has been created Required towards a new device and for a new distribution list. Optional for an existing distribution list.

• optional common.Identities member_identities = 6

  Distribution list members Required towards a new device and for a new distribution list. Optional for an existing distribution list. An empty list is **not** valid. Clearing all members should be prevented by the UI.

• optional ConversationCategory conversation_category = 4

  Conversation category of the distribution list Required towards a new device and for a new distribution list. Optional for an existing distribution list.

• optional ConversationVisibility conversation_visibility = 5

  Conversation visibility of the distribution list Required towards a new device and for a new distribution list. Optional for an existing distribution list.

Threema contacts associated to a group.

Used in: d2d.GroupSync.Create, d2d.GroupSync.Update, join.EssentialData.AugmentedGroup

• optional common.GroupIdentity group_identity = 1

  Unique group identity Always required.

• optional string name = 2

  Name of the group Required towards a new device and for a new group. Optional for an existing group. An empty string is valid. In such a case, the display name of the group is the list of its members.

• optional uint64 created_at = 3

  Unix-ish timestamp in milliseconds when the group has been created locally Required towards a new device and for a new group. Optional for an existing group.

• optional Group.UserState user_state = 6

• optional common.DeltaImage profile_picture = 7

  Group's profile picture as received from the group's creator Always optional.

• optional common.Identities member_identities = 8

  Group members (**NOT** including the creator and the user itself) Required towards a new device and for a new group. Optional for an existing group. The concrete semantic of this list depends on the current `user_state`: - `MEMBER`: It contains a list of all **current** group members (with the user itself implicitly added). - `KICKED`/`LEFT`: It contains a list of all **previous** group members up to that event. If the list is empty, the group must not be visible in the UI. An empty list is valid.

• optional Group.NotificationTriggerPolicyOverride notification_trigger_policy_override = 9

• optional Group.NotificationSoundPolicyOverride notification_sound_policy_override = 10

• optional ConversationCategory conversation_category = 4

  Conversation category of the group Required towards a new device and for a new group. Optional for an existing group.

• optional ConversationVisibility conversation_visibility = 5

  Conversation visibility of the group Required towards a new device and for a new group. Optional for an existing group.

Notification sound policy for the group Required towards a new device and for a new group. Optional for an existing group. Custom sounds are not reflected but are to be (re-)applied in case the policy is _default_.

Used in: Group

• oneof override

  • common.Unit default = 1

    Apply the notification sound policy specified in the settings (i.e. always emit a sound when notifying of a _conversation_ message).

  • NotificationSoundPolicy policy = 2

    Apply the following notification sound policy

Notification trigger policy for the group Required towards a new device and for a new group. Optional for an existing group.

Used in: Group

• oneof override

  • common.Unit default = 1

    Apply the trigger policy specified in the settings (i.e. trigger on every _conversation_ message).

  • NotificationTriggerPolicyOverride.Policy policy = 2

    Apply the following notification trigger policy

Used in: NotificationTriggerPolicyOverride

• Policy.NotificationTriggerPolicy policy = 1

• optional uint64 expires_at = 2

  Unix-ish timestamp in milliseconds when the provided policy should expire and fall back to the default. If not provided, the policy does not expire.

Apply the following notification trigger policy

Used in: Policy

• MENTIONED = 0

  Only trigger a notification if mentioned in a _conversation_ message.

• NEVER = 1

  Never trigger a notification message.

The user's state within the group Required towards a new device and for a new group. Optional for an existing group.

Used in: Group

• MEMBER = 0

  The user is a member (or creator) of the group.

• KICKED = 1

  The user has been kicked from the group. Implies that the group has been marked as _left_.

• LEFT = 2

  The user left the group. Implies that the group has been marked as _left_. If the user is the creator, this implies that the group has been disbanded.

Application configuration parameters shared across Threema Work devices. See [mdm-parameters.md](./md-parameters.md) for documentation of possible parameter values and associated steps to apply when a parameter has been set for the first time, modified, or removed. Note: MDM parameters are always transmitted fully, not as delta updates.

Used in: d2d.MdmParameterSync.Update, join.EssentialData

• map<string, MdmParameters.Parameter> external_parameters = 1

  A map of MDM parameters, originating from an external MDM system. The map key is the identifier of the MDM parameter (e.g. `th_nickname`).

• map<string, MdmParameters.Parameter> threema_parameters = 2

  A map of MDM parameters, originating from Threema App Configuration. The map key is the identifier of the MDM parameter (e.g. `th_nickname`).

• MdmParameters.ParameterPrecedence parameter_precedence = 3

  The parameter precedence defines how to resolve conflicting parameters between an external MDM and the Threema App Configuration.

A single MDM parameter.

Used in: MdmParameters

• oneof value

  • string string_value = 1

    String parameter

  • uint64 integer_value = 3

    Integer parameter

  • bool boolean_value = 2

    Boolean parameter

Used in: MdmParameters

• THREEMA = 0

  On conflict, parameters defined by Threema App Configuration take precedence

• EXTERNAL = 1

  On conflict, parameters defined by an external MDM take precedence

Notification sound policy.

Used in: Contact.NotificationSoundPolicyOverride, Group.NotificationSoundPolicyOverride

• MUTED = 0

  Do not emit a sound when notifying of a _conversation_ message.

_Read_ receipt policy (when an unread message has been read)

Used in: Contact.ReadReceiptPolicyOverride, Settings

• SEND_READ_RECEIPT = 0

  Send _read_ receipt when an unread message has been read

• DONT_SEND_READ_RECEIPT = 1

  Don't send _read_ receipts

App settings When the user changes one or more settings: 1. Begin a transaction (scope: `SETTINGS_SYNC`, precondition: none). 2. For each setting that has been modified, run the associated steps of the setting and include the modified settings. 3. Reflect this message and commit the transaction. 4. Apply the modified settings locally. When reflected from another device: 1. For each setting that is being included by this message, run the associated steps of the setting and apply the modified setting.

Used in: d2d.SettingsSync.Update, join.EssentialData

• optional Settings.ContactSyncPolicy contact_sync_policy = 1

• optional Settings.UnknownContactPolicy unknown_contact_policy = 2

• optional ReadReceiptPolicy read_receipt_policy = 3

  _Read_ receipt policy (when an unread message has been read) Required towards a new device. Optional otherwise.

• optional TypingIndicatorPolicy typing_indicator_policy = 4

  Typing indicator policy (signal _currently typing_) Required towards a new device. Optional otherwise.

• optional Settings.O2oCallPolicy o2o_call_policy = 5

• optional Settings.O2oCallConnectionPolicy o2o_call_connection_policy = 6

• optional Settings.O2oCallVideoPolicy o2o_call_video_policy = 12

• optional Settings.GroupCallPolicy group_call_policy = 11

• optional Settings.ScreenshotPolicy screenshot_policy = 7

• optional Settings.KeyboardDataCollectionPolicy keyboard_data_collection_policy = 8

• optional common.Identities blocked_identities = 9

  List of Threema IDs whose messages are blocked Required towards a new device. Optional otherwise. An empty list is valid.

• optional common.Identities exclude_from_sync_identities = 10

  Threema IDs to be excluded when syncing the contact list Required towards a new device. Optional otherwise. An empty list is valid.

Contact synchronisation policy Required towards a new device. Optional otherwise.

Used in: Settings

• NOT_SYNCED = 0

  Not synced

• SYNC = 1

  Synced

Threema Group Call policy Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_GROUP_CALL = 0

  Allow creating/receiving Threema Group Calls

• DENY_GROUP_CALL = 1

  Denied from creating/receiving any Threema Group Calls

Keyboard data collection policy (e.g. for personalised suggestions) Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_DATA_COLLECTION = 0

  Allow keyboard input data to be collected

• DENY_DATA_COLLECTION = 1

  Deny collecting of keyboard input data

Threema 1:1 Call connection policy. Required towards a new device. Optional otherwise. Note: This is only relevant for 1:1 calls.

Used in: Settings

• ALLOW_DIRECT_CONNECTION = 0

  Allow direct (peer-to-peer) connections for Threema 1:1 Calls

• REQUIRE_RELAYED_CONNECTION = 1

  Require relayed connections for Threema 1:1 Calls

Threema 1:1 Call policy Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_O2O_CALL = 0

  Allow creating/receiving Threema 1:1 Calls

• DENY_O2O_CALL = 1

  Denied from creating/receiving any Threema 1:1 Calls

Threema 1:1 Call video (stream) policy. Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_VIDEO = 0

  Allow sending and receiving video streams in Threema 1:1 Calls.

• DENY_VIDEO = 1

  Reject and don't send video streams in Threema 1:1 Calls.

Screenshot policy Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_SCREENSHOT = 0

  Allow taking screenshots

• DENY_SCREENSHOT = 1

  Deny taking screenshots, if possible

Unknown contacts policy Required towards a new device. Optional otherwise.

Used in: Settings

• ALLOW_UNKNOWN = 0

  Allowed to contact the user

• BLOCK_UNKNOWN = 1

  Will be blocked by the user

Threema Work credentials for authentication towards Work APIs.

Used in: join.EssentialData

• string username = 1

  Work username.

• string password = 2

  Work password.

Typing indicator policy (signal _currently typing_)

Used in: Contact.TypingIndicatorPolicyOverride, Settings

• SEND_TYPING_INDICATOR = 0

  Send _typing_ indicator when a message is being composed

• DONT_SEND_TYPING_INDICATOR = 1

  Don't send _typing_ indicators

The user's profile.

Used in: d2d.UserProfileSync.Update, join.EssentialData

• optional string nickname = 1

  Nickname Required towards a new device. Optional otherwise. When the user cleared its nickname, send an empty string. Do not send the user's Threema ID (i.e. process data). When an empty string was received, store the empty string as-is and fall back to the users Threema ID when sending an end-to-end encrypted message.

• optional common.DeltaImage profile_picture = 2

  Profile picture Always optional.

• optional UserProfile.ProfilePictureShareWith profile_picture_share_with = 3

• optional UserProfile.IdentityLinks identity_links = 4

External entities linked with the identity Required towards a new device. Optional otherwise. When the user has cleared all of its identity links, this message is present but `links` contains zero items.

Used in: UserProfile

• repeated IdentityLinks.IdentityLink links = 1

  List of identity links

Threema ID link.

Used in: IdentityLinks

• oneof type

  Identity link type

  • string phone_number = 1

    Linked with a verified telephone number (E.164 format without leading `+`)

  • string email = 2

    Linked with a verified email address

• string description = 3

  Identity link description

Profile picture share policy Required towards a new device. Optional otherwise.

Used in: UserProfile

• oneof policy

  • common.Unit nobody = 1

    Don't share

  • common.Unit everyone = 2

    Share with everyone

  • common.Identities allow_list = 3

    Share only with explicitly listed contacts When the user selected _allow list_ but did not select any contacts, send an empty list. Do not fall back to `nobody`.