Threema App Remote Protocol (ARP)

The protocol used to exchange data between the Threema app and a client (e.g. Threema Web).

Protocol version: 2.2.1

Concepts

Name Description
General Procedures General procedures that need to be followed.
Connection ID The identifier of a specific connection.
Sequence Number The sequence number counter of the underlying transport for incoming/outgoing chunks.
Chunk Cache How messages will be cached as chunks.
Chunk Cache Blacklist Chunks of messages that are blacklisted.
Session Resumption When and how to reconnect a session.
Message Acknowledgement Message acknowledgement requests and how to confirm them.
Message Subscription How to subscribe for messages.

Messages

Type Subtype A→C C→A Summary
create contact

Create a new contact.

create contact

Confirm the created contact.

create distributionList

Create a new distribution list.

create distributionList

Return the created distribution list.

create fileMessage

Send a new file message.

create fileMessage

Confirm that the file message has been stored

create group

Create a new group.

create group

Return the created group.

create textMessage

Send a new text message.

create textMessage

Confirm that the text message has been sent.

delete cleanReceiverConversation

Delete all messages in a conversation.

delete distributionList

Delete a distribution list.

delete group

Leave or delete a group.

delete message

Delete a message.

request ack

Acknowledge (agree or decline) a message.

request avatar

Request the avatar of a receiver.

request batteryStatus

"Deprecated: Request an immediate battery status update and subscribe to updates."

request blob

Request binary content (e.g. a file).

request clientInfo

Request information about the app's device

request connectionAck

Request an immediate chunk acknowledgement.

request contactDetail

Request contact details (e.g. for a system contact).

request conversations

Request the list of conversations and subscribe to updates.

request groupSync

Sync a group.

request keyPersisted

Mark the permanent key as established and the session as persistent.

request messages

Request messages of a conversation and subscribe to updates.

request profile

Request the user's profile and subscribe to updates.

request read

Mark a message as read.

request receivers

Request the list of receivers (e.g. contacts, groups, etc.) and subscribe to updates.

request thumbnail

Request the thumbnail of a specific message.

response avatar

Return the requested contact avatar.

response blob

Return binary content (e.g. a file).

response clientInfo

Return information about the app's device.

response contactDetail

Return the contact details (e.g. system contact).

response conversations

Return the list of conversations.

response messages

Return the list of messages for a specific conversation.

response profile

Return the user's profile.

response receivers

Return the list of receivers (contacts, groups, etc.).

response thumbnail

Return the thumbnail of a specific message.

update alert

Display an alert.

update avatar

Update the low-res avatar of a subscribed receiver avatar.

update batteryStatus

Update the battery status.

update confirm

Confirms an acknowledgement request.

update connectionAck

Acknowledges one or more chunks.

update connectionDisconnect

Indicates that the sending peer is about to close the connection.

update connectionInfo

Send information about the current (and the previous) connection.

update contact

Modify a contact.

update contact

Return a modified contact.

update conversation

Modify a conversation.

update conversation

Update a subscribed conversation.

update distributionList

Modify a distribution list.

update distributionList

Return a modified distribution list.

update group

Modify a group.

update group

Return a modified group.

update messages

Update one or more messages of a conversation.

update profile

Modify the user's profile.

update profile

Update the user's profile.

update receiver

Update a subscribed receiver.

update receivers

Update all subscribed receivers.

update typing

Notify that the contact/user is typing in a specific conversation.

update voipStatus

Update the VoIP status (e.g. when a call has been started).

Models

Model
Audio
Capabilities
Configuration
Connection
Contact
ContactDetails
ContactReceiverAccess
Conversation
DistributionList
DistributionListReceiverAccess
Email
File
Group
GroupReceiverAccess
ImageFormat
Location
MdmRestrictions
Message
MessageEvent
NotificationDnd
NotificationSettings
NotificationSound
Phone
Quote
SystemContact
Thumbnail
Video
VoIP
VoipAborted
VoipFinished
VoipMissed
VoipRejected
VoipRinging
VoipStarted