Manage rooms

Introduction

Group discussions take place in rooms.

NOTE. Before you add a new room, you can create a space for it. For instructions, refer to Manage spaces.

Manage rooms

Create a room

The below instructions are about adding a new room to a space. If you want to start a one-to-one chat, refer to Find and invite your colleagues, instead.

  1. Navigate to the side bar on the left and right-click the space where you want to add a new room. Select Room. Editor and Doctave Desktop App

  2. Enter the name and topic of your room. The topic is optional. Editor and Doctave Desktop App

  3. Open the drop-down menu to select the visibility setting of your room:

    • Visible to space members. Everyone in the space will be able to find and join your room.

    • Private room. Only people invited will be able to find and join your room.

    • Public room. Anyone will be able to find and join your room.

      NOTE. You can change these settings later. Editor and Doctave Desktop App

  4. A. If your room is visible to space members or a private room, click the toggle to enable or disable end-to-end encryption. Editor and Doctave Desktop App

    NOTE. You cannot disable this later. Bridges and most bots will not work yet.

    B. If your room is a public room, enter a room address for you room. Editor and Doctave Desktop App

  5. For advanced settings, select Show advanced.

    Under the advanced settings, you can block anyone who is not part of the same server from ever joining your room. You can enable this setting if the room is only used for collaborating with internal teams on your homeserver.
    Click the toggle to enable or disable this setting.

    NOTE. This setting cannot be changed later. Editor and Doctave Desktop App

  6. Finish by selecting Create room. Editor and Doctave Desktop App

Add an existing room

Instead of creating a new room, you can also add an already existing room to your space.

  1. Navigate to the side bar on the left and click the space where you want to add an existing room.

  2. Click the + icon at the top and select Add existing room. Editor and Doctave Desktop App

  3. Select the room(s) that you want to add from the list. You can also use the search bar to search for rooms.

  4. Finish by selecting Add. Editor and Doctave Desktop App

Share a room

NOTE. If the room is private, the user needs an invitation from the room admin to join the room.

  1. Click the info icon at the top right corner of the chat. Editor and Doctave Desktop App

  2. Select Share room. Editor and Doctave Desktop App

    There are several ways to share the room:

    • Copy the link. Select the Link to most recent message checkbox if you want to share a link to the most recent message in the room.

    • Share the link on social media. Share the link on Facebook, X, LinkedIn, and Reddit.

    • Share the link via email.

    • Share a QR code. Right-click the QR code to copy or save the image. Editor and Doctave Desktop App

Remove a room

  1. Navigate to the side bar and click the space where the room is located. Editor and Doctave Desktop App

  2. In the middle panel, select the room that you want to remove and click Remove. Editor and Doctave Desktop App

Join a public room

  1. Select Home from the side bar.

  2. Click the + icon at the top and select Join public room. Editor and Doctave Desktop App

    You can scroll the list of suggested public rooms or use the search bar to search for them. Editor and Doctave Desktop App

    You can even search for public rooms in other servers. To open the server list, click the drop-down menu at the right side of the window. Editor and Doctave Desktop App

    Select View to preview a public room before joining. If you want to join the room, select Join the discussion at the bottom of the room.

    Select Join to join a public room.

Leave a room

  1. Navigate to the side bar and click the space where the room is located.

  2. Click the three dots next to the room and select Leave. Editor and Doctave Desktop App

    NOTE. If you are the only person in the room, no one will be able to join it in the future, including you.

  3. Confirm by reselecting Leave. Editor and Doctave Desktop App

Add a room to favorites

  1. Navigate to the side bar and click the space where the room is located.

  2. Click the three dots on the room and select Favorite. Editor and Doctave Desktop App

    The room appears under the Favorites tab. Editor and Doctave Desktop App

    To remove a room from favorites, select Favorited. The room disappears from the Favorites tab and reappears under the Rooms tab.

Manage room settings

There are two ways to access the room settings:

  • From the left panel: Editor and Doctave Desktop App
  • From the info tab: Editor and Doctave Desktop App

Change room name, topic and picture

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Under the General tab, enter the new name, topic, and picture of the room. Editor and Doctave Desktop App
  4. Finish by selecting Save. Editor and Doctave Desktop App

Manage URL previews

URL previews in messages give more information about the shared link, such as the title, description, and image from the website.

In encrypted rooms, URL previews are disabled by default. This is to make sure that your homeserver can't gather information about the links you see in rooms.

To enable or disable URL previews:

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Under the General tab, scroll down to Other and URL Previews, and click the toggle to enable or disable URL previews.
    NOTE. This affects only you. Editor and Doctave Desktop App

Change encryption settings

NOTE. Once enabled, encryption cannot be disabled.

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Go to the Security & Privacy tab. Editor and Doctave Desktop App
  4. NOTE. Once enabled, encryption cannot be disabled. If you did not enable encryption when you created this room, you can enable it here. Editor and Doctave Desktop App Click the toggle to enable or disable sending encrypted messages to unverified devices in this room from this device. The default setting: off Editor and Doctave Desktop App

Define who can join your room

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Go to the Security & Privacy tab. Editor and Doctave Desktop App
  4. Under Access, select who can join your room. Editor and Doctave Desktop App

Define who can read room history

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Go to the Security & Privacy tab. Editor and Doctave Desktop App
  4. Under Who can read history?, select the members who can read room history. Editor and Doctave Desktop App

Edit privileged user roles

  1. Navigate to the side bar and click the space where the room is located.

  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App

  3. Go to the Roles & Permissions tab. Editor and Doctave Desktop App

  4. Under Privileged Users, click the privileged user whose role you want to to edit.

    You can select from the following roles:

    • Admin. Can do all administrative tasks in the room.
    • Moderator. Can do some administrative tasks in the room.
    • Default. No administrative tasks in the room.

Add privileged users

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Go to the Roles & Permissions tab. Editor and Doctave Desktop App
  4. Under Add privileged users, enter the user into the search field. Editor and Doctave Desktop App
  5. Open the drop-down menu to select the role. You can select from the following roles:
    • Admin. Can do all administrative tasks in the room. NOTE. You can't undo this change as you are promoting the user to have the same role as you.
    • Moderator. Can do some administrative tasks in the room.
    • Default. No administrative tasks in the room.
      Editor and Doctave Desktop App
  6. Finish by selecting Apply. Editor and Doctave Desktop App

Change notification settings

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the Notification options icon on the room. You can choose from the following options:
    • Match default setting. Matches the default notification settings of your account. For more information, refer to Manage your settings > Change notification settings.
    • All messages. Show all notifications.
    • Mentions & keywords. Show a notification when someone mentions you or uses keywords.
    • Mute room. Mute all notifications from this room. Editor and Doctave Desktop App

Set a custom notification sound

  1. Navigate to the side bar and click the space where the room is located.
  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App
  3. Go to the Notifications tab. Editor and Doctave Desktop App
  4. Click Browse to select a custom sound.
  5. Finish by selecting Save. Editor and Doctave Desktop App

View room information

  1. Navigate to the side bar and click the space where the room is located.

  2. Click the three dots on the room and select Settings. Editor and Doctave Desktop App

  3. Go to the Advanced tab. Editor and Doctave Desktop App

    You can copy the internal room ID and view the room version. Editor and Doctave Desktop App

Manage room members

Invite a user

  1. Navigate to the side bar and click the space where the room is located.

  2. Click the three dots on the room and select Invite. Editor and Doctave Desktop App

  3. Enter a name, email address, or username into the text field. Users that are already using Secure Messaging appear on the Suggestions list below.

    NOTE. Some suggestions may be hidden for privacy. Editor and Doctave Desktop App

  4. A. If the user is on the list, click it and select Invite.

    Editor and Doctave Desktop App

    B. If you can't find the user on the list, you can share the room with them. Click share this room and follow the instructions.

    Once the user receives the invitation, they have three options to choose from:

    • Accept. The user accepts the invitation and joins the room.
    • Reject and ignore user. The user rejects the invitation and ignores the user. The user can no longer invite the user to a room.
    • Reject. The user rejects the invitation.

Revoke invitation

  1. Click the info icon at the top right corner of the chat. Editor and Doctave Desktop App

  2. Select Direct messages. Editor and Doctave Desktop App

  3. Under Invited, click the user whose invitation you want to revoke.

  4. Under Admin tools, select Revoke invite. Editor and Doctave Desktop App

Remove a user

  1. Click the room.
  2. Click the info icon at the top right corner of the room. Editor and Doctave Desktop App
  3. Select Direct Messages. Editor and Doctave Desktop App
  4. Click the user who you want to remove.
  5. Under Admin tools, select Remove from room. Editor and Doctave Desktop App
  6. Type in the reason, if necessary, and select Remove from room.

Ignore a user

Ignoring a user hides all messages and invites from them.

  1. Click the room.

  2. Click the info icon at the top right corner of the room. Editor and Doctave Desktop App

  3. Select Direct Messages. Editor and Doctave Desktop App

  4. Click the user who you want to ignore.

  5. Under Options, select Ignore. Editor and Doctave Desktop App

  6. Confirm by reselecting Ignore. Editor and Doctave Desktop App

    To unignore a user, select Unignore.

Mute a user

Muting a user prevents them from posting to the room. However, they can still see the room.

  1. Click the room.

  2. Click the info icon at the top right corner of the room. Editor and Doctave Desktop App

  3. Select Direct Messages. Editor and Doctave Desktop App

  4. Click the user who you want to mute.

  5. Under Admin tools, select Mute. Editor and Doctave Desktop App

    To unmute a user, select Unmute.

Ban a user

Banning a user bans them from the room. They can no longer see the room or join the conversation.

  1. Click the room.

  2. Click the info icon at the top right corner of the room. Editor and Doctave Desktop App

  3. Select Direct Messages. Editor and Doctave Desktop App

  4. Click the user who you want to ban from the room.

  5. Under Admin tools, select Ban from room. Editor and Doctave Desktop App

    To unban a user, select Unban from room.

Remove a user's recent messages

Removing a user's recent messages removes messages sent by that user permanently for everyone in the conversation. For a large amount of messages, this might take some time. Do not refresh the client in the meantine.

  1. Click the room.

  2. Click the info icon at the top right corner of the room. Editor and Doctave Desktop App

  3. Select Direct Messages. Editor and Doctave Desktop App

  4. Click the user whose messages you want to remove.

  5. Under Admin tools, select Remove recent messages. Editor and Doctave Desktop App

  6. Check the Preserve system messages option if you don't want to remove system messages, such as membership changes and profile changes, on this user. Editor and Doctave Desktop App

    Uncheck the option if you want to remove all messages on this user, including the system messages.

  7. Finish by selecting Remove [X] message(s). Editor and Doctave Desktop App

Adding Integrations/Bots

SSH Secure Messaging has several bots and integrations that can be added to rooms. These bots and integrations must be setup and configured by a system administrator with access to the SSH Secure Messaging backend and the third-party service which the bot may be interacting with. Once these integrations have been enabled, they will appear as user accounts and can be added to the room by inviting the user account.

Interaction with these bots typically involves using the "!" mark followed by the bot name and the bot command, for example:

!botname <command>

All bots have a help menu that lists the bot commands and room-specific configurations. You can view the help menu by using the following command:

!botname help

Jira Integration

The Jira integration connects a Jira DC or Jira Cloud instance to the SSH Secure Messaging platform, allowing users to view and interact with Jira tickets seamlessly. To get started with the Jira integration, invite the Jira bot to the required room. The bot should then automatically accept the invite and join the room. Once the bot is in the room, configure it to follow a specific Jira project using the following command:

!jira follow <project name>

The bot allows you to follow multiple projects in the same room. You can list all the projects that are currently being followed using the following command:

!jira list

To unfollow a project, use the following command:

!jira unfollow <project name>

To unfollow all projects and disable new notifications, use the following command:

!jira unfollow all

Jira Ticket Notifications

Once configured to follow a project, the bot will automatically check for updates and post notifications to the room for the following events:

  • New Jira issue created
  • New comment on a Jira issue
  • Jira issue description updated

Comments Sync

By default, comments are synced both ways. This means if you get a new Jira ticket update in your Secure Messaging room, you can reply in a thread to that message, and your comment will sync to Jira as well.

Jira Ticket Finder

When a user writes a message containing a Jira issue key in the chat, the bot will attempt to find and post that ticket to the same room. If it cannot find the issue or doesn't have access, it will remain silent. The same ticket can only be pulled once per 60 seconds to prevent spam.

Per Room Configuration

The bot has various settings specific to the room it's running in. These settings control the bot behavior, such as fine-tuning notifications or enabling and disabling features. To view the default settings, use the following command:

!jira config list

For more information about the bot's functionality and features, check the bot help menu:

!jira help

Jenkins Integration

The Jenkins integration provides an easy way to get notifications for build events. Once the bot is set up by a system administrator to integrate to a Jenkins instance, invite the bot user to the required room and list all available pipelines:

!jenkins list-available

This command will list all available pipelines that can be followed. To follow a pipeline, use the following command:

!jenkins follow <pipeline name>

The bot allows you to follow multiple pipelines in the same room. You can list all the pipelines that are currently being followed using the following command:

!jenkins list

To unfollow a pipeline, use the following command:

!jenkins unfollow <pipeline name>

After following a pipeline, the bot will automatically track it and post notifications to the room when a build has finished. The status message will contain the following information:

  • Build event information

  • Commit messages and hashes

  • Artifacts and their download links

Gitlab Integration

The Gitlab integration allows you to set up the bot to follow a specific Gitlab project for notifications. These notifications may include push events, merge requests, new issues, build events, etc. These events can be configured and fine-tuned in the Gitlab integration settings. The bot can also follow multiple Gitlab projects from different instances simultaneously.

To get started, invite the bot to the desired room and configure a Webhook for the bot to listen to and for Gitlab to send notifications to:

!gitlab webhook add

The bot will send a private message containing the following details:

  • Webhook type
  • API key
  • Webhook endpoint
  • Room ID where the webhook has been set up

Then, head to Gitlab -> Project -> Settings -> Integrations -> And fill the following information: URL -> Webhook endpoint Secret Token -> Webhook API key

Then choose which events this webhook should trigger on and click add webhook.

Note: The behavior of the Gitlab test event button may not work correctly; therefore, not all notifications will be reported when you click the test button. However, all real events should be supported.

Note: Once a webhook is set up, the API key is only sent once. This is because the bot itself is not aware of the API key after it is sent; only a hashed version of the key is kept to verify the key's validity. This means that the key is only known to the person who set up the integration.

To remove the webhook from the room, use the following command:

!gitlab webhook remove

Github Integration

The Github integration allows you to set up the bot to follow a specific Github project for notifications. These notifications may include push events, merge requests, new issues, build events, etc. These events can be configured and fine-tuned in the Github integration settings. The bot can also follow multiple Github projects from different instances simultaneously.

To get started, invite the bot to the desired room and configure a webhook for the bot to listen to and for Github to send notifications to:

!github webhook add

The bot will send a private message containing the following details:

  • Webhook type
  • API key
  • Webhook endpoint
  • Room ID where the webhook has been set up

Then, head to Github -> Project -> Settings -> Webhooks -> Add webhook -> Fill in the following settings:

  • Payload URL -> Webhook endpoint
  • Content Type -> application/json
  • Secret -> Webhook API key Then select which events you want this Webhook to trigger and click on add webhook. Once added, the bot should send a message to the room confirming that it has been added successfully.

To remove the webhook from the room, use the following command:

!github webhook remove

Webhooks Bot

The Webhooks bot allows any third-party service to send Webhook events to SSH Secure Messaging via a simple REST API. To configure the bot, invite the bot to the desired room and configure a webhook:

!webhook add

The bot will send a private message containing the following details:

  • Webhook type
  • API key
  • Webhook endpoint
  • Room ID where the webhook has been set up

Note: Once a Webhook is set up, the API key is only sent once. This is because the bot itself is not aware of the API key after it is sent; only a hashed version of the key is kept to verify the key's validity. This means that the key is only known to the person who set up the integration.

You can then test the Webhook by making a simple POST request to that endpoint:

curl -X POST <webhook endpoint> -H "Content-Type: application/json" -H "Authorization: Bearer <API key>" -d 'Hello World'

Furthermore, this bot supports HTML formatted messages by using the URL parameter html=true in the webhook endpoint. Example:

curl -X POST http://bot-url/webhook/room_id/generic?html=true -H "Content-Type: application/json" -H "Authorization: Bearer <API key>" -d 'Hello World'

If you need to retrieve the Webhook information again, use the following command:

!webhook get

However, note that you won't be able to retrieve the API key. If you lose the API key, there is no way to recover it. The only solution is to regenerate it by removing and re-adding the webhook. The webhook can be removed with the following command:

!webhook remove

Was this page helpful?