Skip to content
All technical docs Bricks technical documentation

Private messages: Matrix behind BricksID

How people write to each other through BricksID over Matrix, how an organisation creates rooms for its people and links to conversations from its application, and what each party can see.

Private messages: Matrix behind BricksID

Bricks Technical Documentation

How people write to each other through BricksID over Matrix, how an organisation creates rooms for its people and links to conversations from its application, and what each party can see.


1. What it is

People write to each other in BricksID, the identity they already use on every Bricks application. All their conversations sit in one place, at /account/messages: conversations between two people, and the rooms an organisation created for them.

Conversations run on Matrix, an open protocol with end-to-end encryption. Bricks runs its own Matrix server, and BricksID is the only way into it:

  • No sign-up and no second password. The chat account is created the first time a person opens their messages, by their own action. An organisation's invitation never creates one.
  • No consent screen. Opening messages from BricksID goes straight to the conversations.
  • Standard Matrix apps work too. A person may use any Matrix app from an app store; it signs them in through BricksID, onto the same account.

Messages are switched on platform by platform. Where they are not, the rooms endpoint answers 404 messages.not_configured, the room nodes fail with an explicit error, and BricksID shows no messages screen.

2. Who can read what

Messages are encrypted on the sender's device before they leave it, and decrypted only on the devices of the people in the conversation.

Message text and files Who is in which conversation, and when they wrote
The organisation Never Only for the rooms it created: that the room exists and whom it invited
Bricks, as the operator Stored only encrypted Stored in clear on the chat server, as Matrix requires
Your application's database Never Never

Two facts are stated as they are:

  • Each person chooses where their message keys are kept, in BricksID under Security › Messages: only on their devices, or also in an encrypted backup whose key BricksID keeps. The backup lets a new device, or the same browser after signing out, recover the history from BricksID sign-in alone. With the backup, Bricks could technically read their messages; the screen says so.
  • Bricks runs the server and serves the BricksID pages, so Bricks could technically add a device to an account. Every device that can read is registered on the chat server, where a standard Matrix app lists it; BricksID does not list them yet (see the limits).

The Data Protection Notice describes what is kept and for how long.

3. Chat ids

A person's Matrix id is @<BricksID user id>:<server name>, for example @05394343-dc83-4c58-b320-3a56fb9c8f93:bricks-softwares.com. It is opaque to other people and never contains an email address. The display name is the person's name in BricksID.

Your application never needs the Matrix id: it works with BricksID user ids, the sub it already receives at sign-in.

4. Opening a conversation from your application

A plain link, no library:

To open Link
A conversation with a person <BricksID>/account/messages?with=<BricksID user id>
One of your organisation's rooms <BricksID>/account/messages?room=<room id>
All of the person's conversations <BricksID>/account/messages

<BricksID> is the address your application already uses for sign-in. Open the link from a click (a new tab or a full-page navigation). If the person you link to has never opened their messages, BricksID says so; they can be written to once they have.

Show the button only next to a person the user already sees in your application, and never on the user themselves.

5. Your organisation's rooms

An organisation creates rooms for its people with three workflow nodes. They run like any other node, so the Studio can build them from a plain request ("a room for each team").

Node What it does
action-room-ensure Creates, or finds, the room for a stable key, with a name, and invites invite (BricksID user ids). Returns roomId, key, created and an outcome per person
action-room-invite Invites more people to the room for a key
action-room-remove Removes people from the room for a key; only rooms your organisation created
{
  "id": "room",
  "type": "action-room-ensure",
  "data": {
    "key": "circle:family",
    "name": { "en": "Family", "fr": "Famille" },
    "invite": "{{ $node.members.ids }}"
  }
}

Rules the platform enforces, whatever the workflow says:

  • Rooms are encrypted. They are grouped in your organisation's space on the chat server.
  • Only BricksID people who hold a role in your organisation are invited. Every other id comes back with its own outcome; nothing is dropped silently.
  • The rooms are created by a platform account that has no device: it can create rooms and change who is in them, never read or post.
  • People join from BricksID, where they accept or decline. History is visible from the moment someone joins.
  • Your organisation's schema stores no room and no message. The platform keeps which room belongs to which organisation and key.

Outcomes per person: invited, waiting, already, not_member, invalid, not_in_room (remove only), removed (remove only), failed.

waiting means the person has never opened their messages. No chat account is created for them. BricksID sends them a notification (" invites you to ") that opens the invitation, and the invitation becomes an ordinary one when they first open their messages. Do not add a notification of your own for this.

Listing rooms in your application

GET /v2/tenants/<tenantId>/messages/rooms
Authorization: Bearer <the signed-in person's access token>
{
  "rooms": [
    {
      "roomId": "!lHYYK10jvKZiZ8hjM1qyLXCd60Xyhadxhg1lzWO_UBA",
      "key": "circle:family",
      "name": { "en": "Family", "fr": "Famille" },
      "membership": "join",
      "url": "https://bricks-softwares.com/account/messages?room=!lHYYK10jvKZiZ8hjM1qyLXCd60Xyhadxhg1lzWO_UBA"
    }
  ]
}

Only the rooms the caller is in (join) or invited to (invite) are listed, never others, not even by name. The caller must be a member of the organisation. An integrator key is refused: this answers for a signed-in person.

6. Notifications

New messages reach people through BricksID notifications, on the devices where they allowed them. A notification says "New private message", or "New message in " for an organisation's room, and opens the conversation. It never contains the text, nor who wrote it. A person who muted your organisation in BricksID is not notified for its rooms.

7. Showing conversations inside your application

Bricks ships no chat library for applications, and none is needed for the links and rooms above. An application that wants to show conversations inside its own screens can use a Matrix library it chooses. Its code then decrypts what the person reads there, so that code can read those messages: decide it knowingly, and say it in your own notice.

8. Today's limits

  • Messages are not yet switched on for every platform: check for 404 messages.not_configured.
  • Federation with other Matrix servers is off: people write to other people on the same Bricks platform.
  • A person who keeps their keys only on their device and uses a shared computer should clear the site's data after use; the backup option removes the keys from the browser at sign-out.
  • Notification texts exist in English and French.
  • BricksID does not yet list the devices that can read a person's messages, nor announce a new one; a standard Matrix app shows them.