<p>SimpleX Chat Protocol is a protocol used by SimpleX Chat clients to exchange messages. This protocol relies on lower level SimpleX protocols - SimpleX Messaging Protocol (SMP) and SimpleX Messaging Agent protocol. SimpleX Chat Protocol describes the format of messages and the client operations that should be performed when receiving such messages.</p>
<p>The scope of SimpleX Chat Protocol is application level messages, both for chat functionality, related to the conversations between the clients, and extensible for any other application functions. Currently supported chat functions:</p>
<ul>
<li>direct and group messages,</li>
<li>message replies (quoting), forwarded messages and message deletions,</li>
<li>message attachments: images and files,</li>
<li>creating and managing chat groups,</li>
<li>invitation and signalling for audio/video WebRTC calls.</li>
<p>SimpleX Chat protocol supports two message formats:</p>
<ul>
<li>JSON-based format for chat and application messages.</li>
<li>binary format for sending files or any other binary data.</li>
</ul>
<h3id="json-format-for-chat-and-application-messages"tabindex="-1">JSON format for chat and application messages</h3>
<p>This document uses JTD schemas <ahref="https://www.rfc-editor.org/rfc/rfc8927.html">RFC 8927</a> to define the properties of chat messages, with some additional restrictions on message properties included in metadata member of JTD schemas. In case of any contradiction between JSON examples and JTD schema the latter MUST be considered correct.</p>
<p>Whitespace is used in JSON examples for readability, SimpleX Chat Protocol clients MUST avoid using whitespace when encoding JSON messages.</p>
<p>General message format is defined by this JTD schema:</p>
<p><code>msgId</code> property is a 12 bytes base64url-encoded random message ID that the clients can use to reference the message in the future, e.g. when editing, quoting or deleting it.</p>
<p><code>event</code> property is the type of the message that defines the semantics of the message and the allowed format of <code>params</code> property.</p>
<p><code>params</code> property includes message data, depending on <code>event</code>, as defined below and in <ahref="./simplex-chat.schema.json">JTD schema</a>.</p>
<h3id="binary-format-for-sending-files"tabindex="-1">Binary format for sending files</h3>
<p>SimpleX Chat clients use separate connections to send files using a binary format. File chunk size send in each message MUST NOT be bigger than 15,780 bytes to fit into 16kb (16384 bytes) transport block.</p>
<p>The syntax of each message used to send files is defined by the following ABNF notation:</p>
<p>While users usually use the term "message" to refer to the objects presented in the conversation, the expected functionality of these objects makes it a wrong term. "Messages" are supposed to be immutable; they cannot be modified or deleted once sent. The objects in the conversation are expected to be mutable. This document and implementation use the term "chat item" to refer to these objects to differentiate them from the messages sent between the clients.</p>
<p>JTD schema defining messages for all chat functions is available in <ahref="./simplex-chat.schema.json">this file</a>– please refer to this document for all properties of the message <code>params</code>.</p>
<p>The message is sent as part of the connection request to the long-term user address. <code>contactReqId</code> property is used to identify a duplicate contact request - the receiving client MAY put repeated request on top of the list in the UI.</p>
<h2id="sub-protocol-for-contact-profile"tabindex="-1">Sub-protocol for contact profile</h2>
<p>This message is sent by both sides of the connection during the connection handshake, and can be sent later as well when contact profile is updated.</p>
<h3id="probing-for-duplicate-contacts"tabindex="-1">Probing for duplicate contacts</h3>
<p>As there are no globally unique user identitifiers, when the contact a user is already connected to is added to the group by some other group member, this contact will be added to user's list of contacts as a new contact. To allow merging such contacts, "a probe" (random base64url-encoded 32 bytes) SHOULD be sent to all new members as part of <code>x.info.probe</code> message and, in case there is a contact with the same profile, the hash of the probe MAY be sent to it as part of <code>x.info.probe.check</code> message. In case both the new member and the existing contact are the same user (they would receive both the probe and its hash), the contact would send back the original probe as part of <code>x.info.probe.ok</code> message via the previously existing contact connection – proving to the sender that this new member and the existing contact are the same user, in which case the sender SHOULD merge these two contacts.</p>
<p>Sending clients MAY disable this functionality, and receiving clients MAY ignore probe messages.</p>
<p>If the sending client uses <code>x.info.probe</code> messages, it MUST send them to all new members, rather than only when there is a matching contact profile. This is to avoid leaking information that the matching contact profile exists.</p>
<h2id="sub-protocol-for-content-messages"tabindex="-1">Sub-protocol for content messages</h2>
<h3id="xmsgnew-a-new-content-message"tabindex="-1">x.msg.new - a new content message</h3>
<p>When chat clients receive or send this message, they MUST create a new chat item in the conversation. Top level <code>msgId</code> property is defined to allow referencing this chat item or message in the future, e.g. to delete, update or quote chat item, or to accept file.</p>
<p>This message uses <code>params</code> property of the message as content message container, without any top level properties for the container. Message container (<code>params</code>) includes message <code>content</code> property, an optional "invitation" to receive file or image attachment in <code>file</code> property (that is interpreted depending on message content type) and optional indication whether this message is forwarded (<code>"forward": true</code> property of container) or sent in reply to other message (<code>"quote": {<quoted message>}</code>). See <code>/definition/msgContainer</code> in <ahref="./simplex-chat.schema.json">JTD schema</a> for message container format.</p>
<li><code>text</code> - no file attachment is expected for this format, <code>text</code> property MUST be non-empty.</li>
<li><code>file</code> - attached file is required, <code>text</code> property MAY be empty.</li>
<li><code>image</code> - attached file is required, <code>text</code> property MAY be empty.</li>
<li><code>link</code> - no file attachment is expected, <code>text</code> property MUST be non-empty. <code>preview</code> property contains information about link preview.</li>
<h3id="xmsgupdate-update-of-the-previously-sent-message"tabindex="-1">x.msg.update - update of the previously sent message</h3>
<p>This message is used to update previously created chat item. Its <code>params</code> property contains <code>msgId</code> of the previously sent message that this one is updating and <code>content</code> with the message content that the clients must use to replace the content of the original chat item.</p>
<p>If the referenced message does not exist, the clients MUST create a new chat item with the ID of the referenced message. If the referenced message is not a content message, the clients MUST ignore this message.</p>
<h3id="xmsgdel-request-to-delete-previously-sent-message"tabindex="-1">x.msg.del - request to delete previously sent message</h3>
<p>This message is used to delete previously sent chat items. Receiving clients MUST implement it as soft-delete, replacing the original chat item with a special chat item indicating that "message is deleted" that can be fully deleted by the user. If the referenced message does not exist or was sent by the different user than the one sending <code>x.msg.del</code>, the receiving clients MUST ignore this message. Clients are also RECOMMENDED to limit the time during which message deletion is allowed, both for senders and for the recipients.</p>
<h2id="sub-protocol-for-sending-and-receiving-files"tabindex="-1">Sub-protocol for sending and receiving files</h2>
<p>When content message <code>x.msg.new</code> contains file attachment (the invitation to receive the file), this sub-protocol is used to accept this file or to notify the recipient that sending the file was cancelled.</p>
<p>File attachment can optionally include connection address to receive the file - clients MUST include it when sending files to direct connections, and MUST NOT include it when sending file attachment to the group (as different members would need different connections to receive the file).</p>
<p><code>x.file.acpt</code> message is used to accept the file in case when file connection address was included in the message (that is the case when the file invitation was sent in direct message). It is sent as part of file connection handshake via file connection, that is why this message contains no reference to the file - the used connection provides sufficient context for the sender.</p>
<p><code>x.file.acpt.inv</code> message is used to accept the file in group conversations, it includes the connection address. It is sent in the same connection where the file was offered and must reference the original message.</p>
<p><code>x.file.cancel</code> message is sent to notify the recipient that sending of the file was cancelled. It is sent in response to accepting the file with <code>x.file.acpt.inv</code> message. It is sent in the same connection where the file was offered.</p>
<h2id="sub-protocol-for-chat-groups"tabindex="-1">Sub-protocol for chat groups</h2>
<h3id="decentralized-design-for-chat-groups"tabindex="-1">Decentralized design for chat groups</h3>
<p>SimpleX Chat groups are fully decentralized and do not have any globally unique group identifiers - they are only defined on client devices as a group profile and a set of bi-directional SimpleX connections with other group members. When a new member accepts group invitation, the inviting member introduces a new member to all existing members and forwards the connection addresses so that they can establish direct and group member connections.</p>
<p>There is a possibility of the attack here: as the introducing member forwards the addresses, they can substitute them with other addresses, performing <spandata-glossary="tooltip-mitm-attack"class="glossary-term">MITM attack</span> on the communication between existing and introduced members - this is similar to the communication operator being able to perform MITM on any connection between the users. To mitigate this attack this group sub-protocol will be extended to allow validating security of the connection by sending connection verification out-of-band.</p>
<p>Clients are RECOMMENDED to indicate in the UI whether the connection to a group member or contact was made directly or via annother user.</p>
<p>Each member in the group is identified by a group-wide unique identifier used by all members in the group. This is to allow referencing members in the messages and to allow group message integrity validation.</p>
<p>The diagram below shows the sequence of messages sent between the users' clients to add the new member to the group.</p>
<p>Currently members can have one of three roles - <code>owner</code>, <code>admin</code> and <code>member</code>. The user that created the group is self-assigned owner role, the new members are assigned role by the member who adds them - only <code>owner</code> and <code>admin</code> members can add new members; only <code>owner</code> members can add members with <code>owner</code> role.</p>
<h3id="messages-to-manage-groups-and-add-members"tabindex="-1">Messages to manage groups and add members</h3>
<p><code>x.grp.inv</code> message is sent to invite contact to the group via contact's direct connection and includes group member connection address. This message MUST only be sent by members with <code>admin</code> or <code>owner</code> role. Optional <code>groupLinkId</code> is included when this message is sent to contacts connected via the user's group link. This identifier is a random byte sequence, with no global or even local uniqueness - it is only used for the user's invitations to a given group to provide confirmation to the contact that the group invitation is for the same group the contact was connecting to via the group link, so that the invitation can be automatically accepted by the contact - the contact compares it with the group link id contained in the group link uri's data field.</p>
<p><code>x.grp.acpt</code> message is sent as part of group member connection handshake, only to the inviting user.</p>
<p><code>x.grp.mem.new</code> message is sent by the inviting user to all connected members (and scheduled as pending to all announced but not yet connected members) to announce a new member to the existing members. This message MUST only be sent by members with <code>admin</code> or <code>owner</code> role. Receiving clients MUST ignore this message if it is received from member with <code>member</code> role.</p>
<p><code>x.grp.mem.intro</code> messages are sent by the inviting user to the invited member, via their group member connection, one message for each existing member. When this message is sent by any other member than the one who invited the recipient it MUST be ignored.</p>
<p><code>x.grp.mem.inv</code> messages are sent by the invited user to the inviting user, one message for each existing member previously introduced with <code>x.grp.mem.intro</code> message. When this message is sent by any other member than the one who was invited by the recipient it MUST be ignored.</p>
<p><code>x.grp.mem.fwd</code> message is used by the inviting user to forward the invitations received from invited member in <code>x.grp.mem.inv</code> messages to all other members. This message can only be sent by the member who previously announced the new member, otherwise the recipients MUST ignore it.</p>
<p><code>x.grp.mem.info</code> this message is sent as part of member connection handshake - it includes group member profile.</p>
<p><code>x.grp.mem.role</code> message is sent to update group member role - it is sent to all members by the member who updated the role of the member referenced in this message. This message MUST only be sent by members with <code>admin</code> or <code>owner</code> role. Receiving clients MUST ignore this message if it is received from member with role less than <code>admin</code>.</p>
<p><code>x.grp.mem.del</code> message is sent to delete a member - it is sent to all members by the member who deletes the member referenced in this message. This message MUST only be sent by members with <code>admin</code> or <code>owner</code> role. Receiving clients MUST ignore this message if it is received from member with <code>member</code> role.</p>
<p><code>x.grp.leave</code> message is sent to all members by the member leaving the group. If the only group <code>owner</code> leaves the group, it will not be possible to delete it with <code>x.grp.del</code> message - but all members can still leave the group with <code>x.grp.leave</code> message and then delete a local copy of the group.</p>
<p><code>x.grp.del</code> message is sent to all members by the member who deletes the group. Clients who received this message SHOULD keep a local copy of the deleted group, until it is deleted by the user. This message MUST only be sent by members with <code>owner</code> role. Receiving clients MUST ignore this message if it is received from member other than with <code>owner</code> role.</p>
<p><code>x.grp.info</code> message is sent to all members by the member who updated group profile. Only group owners can update group profiles. Clients MAY implement some conflict resolution strategy - it is currently not implemented by SimpleX Chat client. This message MUST only be sent by members with <code>owner</code> role. Receiving clients MUST ignore this message if it is received from member other than with <code>owner</code> role.</p>
<h2id="sub-protocol-for-webrtc-audiovideo-calls"tabindex="-1">Sub-protocol for WebRTC audio/video calls</h2>
<p>This sub-protocol is used to send call invitations and to negotiate <spandata-glossary="tooltip-end-to-end-encryption"class="glossary-term">End-to-end encryption</span> keys and pass WebRTC signalling information.</p>
<p><code>x.call.inv</code>: the client initiating the call sends <code>x.call.inv</code> message in direct connection to invite another client to the call. At this point WebRTC session is not initialized yet, this message only contains call type and DH key for key agreement.</p>
</li>
<li>
<p><code>x.call.offer</code>: to accept the call, the receiving client sends <code>x.call.offer</code> message. This message contains WebRTC offer and collected ICE candidates. Additional ICE candidates can be sent in <code>x.call.extra</code> message.</p>
</li>
<li>
<p><code>x.call.answer</code>: to continue with call connection the initiating clients must reply with <code>x.call.answer</code> message. This message contains WebRTC answer and collected ICE candidates. Additional ICE candidates can be sent in <code>x.call.extra</code> message.</p>
</li>
<li>
<p><code>x.call.end</code> message is sent to notify the other party that the call is terminated.</p>
<divid="address-portability"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">Address portability</h1><divclass="overlay-content"><p>Similarly to <ahref="https://en.wikipedia.org/wiki/Local_number_portability">phone number portability</a> (the ability of the customer to transfer the service to another provider without changing the number), the address portability means the ability of a communication service customer to change the service provider without changing the service address. Many <ahref="#federated-network">federated networks</a> support SRV records to provide address portability, but allowing service users to set up their own domains for the addresses is not as commonly supported by the available server and client software as for email.</p></div><svgclass="close-overlay-btn"id="cross"width="16"height="16"viewBox="0 0 13 13"xmlns="http://www.w3.org/2000/svg"><pathd="M12.7973 11.5525L7.59762 6.49833L12.7947 1.44675C13.055 1.19371 13.0658 0.771991 12.8188 0.505331C12.5718 0.238674 12.1602 0.227644 11.8999 0.480681L6.65343 5.58028L1.09979 0.182228C0.805 0.002228 0.430001 0.002228 0.135211 0.182228C-0.159579 0.362228 -0.159579 0.697228 0.135211 0.877228L5.68885 6.27528L0.4918 11.3295C0.231501 11.5825 0.220703 12.0042 0.467664 12.2709C0.714625 12.5376 1.12625 12.5486 1.38655 12.2956L6.63302 7.196L12.1867 12.5941C12.4815 12.7741 12.8565 12.7741 13.1513 12.5941C13.4461 12.4141 13.4461 12.0791 13.1513 11.8991L12.7973 11.5525Z"></path></svg></div></div><divid="federated-network"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">Federated network</h1><divclass="overlay-content"><p>Federated network is provided by several entities that agree upon the standards and operate the network collectively. This allows the users to choose their provider, that will hold their account, their messaging history and contacts, and communicate with other providers' servers on behalf of the user. The examples are email, XMPP, Matrix and Mastodon.</p><p>The advantage of that design is that there is no single organization that all users depend on, and the standards are more difficult to change, unless it benefits all users. There are several disadvantages: 1) the innovation is slower, 2) each user account still depends on a single organization, and in most cases can't move to another provider without changing their network address – there is no <ahref="#address-portability">address portability</a>, 3) the security and privacy are inevitably worse than with the centralized networks.</p><p><ahref="https://en.wikipedia.org/wiki/Federation_(information_technology)">Federation on Wikipedia</a></p></div><svgclass="close-overlay-btn"id="cross"width="16"height="16"viewBox="0 0 13 13"xmlns="http://www.w3.org/2000/svg"><pathd="M12.7973 11.5525L7.59762 6.49833L12.7947 1.44675C13.055 1.19371 13.0658 0.771991 12.8188 0.505331C12.5718 0.238674 12.1602 0.227644 11.8999 0.480681L6.65343 5.58028L1.09979 0.182228C0.805 0.002228 0.430001 0.002228 0.135211 0.182228C-0.159579 0.362228 -0.159579 0.697228 0.135211 0.877228L5.68885 6.27528L0.4918 11.3295C0.231501 11.5825 0.220703 12.0042 0.467664 12.2709C0.714625 12.5376 1.12625 12.5486 1.38655 12.2956L6.63302 7.196L12.1867 12.5941C12.4815 12.7741 12.8565 12.7741 13.1513 12.5941C13.4461 12.4141 13.4461 12.0791 13.1513 11.8991L12.7973 11.5525Z"></path></svg></div></div><divid="anonymous-credentials"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">Anonymous credentials</h1><divclass="overlay-content"><p>The credential that allows proving something, e.g. the right to access some resource, without identifying the user. This credential can either be generated by a trusted party or by the user themselves and provided together with the request to create the resource. The first approach creates some centralized dependency in most cases. The second approach does not require any trust - this is used in SimpleX network to authorize access to the messaging queues.</p><p><ah
<li>double ratchet algorithm for <ahref="#end-to-end-encryption">end-to-end encryption</a> with <ahref="#forward-secrecy">perfect forward secrecy</a> and <ahref="#post-compromise-security">post-compromise security</a>,</li>
<li>additional layer of end-to-end encryption for each messaging queue and another encryption layer of encryption from the server to the recipient inside TLS to prevent correlation by ciphertext,</li>
<li>TLS with only strong ciphers allowed,</li>
<li>mitigation of <ahref="#man-in-the-middle-attack">man-in-the-middle attack</a> on client-server connection via server offline certificate verification,</li>
<li>mitigation of replay attacks via signing over transport channel binding,</li>
<li>multiple layers of <ahref="#message-padding">message padding</a> to reduce efficiency of traffic analysis,</li>
<li>mitigation of <ahref="#man-in-the-middle-attack">man-in-the-middle attack</a> on client-client out-of-band channel when sending the invitation,</li>
<li>rotation of delivery queues to reduce efficiency of traffic analysis,</li>
<li>etc.</li>
</ul><p><ahref="https://en.wikipedia.org/wiki/Defence_in_depth">Wikipedia</a></p></div><svgclass="close-overlay-btn"id="cross"width="16"height="16"viewBox="0 0 13 13"xmlns="http://www.w3.org/2000/svg"><pathd="M12.7973 11.5525L7.59762 6.49833L12.7947 1.44675C13.055 1.19371 13.0658 0.771991 12.8188 0.505331C12.5718 0.238674 12.1602 0.227644 11.8999 0.480681L6.65343 5.58028L1.09979 0.182228C0.805 0.002228 0.430001 0.002228 0.135211 0.182228C-0.159579 0.362228 -0.159579 0.697228 0.135211 0.877228L5.68885 6.27528L0.4918 11.3295C0.231501 11.5825 0.220703 12.0042 0.467664 12.2709C0.714625 12.5376 1.12625 12.5486 1.38655 12.2956L6.63302 7.196L12.1867 12.5941C12.4815 12.7741 12.8565 12.7741 13.1513 12.5941C13.4461 12.4141 13.4461 12.0791 13.1513 11.8991L12.7973 11.5525Z"></path></svg></div></div><divid="end-to-end-encryption"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">End-to-end encryption</h1><divclass="overlay-content"><p>A communication system where only the communicating parties can read the messages. It is designed to protect message content from any potential eavesdroppers – telecom and Internet providers, malicious actors, and also the provider of the communication service.</p><p>End-to-end encryption requires agreeing cryptographic keys between the sender and the recipient in a way that no eavesdroppers can access the agreed keys. See <ahref="#key-agreement-protocol">key agreement protocol</a>. This key exchange can be compromised via <ahref="#man-in-the-middle-attack">man-in-the-middle attack</a>, particularly if key exchange happens via the same communication provider and no out-of-band channel is used to verify key exchange.</p><p><ahref="https://en.wikipedia.org/wiki/End-to-end_encryption">Wikipedia</a></p></div><svgclass="close-overlay-btn"id="cross"width="16"height="16"viewBox="0 0 13 13"xmlns="http://www.w3.org/2000/svg"><pathd="M12.7973 11.5525L7.59762 6.49833L12.7947 1.44675C13.055 1.19371 13.0658 0.771991 12.8188 0.505331C12.5718 0.238674 12.1602 0.227644 11.8999 0.480681L6.65343 5.58028L1.09979 0.182228C0.805 0.002228 0.430001 0.002228 0.135211 0.182228C-0.159579 0.362228 -0.159579 0.697228 0.135211 0.877228L5.68885 6.27528L0.4918 11.3295C0.231501 11.5825 0.220703 12.0042 0.467664 12.2709C0.714625 12.5376 1.12625 12.5486 1.38655 12.2956L6.63302 7.196L12.1867 12.5941C12.4815 12.7741 12.8565 12.7741 13.1513 12.5941C13.4461 12.4141 13.4461 12.0791 13.1513 11.8991L12.7973 11.5525Z"></path></svg></div></div><divid="forward-secrecy"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">Forward secrecy</h1><divclass="overlay-content"><p>Also known as perfect forward secrecy, it is a feature of a <ahref="#key-agreement-protocol">key agreement protocol</a> that ensures that session keys will not be compromised even if long-term secrets used in the session key exchange are compromised. Forward secrecy protects past sessions against future compromises of session or long-term keys.</p><p><ahref="https://en.wikipedia.org/wiki/Forward_secrecy">Wikipedia</a></p></div><svgclass="close-overlay-btn"id="cross"width="16"height="16"viewBox="0 0 13 13"xmlns="http://www.w3.org/2000/svg"><pathd="M12.7973 11.5525L7.59762 6.49833L12.7947 1.44675C13.055 1.19371 13.0658 0.771991 12.8188 0.505331C12.5718 0.238674 12.1602 0.227644 11.8999 0.480681L6.65343 5.58028L1.09979 0.182228C0.805 0.002228 0.430001 0.002228 0.135211 0.182228C-0.159579 0.362228 -0.159579 0.697228 0.135211 0.877228L5.68885 6.27528L0.4918 11.3295C0.231501 11.5825 0.220703 12.0042 0.467664 12.2709C0.714625 12.5376 1.12625 12.5486 1.38655 12.2956L6.63302 7.196L12.1867 12.5941C12.4815 12.7741 12.8565 12.7741 13.1513 12.5941C13.4461 12.4141 13.4461 12.0791 13.1513 11.8991L12.7973 11.5525Z"></path></svg></div></div><divid="post-compromise-security"class="overlay glossary-overlay hidden"><divclass="overlay-card"><h1class="overlay-title">Post-compromise security</h1><divclass="overlay-content"><p>Also known as break-in recovery, it is the quality of the e
